Sleepbot.com Java Classes

com.sleepbot.WRLDtime.cron
Class WRLDcron

java.lang.Object
  extended bycom.sleepbot.WRLDtime.cron.WRLDcron
All Implemented Interfaces:
java.lang.Cloneable, java.lang.Runnable

public class WRLDcron
extends java.lang.Object
implements java.lang.Runnable, java.lang.Cloneable

The WRLD.time chronometer logic.
 
It's a generic class based on the idea of there being two components to any time code:

This class converts a conventional time code according to your specifications: NOTE: As flexible as it is, this class is not capable of displaying sub-minute precision for a conventional (eg. hour:minute) time code. That's because a conventional time code has a 24:60:60:10* cycle. Specifically; 24 hours in a day, 60 minutes in an hour, 60 seconds in a minute, and arbitrary sub-second decimal precision. This class can easily perform the 24-hour:60-minute split, but beyond that, it's simply decimal. Try it out for yourself and you'll see what I mean (since things could only get more confusing if I just kept blabbing on). Of course, this isn't a problem for any metric time system -- eg. WRLD.time -- because they're 100% decimal (by definition).
 
For more information, please see the general documentation at Sleepbot.com.
 
version 1.3 - 01Jan05 - Daniel M Foley
version 1.0 - 15Feb98 - Daniel M Foley


Constructor Summary
WRLDcron()
          Constructs a new, initialized chronometer and calculates WRLD.time for 'now'.
 
Method Summary
 java.lang.Object clone()
          Clones this object, including all of its conversion values and its current time.
 long getAdjust()
          Returns the current adjustment for the chronometer.
 long getBeat()
          Returns the beat of the current converted time for the chronometer.
 int getBeatLength()
          Returns the number of digits in the beat of the chronometer.
 java.util.Date getDate()
          Gets the last date that the chronometer converted.
 int getDivisor()
          Returns the current divisor for the chronometer.
 double getFactor()
          Returns the current factor for the chronometer.
 long getFromGMT()
          Returns the current GMT (Greenwich Mean Time) offset for the chronometer.
 long getMeasure()
          Returns the measure of the current converted time for the chronometer.
 int getMeasureLength()
          Returns the number of digits in the measure of the chronometer By default, the measure of WRLDtime has 2 digits.
 double getPatience()
          Returns the current patience for the chronometer.
 WRLDcronTick getTick()
          Returns the current 'tick' of the chronometer.
 long getTime()
          Returns the current converted time for the chronometer.
 int getTimeLength()
          Returns the number of digits in the full time code of the chronometer.
 boolean isUpdated()
          Returns true when the chronometer has received its next 'tick'.
 void run()
          Core processing for the 'tick' update routine.
 void setAdjust(long adj)
          Sets the current adjustment for the chronometer.
 void setAdjustByUTC(java.lang.String line)
          Sets the current adjustment for the chronometer using a UTC code.
 void setAdjustByUTC(java.lang.String utcHost, int utcPort)
          Sets the current adjustment for the chronometer using a UTC server.
 void setAdjustByUTC(java.net.URL utcCgi)
          Sets the current adjustment for the chronometer using a UTC code provided by a CGI script.
 void setDate()
          Set's the chronometer's current date to 'now' and converts it accordingly.
 void setDate(java.util.Date nowDate)
          Set's the chronometer's current date and converts it accordingly.
 void setDivisor(int div)
          Sets the current divisor for the chronometer
 
 void setFactor(double fct)
          Sets the current factor for the chronometer.
 void setFromGMT(long gmt)
          Sets the current GMT (Greenwich Mean Time) offset for the chronometer.
 void setPatience(double pat)
          Sets the current patience for the chronometer.
 void startPatientUpdate()
          Starts the 'tick' update process by creating a patient update thread.
 void startUpdate()
          Starts the dedicated 'tick' update process by creating an update thread.
 void stopUpdate()
          Stops the 'tick' update process in its tracks.
 void waitForUpdate()
          Wait intently until the next 'tick'.
 void waitForUpdatePatiently()
          Wait patiently until the next 'tick'.
 void waitPatiently()
          Wait as patiently as (eg. sleep for as long as) the chronometer should.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WRLDcron

public WRLDcron()
Constructs a new, initialized chronometer and calculates WRLD.time for 'now'.

Method Detail

clone

public java.lang.Object clone()
Clones this object, including all of its conversion values and its current time.


getFactor

public double getFactor()
Returns the current factor for the chronometer.
 
The factor is the number of seconds in one 'tick'. By default, WRLD.time experiences one tick every 8.64 seconds. A 24-hour clock with minute precision -- the highest precision this class can provide for non-metric time -- would have a factor of 60.
 

