org.jeospace.simulation
Class Chronometer

java.lang.Object
  org.jeospace.simulation.Chronometer

public class Chronometer

extends java.lang.Object

A virtual clock used to control the setting and passage of time independent of the system clock. There are four primary properties that are managed by the Chronometer.

1. The setting of time. The system clock is typically set to the current -real world- date and time. The Chronometer can be set to arbitrary dates and times independent of the system clock.
2. The run state of the chronometer. While the system clock is always running, the Chronometer may be started and stopped. Additionally, the Chronometer can be stepped - i.e. the Chronometer's time is adjusted by a fixed period then stopped.
3. The direction in which time flows. The system clock only runs in the forward direction. The Chronometer can run time forward or backward.
4. The rate at which time passes. The system clock provides a measure of time as it passes in the real world. The Chronometer can also reflect the -real world- passage of time or it can run at a user defined rate. When running at a non-real-world rate, the chronometer is adjusted by a ChronPeriod for each chronometer tick( )
.

The are two primary modes in which the Chronometer functions.

1. Tracking System Time. In this mode, the Chronometer will reflect the setting and passage of time as it would be read from the system clock. This implies that the clock is running forward at a normal -real world- rate. Additionally, the Chronometer may be stopped. When it is restarted it will resume reflecting the system clock.
2. Tracking Virtual Time. In this mode, the Chronometer is set to a time and date. The Chronometer will process the passage of time according to the values of the properties for state (RUN, STOP, STEP), direction (FORWARD, BACKWARD) and rate (ChronPeriod). If the rate is set to null, the Chronometer will pass time at a rate equivalent to the passage of time by the system clock.

The Chronometer's time is updated in response to it's tick( ) method being called. Typically a manager thread running on a periodic timer will call the Chronometer's tick( ) method and then schedule the execution of application threads that are dependant upon the Chronometer's virtual time.

Version:

$Revision: 1.1.1.1 $

Author:

Rex Melton

See Also:

Date, Calendar, ChronDirection, ChronPeriod, ChronState, TimeUnit

Constructor Summary

Chronometer()
Constructor for a Chronometer that tracks system time.

Chronometer(java.util.Calendar calendar)
Constructor for a Chronometer that is set to the specified time.

Chronometer(java.util.Date date)
Constructor for a Chronometer that is set to the specified time.

Chronometer(double julianDay)
Constructor for a Chronometer that is set to the specified time.

Chronometer(long millisFromTheEpoch)
Constructor for a Chronometer that is set to the specified time.

Method Summary

void	addChronListener(ChronListener csl) Add a listener for ChronEvents
protected void	fireChronEvent(int id) Send a ChronEvent to all registered listeners
java.util.Calendar	getCalendar() Return the Chronometer's time in a Calendar object
void	getCalendar(java.util.Calendar c) Return the Chronometer's time in a Calendar object
ChronPeriod	getChronRate() Return the aggregate chron rate.
java.util.Date	getDate() Return the Chronometer's time in a Date object
void	getDate(java.util.Date d) Return the Chronometer's time in a Date object
ChronDirection	getDirection() Return the value indicating the direction of time flow of the Chronometer.
double	getJulianDay() Return the Chronometer's time as a Julian Day.
ChronState	getState() Return the value indicating the run state of the Chronometer.
long	getTimeInMillis() Return the Chronometer's time in milliseconds from the epoch.
boolean	isTrackingSystemTime() Return the flag indicating whether the Chronometer is reflecting system time.
void	removeChronListener(ChronListener csl) Remove a listener for ChronEvents
void	set(java.util.Calendar calendar) Set the Chronometer's time to mirror the argument Calendar.
void	set(java.util.Date date) Set the Chronometer's time to mirror the argument Date.
void	set(double julianDay) Set the Chronometer's time to mirror the argument Julian Day.
void	set(long millisFromTheEpoch) Set the Chronometer's time to mirror the argument.
void	setChronRate(ChronPeriod rate) Set the aggregate chron rate.
void	setDirection(ChronDirection directionValue) Set the direction of time flow of the Chronometer.
void	setState(ChronState stateValue) Set the run state of the Chronometer.
void	setStateAndDirection(ChronState stateValue, ChronDirection directionValue) Set the run state and direction of time flow of the Chronometer.
void	setToTrackSystemTime() Set the Chronometer to reflect system time.
void	tick() Perform the processing to update the Chronometer to it's next time and state.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Chronometer

public Chronometer()

Constructor for a Chronometer that tracks system time.

Chronometer

public Chronometer(long millisFromTheEpoch)

Constructor for a Chronometer that is set to the specified time.

Parameters:

millisFromTheEpoch - the long number of milliseconds that have elapsed since the system epoch.

