WRLD.time - Class Documentation

Class Documentation how to use the WRLD.time classes in a safe & effective manner

once you've acquired the WRLD.time classes, the documenation below should help you leverage your chronological solution. furthermore, i promise i will not use the word 'leverage' again within the confines of the documentation.

WRLDtimeNow	command-line access to the WRLD.time chronometer
WRLDtimeApplet	the applet which drives a WRLDtimePiece
WRLDtimeApp	the command-line application which drives a WRLDtimePiece
WRLDtimePiece	an abstract class for creating a WRLDtimePiece
WRLDcron	the WRLD.time chronometer

Contents Previous Next WRLDtimeNow

A simple command-line app which uses WRLDcron to return the current WRLD.time. The current time is always returned in the format "XX.XX"... the 2-digit measure, a period separator, then the 2-digit beat.

It takes 2 optional parameters:

host: adddress for a UTC host... optional
If provided, app uses UTC to increase accuracy of response
port: port for a UTC port... optional
If provided, indicates the UTC socket port (defaults to 13)

The command-line app does not support referencing a CGI script. That's because there aren't same security hobbing issues from the command line as there are in applet.

Contents Previous Next WRLDtimeApplet

An applet that surrounds a WRLD.time time-piece. Create a new time-piece, compile it, attach it to your document like so and... voila!

Now... it's not totally generic. Besides making a time-piece that implements the WRLDtimePiece class, you'll have to call the class WRLDtime, because that's what the applet wrapper expects. Still figurin' this stuff out, you know.

Oh... heh. And if you run the applet anywhere other than sleepbot.com, you get the 25-pixel-high black logo bar at the bottom.

Here's what methods it calls, and when it calls them:

init(): invokes the constructor and init(WRLDcron, Applet).
start(): invokes start(WRLDcron).
run(): checks isLoaded() before choosing how to wait, invokes waiting(WRLDcron) while waiting for the update, and invokes tick(WRLDcron) when the update completes.
update(): checks isPaintable().
paint(): checks isPaintable() before invoking paint(Graphics).
stop(): invokes stop(WRLDcron).
destroy(): invokes destroy().

Contents Previous Next WRLDtimeApp

A command-line app that surrounds a WRLD.time time-piece. Create a new time-piece, compile it, and it runs merrily from your desktop!

Now... it's not totally generic. Besides making a time-piece that implements the WRLDtimePiece class, you'll have to call the class WRLDtime, because that's what the application wrapper expects. Also, the WRLDtimeApp class requires the WRLDtimeFrame class, so don't be going around deleting it an' shit.

The version of WRLDtimeApp provided with the class files has a parameter. More information on that over here.

Here's what methods it calls, and when it calls them:

main(): invokes the constructor and init(WRLDcron, Frame, String[][]).
start(): invokes start(WRLDcron).
run(): checks isLoaded() before choosing how to wait, invokes waiting(WRLDcron) while waiting for the update, and invokes tick(WRLDcron) when the update completes.
update(): checks isPaintable().
paint(): checks isPaintable() before invoking paint(Graphics).
stop(): invokes stop(WRLDcron).
handleEvent(): invokes stop(WRLDcron) and destroy() when the window is closed.

Contents Previous Next WRLDtimePiece

An abstract class which defines everything you'll need to create a custom WRLD.time time-piece. It works in tandem with WRLDtimeApp and WRLDtimeApplet to make really cool-ass shit.

In the standard implementation, the time-piece class (called WRLDtime) needed two other classes to be around, WRLDglyph and WRLDconfig. They are specific to the standard implementation and can be deleted from your own personal class set.

abtract public void destroy()

This routine is called by the owner just before it destroys itself. Might want to clean up after yourself

abtract public void init(WRLDcron cron, Applet a): cron - a WRLDcron object which has been created by the applet.
a - the Applet itself

This routine is called by the owning applet (generally WRLDtimeApplet) during its own init() routine. Generally that happens once, when the applet is first loaded into the browser. This'd be a good time to set up those instance variables, allocate dynamic storage and the like.

abtract public void init(WRLDcron cron, Frame f, String[] args): cron - a WRLDcron object which has been created by the applet.
f - the Frame itself
args - the command line arguments for the application, in case you want them

This routine is called by the owning frame in an application (generally the one created in WRLDtimeApp). It happens once, when the application first starts. This'd be a good time to set up those instance variables, allocate dynamic storage and the like.

