org.mitre.sim.api3
Class Entity

java.lang.Object
  extended byorg.mitre.sim.api3.flow.threads.ThreadData
      extended byorg.mitre.sim.api3.exec.LogicalProcess
          extended byorg.mitre.sim.api3.Entity
All Implemented Interfaces:
java.lang.Runnable
Direct Known Subclasses:
PeriodicEntity

public abstract class Entity
extends LogicalProcess

Abstract class from which all entities in a simulation are derived. Entities are the source of autonomous action in a simulation. They embody both proactive and reactive behavior. The agenda usually contains the proactive part of a Entity. The reactive behavior can be coded in action methods that respond to other Entity initiatives. 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 Entity or register in class Simulation.


Copyright © 2003-2004 The MITRE Corporation


Field Summary
 
Fields inherited from class org.mitre.sim.api3.flow.threads.ThreadData
elaborated, launched, stop, thread
 
Constructor Summary
Entity(java.lang.String myName)
          Construct a new instance of class Entity with a user-supplied name.
 
Method Summary
 void actionMethodNotifier()
          Deprecated. Designates a method on Entity subclasses as an action method. If an Entity subclass method includes an invocation of actionMethodNotifier anytime during the execution of the method, that method is known as an action method. Action methods are the reactive portion of an entity's behavior. (The proactive hehavior is in the agenda.) The use of actionMethodNotifier has been replaced by a method naming convention. Methods of the form "actionX" where X is one or more characters are now recognized by the Executive as action methods.
 void agenda()
          Overloading this method gives the entity proactive behavior.
 Population createPopulation(java.lang.Class c)
          Create a Population of Class c entities.
 void displayEntities(java.lang.String message)
          Display a table of the simulation Entities catagorized by state.
 void entityComplete()
          Overload if entity completion notification is desired.
 boolean entityIsAlive(Entity target)
          Test the target entity and determine if it is in ready to receive an action method invocation.
 void exceptionHandler(java.lang.Exception e)
          Overload if a custom exception handler is desired.
 java.util.logging.Logger getLogger()
          Return the Entity logger.
 java.lang.String getName()
           
 double getTimeLast()
          Last value of simulation time before the simulation stops.
 double getTimeNow()
          Returns the current simulation time.
 void info(java.lang.String message)
          Convenience method that concatenates the current simulation time, entity name, and the supplied message string then logges them to the Entity logger as an info level message.
 void msg(java.lang.String message)
          Deprecated. Please see info(String).
 Entity register(Entity e)
          Affiliate a new entity with this simulation.
 void schedule(java.lang.String methodName, double eventDelay)
          Schedule a parameterless method for execution after a specifed delay.
 void schedule(java.lang.String methodName, double eventDelay, java.lang.Object[] arguments)
          Schedule a method for execution after a specifed delay.
 void setTimeLast(double t)
          Specify the last value of time to be simulated before the simulation stops.
 void stopSimulation()
          Stops the entire simulation.
 java.lang.String toString()
          Return the name, state, and simulation time as a comma separated string.
 WaitResult waitForAction(double backStop)
          Place the entity in a waitingForEvent state until either the specified amount of simulation time has passed or an action method is invoked.
 WaitResult waitForActionOrTrigger(Trigger trigger)
          Convenient version of waitForActionOrTrigger(Trigger[], double) that accepts a single condition and assumes an infinite backstop time.
 WaitResult waitForActionOrTrigger(Trigger[] triggers, double backStop)
          Place the entity in a waitingForEvent state until either the specified amount of simulation time has passed, an action method is invoked, or one of the supplied conditions is true.
 WaitResult waitForActionOrTrigger(Trigger trigger1, Trigger trigger2)
          Convenient version of waitForActionOrTrigger(Trigger[], double) that accepts a single condition and assumes an infinite backstop time.
 WaitResult waitForTime(double delay)
          Place the entity in a waitingForTime state until the specified amount of simulation time has passed.
 