Returns:
the current factor for the chronometer.

setFactor

public void setFactor(double fct)
Sets the current factor for the chronometer.
 

Parameters:
fct - the new factor for the chronometer.
 
See Also:
getFactor()

getDivisor

public int getDivisor()
Returns the current divisor for the chronometer.
 
The divisor indicates how to divide the beats from the measures. Originally, jonathan referred to this as the 'radix'. By default, WRLD.time has 100 beats per measure -- turns out there's also 100 measures because of the factor. A 24-hour clock with minute precision -- the highest precision this class can provide for non-metric time -- would have a divisor of 60, since there are 60 beats (minutes) for every measure (hour).
 

Returns:
the current divisor for the chronometer.

setDivisor

public void setDivisor(int div)
Sets the current divisor for the chronometer
 

Parameters:
div - the new divisor for the chronometer.
 
See Also:
getDivisor()

getPatience

public double getPatience()
Returns the current patience for the chronometer.
 
Patience is specified in seconds (or a fraction thereof). This 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 (0.01).
 

Returns:
the current patience for the chronometer.
 
See Also:
waitForUpdate(), waitForUpdatePatiently()

setPatience

public void setPatience(double pat)
Sets the current patience for the chronometer.
 

Parameters:
pat - the new patience for the chronometer.
 
See Also:
getPatience()

getFromGMT

public long getFromGMT()
Returns the current GMT (Greenwich Mean Time) offset for the chronometer.
 
The offset is specified in minutes. It's 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 -- the International Date Line, which lies between Kamchatka and Alaska on your standard RISK(tm) board. With its default offset of 0, the clock will keep time for the middle of the United Kingdom (where you'll find the city of Greenwich).
 
Do not use this offset to provide UTC adjustments; it's not sensitive enough, being measured in minutes. For subtle adjustments, you want to use getAdjust().
 

Returns:
the current GMT offset for the chronometer.

setFromGMT

public void setFromGMT(long gmt)
Sets the current GMT (Greenwich Mean Time) offset for the chronometer.
 

Parameters:
gmt - the new GMT offset for the chronometer.
 
See Also:
getFromGMT()

getTick

public WRLDcronTick getTick()
Returns the current 'tick' of the chronometer.
 
A 'tick' is the snapshot of time currently represented by the chronometer. Since the WRLDcron class is more of a stopwatch than a continuous stream of time, all we have are snapshots anyway.
 

Returns:
the current 'tick' of the chronometer, as encapsulated by a WRLDcronTick.

getTime

public long getTime()
Returns the current converted time for the chronometer.
 
This would be driven solely by the current factor. By default, WRLD.time ranges from 0 to 9999. A 24-hour clock would range from 0 to 1439.
 

Returns:
the current converted time for the chronometer.
 
See Also:
getFactor()

getMeasure

public long getMeasure()
Returns the measure of the current converted time for the chronometer.
 
This would be the 'whole' portion of the current converted time divided by by the current divisor. By default, the measure of WRLDtime ranges from 0 to 99. The measure of a 24-hour clock would range from 0 to 23.
 

Returns:
the measure of the current converted time for the chronometer.
 
See Also:
getTime(), getDivisor()

getBeat

public long getBeat()
Returns the beat of the current converted time for the chronometer.
 
This would be the 'remainder' portion of the current converted time divided by by the current divisor. By default, the beat of WRLDtime ranges from 0 to 99. The beat of a 24-hour clock would range from 0 to 59
 

Returns:
the beat of the current converted time for the chronometer.
 
See Also:
getTime(), getDivisor()

getTimeLength

public int getTimeLength()
Returns the number of digits in the full time code of the chronometer.
 
This is the sum of the measure & beat counts. The resulting value is useful for visual padding (eg. zeros to the left).
 

Returns:
the number of digits in the full time code of the chronometer.
 
See Also:
getMeasureLength(), getBeatLength()

getMeasureLength

public int getMeasureLength()
Returns the number of digits in the measure of the chronometer By default, the measure of WRLDtime has 2 digits. Same goes for a 24-hour clock. The resulting value is useful for visual padding (eg. zeros to the left).
 

Returns:
the number of digits in the measure of the chronometer

getBeatLength

public int getBeatLength()
Returns the number of digits in the beat of the chronometer.
 
By default, the beat of WRLDtime has 2 digits. Same goes for a 24-hour clock. The resulting value is useful for visual padding (eg. zeros to the left).
 

Returns:
the number of digits in the beat of the chronometer.

startUpdate

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.
 

See Also:
waitForUpdate(), isUpdated()

startPatientUpdate

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

See Also:
waitForUpdatePatiently(), isUpdated()

stopUpdate

