ix.isim
Class ISimTimer

java.lang.Object
  extended by 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:

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