Methods inherited from class org.mitre.sim.api3.exec.LogicalProcess
getActionOccurred, getCurrentTriggers, getExec, getExecutive, getNextTime, getSelectedTrigger, getState, getTriggerOccurred, isWaiting, run, setActionOccurred, setCurrentTriggers, setExecutive, setLogger, setNextTime, setSelectedTrigger, setState, setTriggerOccurred, stateEquals
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Entity

public Entity(java.lang.String myName)
Construct a new instance of class Entity with a user-supplied name. Entity names are for developer convenience, are not examined by the executive, and need not be unique. Names are used to annotate messages generated by methods msg and toString. If the supplied name string is null or less than one charater long, then entity name is set to "Entity".

Parameters:
myName - Any string value that is useful to identify this entity.
See Also:
msg(String), toString()
Method Detail

getName

public final java.lang.String getName()
Specified by:
getName in class LogicalProcess

agenda

public void agenda()
Overloading this method gives the entity proactive behavior. The agenda method is invoked by the simulation executive on each instance of class Entity. An entity's agenda is often a loop where the entity examines and/or modifies the simulation state then waits for external events to occur. Before the simulation executive invokes the agenda method, the entity is in a dormant state. During execution of the agenda method, the entity is in one of these states: ready, active, waitingForTime, or waitingForEvent. When the agenda method returns, the entity is in a complete state and has no further proactive or reactive behavior.

Specified by:
agenda in class LogicalProcess

entityComplete

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

Specified by:
entityComplete in class LogicalProcess
See Also:
Simulation.simulationComplete()

exceptionHandler

public void exceptionHandler(java.lang.Exception e)
Overload if a custom exception handler is desired. An entity's agenda is invoked by the simulation executive. If the agenda throws an exception, that exception will be caught by the executive and passed to this method before execution of the entity is abandoned. Exceptions thrown by the exceptionHandler method itself are ignored. The default behavior for this method is to invoke e.printStackTrace() where e is the exception thrown by the agenda.

Specified by:
exceptionHandler in class LogicalProcess

stopSimulation

public final void stopSimulation()
Stops the entire simulation. Simulations will end when all the entity agendas are complete or the last value of simulation time is reached. This method is used if an entity needs to stop the simulation before then.

See Also:
getTimeLast(), Executive.stopSimulation(LogicalProcess)

getTimeNow

public final double getTimeNow()
Returns the current simulation time.

Returns:
Current simulation time.
See Also:
Executive.getTimeNow()

getTimeLast

public final double getTimeLast()
Last value of simulation time before the simulation stops.

Returns:
Last value of simulation time to be simulated.
See Also:
setTimeLast(double t), Executive.getTimeLast()

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:
getTimeLast(), Simulation.setTimeLast(double), Executive.setTimeLast(double)

actionMethodNotifier

public final void actionMethodNotifier()
                                throws java.lang.IllegalStateException
Deprecated. Designates a method on Entity subclasses as an action method. If an Entity subclass method includes an invocation of actionMethodNotifier anytime during the execution of the method, that method is known as an action method. Action methods are the reactive portion of an entity's behavior. (The proactive hehavior is in the agenda.) The use of actionMethodNotifier has been replaced by a method naming convention. Methods of the form "actionX" where X is one or more characters are now recognized by the Executive as action methods.

Throws:
java.lang.IllegalStateException
See Also:
Executive.actionMethodInvoked(LogicalProcess)

entityIsAlive

public final boolean entityIsAlive(Entity target)
Test the target entity and determine if it is in ready to receive an action method invocation. Entities cannot receive action method invocations when they are in either the Dormant or Complete states.

Parameters:
target - Entity instance to be tested.
Returns:
true: Entity is active and can receive action method invocations. false: The target entity is null, or in either a Dormant or Complete state.

register

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

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

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, entity name, and the supplied message string then logges them to the Entity logger as an info level message.

See Also:
Simulation.info(String)

toString

