org.mitre.sim.api3
Class Simulation

java.lang.Object
  extended byjava.lang.Thread
      extended byorg.mitre.sim.api3.Simulation
All Implemented Interfaces:
java.lang.Runnable

public abstract class Simulation
extends java.lang.Thread

Abstract class used to create a simulation. An instance of a Simulation subclass is associated with a group of entities sharing a common definition of simulation time. When an instance of an Entity subclass is created, it must be associated with an instance of a Simulation subclass. This is done with the register method in class Simulation or register in class Entity. Usually there is only one instance of a Simulation subclass but more than one may exist. If a program has more than one instance, each will be a separate and independent simulation.


Copyright © 2003-2004 The MITRE Corporation


Field Summary
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Constructor Summary
Simulation()
           
 
Method Summary
 Population createPopulation(java.lang.Class c)
          Create a Population of Class c entities.
 void displayEntities(java.lang.String message)
          Deprecated. Display a table of the simulation Entities catagorized by current state. Used to test Executive implementations and not needed by simulation developers.
 java.util.logging.Logger getEntityLogger()
          Return the logger used by all Entity instances and subclasses.
 java.util.logging.Logger getExecLogger()
          Return the logger used by the simulation executive.
 Executive getExecutive()
          Deprecated. Used to test Executive implementations and is not needed by simulation developers.
 java.util.logging.Logger getFlowLogger()
          Return the logger used by the flow manager.
 java.util.logging.Logger getLogger(java.lang.String loggerName)
          Return the logger of the specified name.
 long getPace()
          Return the current pave setting.
 java.util.logging.Logger getSimLogger()
          Return the logger used by the Simulation instance.
 java.util.Properties getSubProperties(java.lang.String prefix, java.util.Properties origProps)
           
 void info(java.lang.String message)
          Convenience method that concatenates the current simulation time, Simulation subclass name, and the supplied message string before it is logged to the Simulation logger as an info level message.
abstract  void initialize()
          Create the initial simulation environment.
 void msg(java.lang.String message)
          Deprecated. Please see info(String).
 void pauseSimulation()
          Used by an external thread to pause the Executive.
 Entity register(Entity e)
          Affiliate a new entity with this simulation.
 void resumeSimulation()
          Used by an external thread to resume the Executive.
 void run()
          Execute the simulation.
 void setPace(long period)
          Set the minimum amount of real time that must pass before the simulation advances one unit of simulation time.
 void setTimeLast(double t)
          Specify the last value of time to be simulated before the simulation stops.
 void setVisible(boolean flag)
          Enables/Disables the GUI for this simulation
 void simulationComplete()
          Overload if simulation completion notification is desired.
 void start()
          Execute the simulation using a new thread.
 java.lang.String version()
          Returns the version of the classes implementing interface Executive and Flow.
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, stop, stop, suspend, toString, yield
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Simulation

public Simulation()
Method Detail

register

public final Entity register(Entity e)
Affiliate a new entity with this simulation. This method has the same semantics as the Entity.register(Entity) method.

Parameters:
e - Entity instance being registered
Returns:
Same Entity supplied by parameter e.
See Also:
Entity.register(Entity)

initialize

public abstract void initialize()
Create the initial simulation environment. Code placed in this method is executed by the simulation executive before simulation time starts to advance. Usually initialize is used to create and register the initial set of entities. Once the initialize method returns, the executive begins the advance of simulation time by selecting the first entity for activation.


simulationComplete

public void simulationComplete()
Overload if simulation completion notification is desired. Simulation execution can come to an end for a variety of reasons. Overloading the simulationComplete method gives the simulation developer a place to put code that will be executed unconditionally at the end of the simulation's life.

See Also:
Entity.entityComplete()

run

public final void run()
Execute the simulation. Method run performs the following three operations:
  1. Invoke the initialize method.
  2. Activate and execute all the entities associated with this simulation. This process continues until all entities have finished their agendas or until the timeLast value of simulation time is reached.
  3. Invoke the simulationComplete method.
Method run blocks until the simulation is finished. If blocking is not desired, use method start to execute a simulation.

See Also:
start(), setTimeLast(double), Executive.startSimulation()

start