abtract public boolean isLoaded(): returns true if you're fully loaded, false if not

This routine is called when the owner needs to know if you've fully loaded all your images & stuff. If you say 'false', it will perform patient ticks rather than dedicated ones (ie. less accuracy)

abtract public boolean isPaintable(): returns true if you're ready for a painting, false if not

This routine is called when the owner needs to know if you're ready to paint yourself or not. If you say 'false', it'll put up the standard "WRLD.time" logo instead.

abtract public void paint(Graphics g, Dimension d): g - a Graphics object for drawing
d - the Dimension of the display area

This routine is called when the owner wants you to paint yourself.

abtract public void start(WRLDcron cron): cron - a WRLDcron object which has been created by the applet.

This routine is called by the owner just before its thread starts up. In an application, it's called just after init(). In an applet, it's every time you refresh the page. Good point for other pre-run preparations.

abtract public void stop(WRLDcron cron): cron - a WRLDcron object which has been created by the applet.

This routine is called by the owner just before it stops. In an application, it's called just before termination. In an applet, it's every time you leave the page. Basically, stop doing what you were doing.

abtract public void tick(WRLDcron cron): cron - a WRLDcron object which has been created by the applet.

This routine is called when the owner's chronometer has been incremented. Do whatever you need to do to prepare yourself accordingly.

abtract public void waiting(WRLDcron cron): cron - a WRLDcron object which has been created by the applet.

This routine is called within the owner's inner time-keeping loop. If there's anything you need to do while waiting, here's where to do it.

Contents Previous Next WRLDcron

A WRLD.time chronometer. It does everything I could imagine a chronometer object would want to do. The ones you'd probably use most are the constuctor, setDate(Date) and getTime()

Alright. So you want to know what these variables really mean in the big scheme of things. Well, since this is documentation, I'll tell you...

adjust: any other miscellaneous adjustment, but this one is in seconds.
By default, this is 0. If you know your computer's clock is 5 minutes off, set this to 300 and it'll work fine. or FIX YOUR CLOCK! You're most likely to set this indirectly via a UTC server.
divisor: how to divide the beats from the measures.
By default, WRLD.time has 100 beats per measure... turns out there's also 100 measures because of the factor. A 24-hour clock would have a divisor of 60, since there are 60 beats (minutes) for every measure (hour).
factor: the number of seconds in one 'tick'.
A 24-hour clock, whose 'tick' is one minute, would have a factor of 60, since there's that many seconds in a minute. Keep in mind that this chronometer can only measure 2 chunks of time.
fromGMT: how many minutes from GMT the chronometer is aligned to (ie. a timezone simulator, without DST).
By default, WRLD.time is aligned to GMT+12, which is the International Date Line. It lies between Kamchatka and Alaska on your standard RISK(tm) board.
patience: indicates how accurate you want to be during patient waiting.
By default, WRLD.time is willing to be patient to an accurace of 1/100 of a tick (.01).

Note that the chronometer can only internally maintain 4 unique digits, two for beat and two for measure. If you end up with more precision than that, you'll have to mainipulate the raw beats & measures yourself.

This implementation is even capable of displaying that 24-hour clock i've used as example. Pretty neato, huh? jonathan recently sent me specs on two Indian standards of time which could be just as easily represented with this chronometer.

public WRLDcron()

The constuctor... it creates a new, initialized chronometer and calculates WRLD.time for 'now'.

public synchronized Object clone()

Creates a duplicate of myself, all my conversion values and my current time.

public long getAdjust(): returns the current adjustment for the chronometer

The adjust is any other miscellaneous adjustment, but this one is in seconds (vs. minutes in fromGMT). By default, this is 0. If you know your computer's clock is 5 minutes off, set this to 300 and it'll work fine. or FIX YOUR CLOCK! You're most likely to set this indirectly via a UTC server.

public long getBeat(): returns the beat of the current converted time for the chronometer

By default, the beat of WRLD.time ranges from 0 to 99. the beat of a 24-hour clock would range from 0 to 59

public int getBeatLength(): returns the length, in characters, of the a full beat.

By default, the beat length of WRLD.time is 2.

public Date getDate()

Gets the last date that the chronometer converted

public int getDivisor(): returns the current divisor for the chronometer

