ix.isim
Class ISimTimer

java.lang.Object
  ix.isim.ISimTimer

Direct Known Subclasses:

ISimTimerClient, ISimTimerServer

public abstract class ISimTimer
extends java.lang.Object

An ISimTimer is a device for keeping track of simualted time. There are two sub-classes here that can be used:

• an ISimTimerServer belongs to an ISim agent and controls simulated time for other ISimTimers (that have regitered with the ISimTimerServer); there should only be one such timer for any I-X application
• an ISimTimerClient registers with an ISimTimerServer and obtains the current simulated time from the server for displaying it, not for changing it

The sole constructor of this class is protected and the static method getISimTimer(...) should be used to obtain the right kind of ISimTimer for the given agent type.

Nested Class Summary

(package private) class

ISimTimer.UpdateTimeDisplayThread This Thread is used to update the displayed time on a regular basis.

Field Summary

protected java.lang.String	ACCELERATE
protected IXAgent	owner the IXAgent to which this timer belongs
protected java.lang.String	PAUSE
protected java.lang.String	REGISTER
protected java.lang.String	RESUME
protected ISimTimeFrame	simTimeDisplay the frame displaying the simuation time
protected boolean	simulationActive indicates whether simulation time is currently passing
protected java.lang.String	START
protected java.lang.String	STOP
protected Symbol	SYNCHRONIZE_LABEL some command strings used for the synchronization of multiple ISimTimers
protected ISimTimer.UpdateTimeDisplayThread	tUpdater the Thread used for updating the display

Constructor Summary

protected

ISimTimer(IXAgent agent) Protected constructor for use by sub-classes.

Method Summary

long	changeAccelerationFactor(double acceleration) This function changes the time acceleration factor to the given value.
double	getAccelerationFactor() Returns the currently used time acceleration factor
static ISimTimer	getISimTimer(IXAgent agent) Factory for getting the right kind of timer for this agent.
long	getSimTimeInMillis() This function returns the current time in the simulation.
abstract void	handleSynchronizeActivity(Activity synchActivity) This function needs to be implemented by the inheriting class.
long	pause() This function pauses this simulation timer, be it a Server or Client.
long	resume() This function re-starts the simulation timer after it had been paused.
protected void	setCurrentSimTime(long time)
boolean	simulationStarted() Returns whether the start function has been called.
void	start(long simTime, double factor) This function starts the simulation clock.
void	terminateTimer() This function should be called terminate this Timer.

Methods inherited from class java.lang.Object

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

Field Detail

SYNCHRONIZE_LABEL

protected final Symbol SYNCHRONIZE_LABEL

some command strings used for the synchronization of multiple ISimTimers

START

protected final java.lang.String START

See Also:

Constant Field Values

PAUSE

protected final java.lang.String PAUSE

See Also:

Constant Field Values

RESUME

protected final java.lang.String RESUME

See Also:

Constant Field Values

ACCELERATE

protected final java.lang.String ACCELERATE

See Also:

Constant Field Values

STOP

protected final java.lang.String STOP

See Also:

Constant Field Values

REGISTER

protected final java.lang.String REGISTER

See Also:

Constant Field Values

owner

protected IXAgent owner

the IXAgent to which this timer belongs

simulationActive

protected boolean simulationActive

indicates whether simulation time is currently passing

simTimeDisplay

protected ISimTimeFrame simTimeDisplay

the frame displaying the simuation time

tUpdater

protected ISimTimer.UpdateTimeDisplayThread tUpdater

the Thread used for updating the display

Constructor Detail

ISimTimer

protected ISimTimer(IXAgent agent)

Protected constructor for use by sub-classes. It registers this timer as a tool with the given IXAgent so that the user can display it.

Parameters:

agent - IXAgent owner of this timer

Method Detail

handleSynchronizeActivity

public abstract void handleSynchronizeActivity(Activity synchActivity)

This function needs to be implemented by the inheriting class. This is because the two types of ISimTimer, ISimTimerClient and ISimTimerServer, behave differently with respect to synchronization. Having it abstract ensures that no ISimTimer can ever be constructed.

Parameters:

synchActivity - a synchronization Activity (see final Strings in this class for possible activities)

simulationStarted

public boolean simulationStarted()

Returns whether the start function has been called.

Returns:

boolean whether simulation time has been started

getSimTimeInMillis

public long getSimTimeInMillis()

This function returns the current time in the simulation. This function should only be called after the simulation has been started. Then it will return the correct simulated time even if the simulation is paused.

Returns:

long

getAccelerationFactor

public double getAccelerationFactor()

Returns the currently used time acceleration factor

Returns:

double current acceleration factor

start

public void start(long simTime,
                  double factor)
           throws ISimTimerException

This function starts the simulation clock. The simulation time will be set to the given time and simulated time will progress with the given acceleration factor. It also shows the frame displaying current sim-time if it isn't already showing.

Parameters:

simTime - initial value of the simulated time

factor - acceleration factor for simulated time

Throws:

ISimTimerException - if this function has been called before

pause

public long pause()

This function pauses this simulation timer, be it a Server or Client. As a result simulationActive will be false and the display will show it is paused. However, the time update thread will continue to run.

Returns:

long the simulation time when the simulation was paused

resume

public long resume()

This function re-starts the simulation timer after it had been paused. As a result simulationActive will be true and the display will show that it is running.

Returns:

long the simulation time when the simulation was resumed

changeAccelerationFactor

public long changeAccelerationFactor(double acceleration)

This function changes the time acceleration factor to the given value.

Parameters:

acceleration - double the new acceleration factor

Returns:

long the simulation time when the acceleration factor was changed

terminateTimer

public void terminateTimer()

This function should be called terminate this Timer. It will gracefully terminate the update thread for the display.

setCurrentSimTime

protected void setCurrentSimTime(long time)

getISimTimer

public static ISimTimer getISimTimer(IXAgent agent)

Factory for getting the right kind of timer for this agent. ISim agents get an ISimTimerServer and others get an ISimTimerClient.

Parameters:

agent - IXAgent owner of this timer

Returns:

ISimTimer the new timer