public final void start()
Execute the simulation using a new thread. Method start performs the following three operations:
  1. Invoke the initialize method.
  2. Activate and execute all the entities associated with this simulation. This process continues until all entities have finished their agendas or until the timeLast value of simulation time is reached.
  3. Invoke the simulationComplete method.
Method start does not block until the simulation is finished. If blocking is desired, use method run to execute a simulation.

See Also:
run(), setTimeLast(double), Executive.startSimulation()

setTimeLast

public final void setTimeLast(double t)
Specify the last value of time to be simulated before the simulation stops. The simulation can end before timeLast if all the entities reach the end of their agendas before then. If an entity agenda is active when simulation time reaches the timeLast value, the executive will stop the simulation. The default value of timeLast is positive infinity.

Parameters:
t - Last value of simulation time to be simulated.
See Also:
Entity.setTimeLast(double), Executive.setTimeLast(double)

setVisible

public final void setVisible(boolean flag)
Enables/Disables the GUI for this simulation

Parameters:
flag - true: Create and display the controlling GUI for the simulation. false: Hide the controlling GUI.

msg

public void msg(java.lang.String message)
Deprecated. Please see info(String).


info

public final void info(java.lang.String message)
Convenience method that concatenates the current simulation time, Simulation subclass name, and the supplied message string before it is logged to the Simulation logger as an info level message.

See Also:
Entity.info(String)

getExecutive

public final Executive getExecutive()
Deprecated. Used to test Executive implementations and is not needed by simulation developers.

Returns:
The Executive instance for this simulation.

displayEntities

public final void displayEntities(java.lang.String message)
Deprecated. Display a table of the simulation Entities catagorized by current state. Used to test Executive implementations and not needed by simulation developers.

Parameters:
message - Text message display at the top of the Entity table.

setPace

public final void setPace(long period)
Set the minimum amount of real time that must pass before the simulation advances one unit of simulation time. This method places an upper bound on the rate at which simulation time advances. By default, there is no artifical constraint on how fast simulation time advances. Simulations advance as fast as the require computation can be performed. As an example, assume the following are true: To get the desired 2 to 1 ratio of simulation time to real time, this invocation should be used:
    setPace(60 * 1000 / 2)
    
To return the simulation to a state the computation proceeds as fast as possible, make the following invocation:
    setPace(0)
    

Parameters:
period - Minimum number of real milliseconds that must pass before one unit of simulation time passes.

getPace

public long getPace()
Return the current pave setting.

Returns:
Minimum number of real milliseconds that must pass before one unit of simulation time passes.

pauseSimulation

public final void pauseSimulation()
Used by an external thread to pause the Executive. Care should be taken when using this method. If the Executive thread calls this method, deadlock will result. An attempt to pause an Executive that is already paused has no effect.


resumeSimulation

public final void resumeSimulation()
Used by an external thread to resume the Executive. An attempt to resume a running executive has no effect.


version

public final java.lang.String version()
Returns the version of the classes implementing interface Executive and Flow.

Returns:
Simulation, Executive, and Flow implementation version.

getSubProperties

public java.util.Properties getSubProperties(java.lang.String prefix,
                                             java.util.Properties origProps)

getLogger

public final java.util.logging.Logger getLogger(java.lang.String loggerName)
Return the logger of the specified name.

Parameters:
loggerName - Name of the logger sought
Returns:
The logger of name loggerName.

getExecLogger

public java.util.logging.Logger getExecLogger()
Return the logger used by the simulation executive.

Returns:
The executive logger.

getFlowLogger

public java.util.logging.Logger getFlowLogger()
Return the logger used by the flow manager.

Returns:
The flow manager logger.

getSimLogger

public java.util.logging.Logger getSimLogger()
Return the logger used by the Simulation instance.

Returns:
The simulation logger.

getEntityLogger

public java.util.logging.Logger getEntityLogger()
Return the logger used by all Entity instances and subclasses.

Returns:
The entity logger.

createPopulation

public Population createPopulation(java.lang.Class c)
Create a Population of Class c entities. The returned Population will contain all instances of the specified class (or subclass) that have been registered and which have not yet completed.

Parameters:
c - Class Entity or subclass.
Returns:
new Population.
See Also:
Executive.createPopulation(Class, LogicalProcess)