Chronometer

public Chronometer(java.util.Date date)

Constructor for a Chronometer that is set to the specified time.

Parameters:

date - the Date object specifying the chronometer time.

Chronometer

public Chronometer(java.util.Calendar calendar)

Constructor for a Chronometer that is set to the specified time.

Parameters:

calendar - the Calendar object specifying the chronometer time.

Chronometer

public Chronometer(double julianDay)

Constructor for a Chronometer that is set to the specified time.

Parameters:

julianDay - the Julian Day specifying the chronometer time.

Method Detail

getTimeInMillis

public long getTimeInMillis()

Return the Chronometer's time in milliseconds from the epoch.

Returns:

the long representation of the Chronometer's time in milliseconds from the epoch.

getJulianDay

public double getJulianDay()

Return the Chronometer's time as a Julian Day.

Returns:

the double representation of the Chronometer's time as a Julian Day.

getDate

public java.util.Date getDate()

Return the Chronometer's time in a Date object

Returns:

a Date object initialized with the Chronometer's time.

getDate

public void getDate(java.util.Date d)

Return the Chronometer's time in a Date object

Parameters:

d - the Date object to initialize.

getCalendar

public java.util.Calendar getCalendar()

Return the Chronometer's time in a Calendar object

Returns:

a Calendar object initialized with the Chronometer's time.

getCalendar

public void getCalendar(java.util.Calendar c)

Return the Chronometer's time in a Calendar object

Parameters:

c - the Calendar object to initialize.

addChronListener

public void addChronListener(ChronListener csl)

Add a listener for ChronEvents

Parameters:

csl - the listener

removeChronListener

public void removeChronListener(ChronListener csl)

Remove a listener for ChronEvents

Parameters:

csl - the listener

fireChronEvent

protected void fireChronEvent(int id)

Send a ChronEvent to all registered listeners

Parameters:

id - the ChronEvent id to send

isTrackingSystemTime

public boolean isTrackingSystemTime()

Return the flag indicating whether the Chronometer is reflecting system time.

Returns:

true if the Chronometer is reflecting system time, false if not.

setToTrackSystemTime

public void setToTrackSystemTime()

Set the Chronometer to reflect system time.

set

public void set(long millisFromTheEpoch)

Set the Chronometer's time to mirror the argument.

Parameters:

millisFromTheEpoch - the long representation of the time in milliseconds from the system epoch to set.

set

public void set(java.util.Date date)

Set the Chronometer's time to mirror the argument Date.

Parameters:

date - the Date representation of the time to set.

set

public void set(java.util.Calendar calendar)

Set the Chronometer's time to mirror the argument Calendar.

Parameters:

calendar - the Calendar representation of the time to set.

set

public void set(double julianDay)

Set the Chronometer's time to mirror the argument Julian Day.

Parameters:

julianDay - the Julian Day representation of the time to set.

getState

public ChronState getState()

Return the value indicating the run state of the Chronometer. The value returned will be one of: ChronState.RUN, ChronState.STOP or ChronState.STEP.

Returns:

the value indicating the run state.

setState

public void setState(ChronState stateValue)

Set the run state of the Chronometer.

Parameters:

stateValue - the value for the state parameter. Legal values are: ChronState.RUN, ChronState.STOP or ChronState.STEP

Throws:

IllegalArgumentException - for any non-legal argument value.

getDirection

public ChronDirection getDirection()

Return the value indicating the direction of time flow of the Chronometer. The value returned will either be: ChronDirection.FORWARD or ChronDirection.BACKWARD.

Returns:

the value indicating the direction of time flow.

setDirection

public void setDirection(ChronDirection directionValue)

Set the direction of time flow of the Chronometer.

Parameters:

directionValue - the value for the direction parameter. Legal values are: ChronDirection.FORWARD or ChronDirection.BACKWARD

Throws:

IllegalArgumentException - for any non-legal (null) argument value.

setStateAndDirection

public void setStateAndDirection(ChronState stateValue,
                                 ChronDirection directionValue)

Set the run state and direction of time flow of the Chronometer.

Parameters:

stateValue - the value for the state parameter. Legal values are: ChronState.RUN, ChronState.STOP or ChronState.STEP

directionValue - the value for the direction parameter. Legal values are: ChronDirection.FORWARD or ChronDirection.BACKWARD

Throws:

IllegalArgumentException - for any non-legal argument value.

getChronRate

public ChronPeriod getChronRate()

Return the aggregate chron rate.

Returns:

the aggregate chron rate.

setChronRate

public void setChronRate(ChronPeriod rate)

Set the aggregate chron rate.

Parameters:

rate - the aggregate chron rate.

tick

public void tick()

Perform the processing to update the Chronometer to it's next time and state.