public void stopUpdate()
Stops the 'tick' update process in its tracks.


run

public void run()
Core processing for the 'tick' update routine.
 
It just sits and waits until the clock catches up with expectations
 

Specified by:
run in interface java.lang.Runnable
See Also:
startUpdate(), startPatientUpdate(), stopUpdate(), isUpdated()

isUpdated

public boolean isUpdated()
Returns true when the chronometer has received its next 'tick'.
 
You'd call this method if you were waiting for the update in a loop of your own.
 

See Also:
waitForUpdate(), waitForUpdatePatiently()

waitForUpdate

public void waitForUpdate()
Wait intently until the next 'tick'.
 
This method takes control of the active thread and dedicates it to giving as accurate a result as possible. It yields as little time as possible to other threads during this wait.
 

See Also:
waitForUpdatePatiently()

waitForUpdatePatiently

public void waitForUpdatePatiently()
Wait patiently until the next 'tick'.
 
This method takes control of the active thread. It sleeps while it is being 'patient', giving other threads plenty of time to work during this wait. So you'll get more external processing time in exchange for whatever you deem is an acceptable loss of accuracy.
 

See Also:
getPatience(), waitForUpdate(), waitPatiently()

waitPatiently

public void waitPatiently()
                   throws java.lang.InterruptedException
Wait as patiently as (eg. sleep for as long as) the chronometer should.
 
You'd call this method if you were patiently waiting for the update in a loop of your own.
 

Throws:
java.lang.InterruptedException -
 
See Also:
getPatience(), waitForUpdatePatiently()

getDate

public java.util.Date getDate()
Gets the last date that the chronometer converted.
 
This would be the date in conventional terms.
 

Returns:
the last java.util.Date that the chronometer converted.

setDate

public void setDate()
Set's the chronometer's current date to 'now' and converts it accordingly.
 

See Also:
setDate(java.util.Date)

setDate

public void setDate(java.util.Date nowDate)
Set's the chronometer's current date and converts it accordingly.
 

Parameters:
nowDate - the java.util.Date for the chronometer to convert
 
See Also:
getDate(), setDate(java.util.Date)

getAdjust

public long getAdjust()
Returns the current adjustment for the chronometer.
 
The adjustment is specified in seconds. It provides fine-tuning, most likely to align the chronometer to an atomic clock. You're most likely to set this indirectly via a UTC server. By default, the adjustment is 0.
 
For example, if you know that your computer's clock is 5 minutes off, an adjustment of 300 will calibrate your chronometer properly. Then again, you could always FIX YOUR CLOCK!
 
Do not use this adjustment to correct for your time-zone; it's too sensitive, being measured in seconds. For a time-zone offset, you want to use getFromGMT().
 

Returns:
the current adjustment for the chronometer.

setAdjust

public void setAdjust(long adj)
Sets the current adjustment for the chronometer.
 

Parameters:
adj - the new adjustment for the chronometer.
 
See Also:
getAdjust()

setAdjustByUTC

public void setAdjustByUTC(java.lang.String utcHost,
                           int utcPort)
                    throws java.net.SocketException
Sets the current adjustment for the chronometer using a UTC server.
 
The chronometer will hit the server, grab the UTC code, and parse it. You must provide both the server's hostname and its port number.
 
The following is a short list of standard UTC hostnames: The UTC protocol is usually served from port 13.
 
For much more detailed information on UTC codes, please see http://www.bldrdoc.gov/timefreq/.
 

Parameters:
utcHost - the hostname of the UTC server.
utcPort - the port number of the UTC server.
Throws:
java.net.SocketException -
 
See Also:
getAdjust(), setAdjustByUTC(String)

setAdjustByUTC

public void setAdjustByUTC(java.net.URL utcCgi)
                    throws java.net.SocketException
Sets the current adjustment for the chronometer using a UTC code provided by a CGI script.
 
The chronometer will hit the CGI, grab the UTC code, and parse it. It's likely that the script is just a proxy -- it hits a UTC server and passes through the result. This, my friends, is how you get around the applet same-domain security restrictions!
 

Parameters:
utcCgi - the URL for the CGI script
Throws:
java.net.SocketException -
 
See Also:
getAdjust(), setAdjustByUTC(String)

setAdjustByUTC

public void setAdjustByUTC(java.lang.String line)
                    throws java.lang.NumberFormatException
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 UTC codes, please see http://www.bldrdoc.gov/timefreq/.
 

Parameters:
line - the UTC code to be parsed.
Throws:
java.lang.NumberFormatException -
 
See Also:
setAdjustByUTC(String, int), setAdjustByUTC(URL), getAdjust()

Sleepbot.com Java Classes

Copyright 1995-..   Lookit the Cat Productions