public java.lang.String toString()
Return the name, state, and simulation time as a comma separated string.

Returns:
Entity name, state, and simulation time.

displayEntities

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

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

getLogger

public final java.util.logging.Logger getLogger()
Return the Entity logger.

Overrides:
getLogger in class LogicalProcess
Returns:
The Entity logger.

waitForTime

public WaitResult waitForTime(double delay)
Place the entity in a waitingForTime state until the specified amount of simulation time has passed. Zero or more action methods may be invoked by other entities during the invocation of this method but control will not return until the specified amount of simulation time as passed. This method is similar to the HLA Time Advance Request service.

Parameters:
delay - Amount of simulation time that must pass before this entity is ready to run.
Returns:
WaitResult
See Also:
Executive.waitForTime(double, LogicalProcess)

waitForAction

public WaitResult waitForAction(double backStop)
Place the entity in a waitingForEvent state until either This method is similar to the HLA Next Event Request service.

Parameters:
backStop - Maximum amount of simulation time that will pass before this entity is ready to run.
Returns:
WaitResult
See Also:
Executive.waitForEvent(Trigger[], double, LogicalProcess)

waitForActionOrTrigger

public WaitResult waitForActionOrTrigger(Trigger[] triggers,
                                         double backStop)
Place the entity in a waitingForEvent state until either This method is similar to the HLA Next Event Request service.

Parameters:
triggers - Array of zero or more conditions or null.
backStop - Maximum amount of simulation time that will pass before this entity is ready to run.
Returns:
WaitResult
See Also:
Trigger, Executive.waitForEvent(Trigger[], double, LogicalProcess)

waitForActionOrTrigger

public WaitResult waitForActionOrTrigger(Trigger trigger)
Convenient version of waitForActionOrTrigger(Trigger[], double) that accepts a single condition and assumes an infinite backstop time. This method is equivalent to:
   waitForActionOrTrigger(new Trigger[] {trigger}, Double.POSITIVE_INFINITY)
   

See Also:
waitForActionOrTrigger(Trigger[], double)

waitForActionOrTrigger

public WaitResult waitForActionOrTrigger(Trigger trigger1,
                                         Trigger trigger2)
Convenient version of waitForActionOrTrigger(Trigger[], double) that accepts a single condition and assumes an infinite backstop time. This method is equivalent to:
   waitForActionOrTrigger(new Trigger[] {trigger1, trigger2}, Double.POSITIVE_INFINITY)
   

See Also:
waitForActionOrTrigger(Trigger[], double)

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)

schedule

public void schedule(java.lang.String methodName,
                     double eventDelay)
              throws java.lang.IllegalArgumentException
Schedule a parameterless method for execution after a specifed delay. The method name given by methodName will be invoked by the executive after eventDelay units of simulation time have passed. The specified method must belong to the Entity instance making the schedule invocation. Entity methods scheduled for execution using schedule should take no parameters and have a return type of void. The agenda method cannnot be scheduled for execution.

Parameters:
methodName - String representation of the method name being scheduled.
eventDelay - Amount of simulation time that must pass before the method is invoked by the executive.
Throws:
java.lang.IllegalArgumentException
See Also:
schedule(String, double, Object[])

schedule

public void schedule(java.lang.String methodName,
                     double eventDelay,
                     java.lang.Object[] arguments)
              throws java.lang.IllegalArgumentException
Schedule a method for execution after a specifed delay. The method name given by methodName will be invoked by the executive after eventDelay units of simulation time have passed. The specified method must belong to the Entity instance making the schedule invocation. Entity methods scheduled for execution using schedule should have a return type of void. The agenda method cannnot be scheduled for execution.

Parameters:
methodName - String representation of the method name being scheduled.
eventDelay - Amount of simulation time that must pass before the method is invoked by the executive.
arguments - Array of argument supplied when methodName is executed.
Throws:
java.lang.IllegalArgumentException
See Also:
schedule(String, double)