The divisor indicates how to divide the beats from the measures By default, WRLD.time has 100 beats per measure... turns out there's also 100 measures because of the factor A 24-hour clock would have a divisor of 60, since there are 60 beats (minutes) for every measure (hour)

public double getFactor(): returns the current factor for the chronometer

The factor is the number of 'ticks' in one second. A 24-hour clock would have a factor of 60, since there's that many seconds in a minute. Keep in mind that this chronometer can only measure 2 chunks of time.

public long getFromGMT(): returns the current GMT offset for the chronometer

FromGMT is how many minutes from GMT the chronometer is aligned to (ie. a timezone simulator, without DST) By default, WRLD.time is aligned to GMT+12, which is the International Date Line It lies between Kamchatka and Alaska on your standard RISK(tm) board.

public long getMeasure(): returns the measure of the current converted time for the chronometer

By default, the measure of WRLD.time ranges from 0 to 99. the measure of a 24-hour clock would range from 0 to 23

public int getMeasureLength(): returns the length, in characters, of a full measure.

By default, the measure length of WRLD.time is 2.

public double getPatience(): returns the current patience for the chronometer

The patience indicates how accurate you want to be during patient waiting (ie. waitForUpdatePatiently()) By default, WRLD.time is willing to be patient to an accurace of 1/100 of a tick (.01).

public long getTime(): returns the current converted time for the chronometer

By default, WRLD.time ranges from 0 to 9999. a 24-hour clock would range from 0 to 1440

public int getTimeLength(): returns the length, in characters, of a full time code (measure & beat).

By default, the time length of WRLD.time is 4.

public boolean isUpdated()

Indicates whether the chronometer has received its 'tick'. You'd ask this if you were waiting for the update in a loop of your own.

public synchronized void setAdjust(long adj): adj - the new adjustment (see above)

Sets the current adjustment for the chronometer

public synchronized void setAdjustByUTC(String utcHost, int utcPort) throws SocketException: utcHost - the UTC host
utcPort - the UTC port

Sets the current adjustment for the chronometer using a UTC code provided by a host:port combination

Over here i've put a list of known UTC sites. The UTC protocol is usually served from port 13

public synchronized void setAdjustByUTC(URL utcCgi) throws SocketException: utcCgi - a reference to the CGI script

Sets the current adjustment for the chronometer using a UTC code provided by a CGI script A little perl script which opens a socket to a UTC host:port should do the trick.

public synchronized void setAdjustByUTC(String line) throws NumberFormatException: line - a valid UTC code

Sets the current adjustment for the chronometer using a UTC code

The following is the format of a UTC code

JJJJJ YR-MO-DA HH:MM:SS TT L UT1 msADV UTC(NIST) OTM

Since this is a dateless chronometer, ony the HH:MM:SS is important here. For much more detailed information on the UTC format, please see http://www.bldrdoc.gov/timefreq/.

public synchronized void setDate()

Converts the current date via the chronometer

public synchronized void setDate(Date nowDate): nowDate - the date to convert into the chronometer's time

Converts the requested date via the chronometer

public synchronized void setDivisor(int div): div - the new divisor (see above)

Sets the current divisor for the chronometer

public synchronized void setFactor(double fct): fct - the new factor (see above)

Sets the current factor for the chronometer

public synchronized void setFromGMT(long gmt): gmt - the new offset (see above)

Sets the current GMT offset for the chronometer

public synchronized void setPatience(double pat): pat - the new patience (see above)

Sets the current patience for the chronometer

public void startPatientUpdate()

Starts the 'tick' update process by creating a patient update thread. Very similar to startUpdate() (see above), but it allows for more external processing.

public void startUpdate()

Starts the dedicated 'tick' update process by creating an update thread. This causes the run() routine to wait for the next tick.

public void stopUpdate()

Stops the 'tick' update process in its tracks.

public void waitForUpdate()

Wait with bated breath (ie. yeilding) until the next 'tick'. This takes control of the active thread and dedicates it to giving as accurate a result as possible

public void waitForUpdatePatiently()

Wait patiently (ie. sleeping) until the next 'tick'. This takes control of the active thread but gives others plenty of time to work in exchange for a loss of accuracy

public void waitPatiently() throws InterruptedException

Wait as patiently as the chronometer should. You'd ask this if you were patiently waiting for the update in a loop of your own.

WRLD.time
a fine global temporal standard

Sleepbot Constructs