Class Simulation

All Implemented Interfaces:
ObjectNamerOps<SimObject>
Direct Known Subclasses:
Animation2D, GenericSimulation

public class Simulation extends ScriptingContext implements ObjectNamerOps<SimObject>
Top level class for a simulation. This class models the flow of time, handles scheduling of events, and provides tables that allow simulation objects to be looked up by name. Subclasses provide additional functionality.
  • Constructor Details

    • Simulation

      public Simulation()
      Constructor.
    • Simulation

      public Simulation(ScriptingContext parent)
      Constructor with a parent simulation or scripting context. When a simulation has a parent, the simulation shares the parent's scripting context. In addition, if the parent is a Simulation, the parent's event queue is used instead of the simulation's event queue and time structures. This allows multiple simulations, perhaps with different flavors, to be combined into a single simulation. While the event queue and simulation time are shared, tables of simulation objects are not. Running any of the simulations sharing a parent will run all of them. In addition, the parent simulation will be added an an alternative object namer, so that the set/add methods of factory classes can find objects are defined by a parent simulation. The value returned by getTicksPerUnitTime() will be that of the parent simulation if the parent is not null or the default value of 1.0.
      Parameters:
      parent - the simulation's parent; null if there is none
    • Simulation

      public Simulation(ScriptingContext parent, double ticksPerUnitTime)
      Constructor with a parent simulation or scripting context and with a time-unit specification. When a simulation has a parent, the simulation shares the parent's scripting context. In addition, if the parent is a Simulation, the parent's event queue is used instead of the simulation's event queue and time structures. This allows multiple simulations, perhaps with different flavors, to be combined into a single simulation. While the event queue and simulation time are shared, tables of simulation objects are not. Running any of the simulations sharing a parent will run all of them. In addition, the parent simulation will be added an an alternative object namer, so that the set/add methods of factory classes can find objects are defined by a parent simulation.
      Parameters:
      parent - the simulation's parent; null if there is none
      ticksPerUnitTime - the number of ticks per unit time
    • Simulation

      public Simulation(double ticksPerUnitTime)
      Constructor give a time-unit specification.
      Parameters:
      ticksPerUnitTime - the number of ticks per unit time when time is provided as a double-precision number
  • Method Details

    • getTicks

      public long getTicks(double time)
      Convert a time or time interval to ticks. The value returned will be rounded to the closest long integer.
      Parameters:
      time - the time or interval in unit-time units
      Returns:
      the corresponding number of ticks.
    • getTicksCeil

      public long getTicksCeil(double time)
      Convert a time or time interval to ticks, rounding up. The value returned will be rounded to the closest long integer equal to or larger than the argument after the conversion.
      Parameters:
      time - the time or interval in unit-time units
      Returns:
      the corresponding number of ticks.
    • getTicksFloor

      public long getTicksFloor(double time)
      Convert a time or time interval to ticks, rounding down. The value returned will be rounded down to the closest long integer equal to or smaller than the argument after the conversion.
      Parameters:
      time - the time or interval in unit-time units
      Returns:
      the corresponding number of ticks.
    • getTime

      public double getTime(long ticks)
      Get the time in the simulation's time units given the time in ticks.
      Parameters:
      ticks - the number of ticks
      Returns:
      the time
    • allowSetStackTraceMode

      public void allowSetStackTraceMode(boolean allow, boolean tsallow)
      Configure whether or not setStackTraceMode(boolean) checks permissions. This method also controls the use of TraceSet.setStackTraceMode(boolean) for those trace sets associated with this simulation.
      Parameters:
      allow - true if calls to setStackTraceMode(boolean) cannot throw a security exception; false otherwise
      tsallow - true if calls to TraceSet.setStackTraceMode(boolean) for trace sets associated with this simulation cannot throw a security exception; false otherwise
    • allowsSetStackTraceMode

      public boolean allowsSetStackTraceMode()
      Determine if the simulation is configured so that calls to setStackTraceMode(boolean) or TraceSet.setStackTraceMode(boolean) for trace sets associated with this simulation cannot throw a security exception.
      Returns:
      true if a security exception cannot be thrown; false otherwise
    • allowsSetStackTraceModeTS

      public boolean allowsSetStackTraceModeTS()
      Determine if the simulation is configured so that calls to TraceSet.setStackTraceMode(boolean) for trace sets associated with this simulation cannot throw a security exception.
      Returns:
      true if a security exception cannot be thrown; false otherwise
    • setStackTraceMode

      public void setStackTraceMode(boolean mode)
      Set stack-trace mode. When stack-trace mode is on, certain events are tagged with the stack trace at the point the event was created. At each point in simulation time, the method getEventStackTrace() will return a StackTraceElement array containing the stack trace. This option is useful for modest-sized simulations for debugging purposes.
      Parameters:
      mode - true to turn stack-trace mode on; false to turn it off
    • getStackTraceMode

      public boolean getStackTraceMode()
      Get the stack-trace mode. When stack-trace mode is on, certain events are tagged with the stack trace at the point the event was created. At each point in simulation time, the method getEventStackTrace() will return a StackTraceElement array containing the stack trace. This option is useful for modest-sized simulations for debugging purposes.
      Returns:
      true if stack-trace mode is on; false if it is off
    • getEventStackTrace

      public StackTraceElement[] getEventStackTrace()
      Get the stack trace in effect when the current event was created.
      Returns:
      an array containing the stack trace
    • getParent

      public Simulation getParent()
      Get the simulation's parent. The parent is the simulation passed as an argument in a constructor.
      Returns:
      the simulation's parent; null if there is none.
      See Also:
    • currentTicks

      public final long currentTicks()
      Get the current simulation time in tick units.
      Returns:
      the current simulation time
    • getCurrentTime

      @Deprecated public final long getCurrentTime()
      Deprecated.
      Replaced by currentTicks()
      Returns:
      the current time in ticks
    • currentTime

      public final double currentTime()
      Get the current simulation time in real-valued time units. The value is the value returned by getCurrentTime() divided by the value returned by getTicksPerUnitTime().
      Returns:
      the current simulation time
    • currentTimeFrom

      public final double currentTimeFrom(long ticks)
      Get the change in the current simulation time from an initial value. This is provided to eliminate round-off errors from computing the difference between large floating-point numbers.
      Parameters:
      ticks - the initial simulation-time value
      Returns:
      the difference in time in real-valued time units
    • getTicksPerUnitTime

      public final double getTicksPerUnitTime()
      Get the number of ticks per unit time.
      Returns:
      the number of ticks per unit time
    • getCurrentTimePriority

      public final double getCurrentTimePriority()
      Get the priority for the current event at the current time.
      Returns:
      the priority; 0.0 if none has been set.
    • moreEventsScheduled

      public final boolean moreEventsScheduled()
      Check if there are any pending events.
      Returns:
      true if events have been scheduled but not yet run; false otherwise
    • getNextEventInterval

      public final long getNextEventInterval()
      Get the interval to the next scheduled event. The value returned is that maximum interval given the current state of the simulation by which the current simulation time may be advanced.
      Returns:
      the time for the next scheduled event, or Integer.MAX_VALUE time if no event next event is scheduled
    • advance

      public final long advance(long interval)
      Advance Simulation time. This method increments the current simulation time by at most the number of ticks given by its argument. It will not advance the current simulation time beyond the time at which the next scheduled event is scheduled. If there is no scheduled event, the simulation time will be advanced by the number of ticks given by this method's argument.
      Parameters:
      interval - the time interval by which to advance the current simulation time
      Returns:
      the amount of time by which the current simulation time was actually advanced
    • scheduleEvent

      public final SimulationEvent scheduleEvent(SimulationEvent event, long delay)
      Schedule an event given a delay. Typically used in the implementation of core classes, not called by user code unless a user defines new types of events.
      Parameters:
      event - the event to schedule
      delay - the number of time units to wait, measured from the current simulation time, until an event occurs
      Returns:
      the event scheduled
    • scheduleEvent

      public final SimulationEvent scheduleEvent(SimulationEvent event, long delay, double tpriority)
      Schedule an event given a delay and a priority. Typically used in the implementation of core classes, not called by user code unless a user defines new types of events.
      Parameters:
      event - the event to schedule
      delay - the number of time units to wait, measured from the current simulation time, until an event occurs
      tpriority - the priority level of the event at the time it is scheduled
      Returns:
      the event scheduled
    • descheduleEvent

      public final boolean descheduleEvent(SimulationEvent pqentry)
      Deschedule (cancel) an event.
      Parameters:
      pqentry - the simulation event to deschedule
      Returns:
      true on success; false on failure
    • rescheduleEvent

      public final boolean rescheduleEvent(SimulationEvent event, long delay)
      Reschedule a simulation event. This method will fail if an event is not currently scheduled or if an attempt is made to schedule it at a previous point in simulation time.
      Parameters:
      event - the event
      delay - the number of time units to wait, measured from the current simulation time, until an event occurs
      Returns:
      true on success; false on failure
    • rescheduleEvent

      public final boolean rescheduleEvent(SimulationEvent event, long delay, double tpriority)
      Reschedule a simulation event given a delay and a priority.
      Parameters:
      event - the event
      delay - the number of time units to wait, measured from the current simulation time, until an event occurs
      tpriority - the priority of the event at the time it is scheduled
      Returns:
      true on success; false on failure
    • scheduleCall

      public TaskSimulationEvent scheduleCall(Callable callable)
      Schedule a call. The call method of a Callable will be run at the current simulation time after the current event completes. Equivalent to scheduleCall(callable, 0).

      For scripting languages that can handle Java lambda expressions, the Callable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Callable.

      Parameters:
      callable - the Callable to run.
      Returns:
      the event scheduled
    • scheduleCallWP

      public TaskSimulationEvent scheduleCallWP(Callable callable, double tpriority)
      Schedule a call with a priority. The call method of a Callable will be run at the current simulation time after the current event completes. Equivalent to scheduleCall(callable, 0, tpriority).

      For scripting languages that can handle Java lambda expressions, the Callable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Callable.

      Parameters:
      callable - the Callable to run.
      tpriority - the event priority at the current time
      Returns:
      the event scheduled
    • scheduleCall

      public TaskSimulationEvent scheduleCall(SimObjectCallable soc)
      Schedule a call specified by a SimObjectCallable. The call method of a Callable will be run at the current simulation time after the current event completes. Equivalent to scheduleCall(callable, 0).
      Parameters:
      soc - the SimObjectCallable to run.
      Returns:
      the event scheduled
    • scheduleCallWP

      public TaskSimulationEvent scheduleCallWP(SimObjectCallable soc, double tpriority)
      Schedule a call specified by a SimObjectCallable and given a priority. The call method of a Callable will be run at the current simulation time after the current event completes. Equivalent to scheduleCall(callable, 0).
      Parameters:
      soc - the SimObjectCallable to run.
      tpriority - the event priority at the current time
      Returns:
      the event scheduled
    • scheduleCall

      public TaskSimulationEvent scheduleCall(Callable callable, long delay)
      Schedule a call providing a delay. The call method of a Callable will be run at a particular simulation time.

      For scripting languages that can handle Java lambda expressions, the Callable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Callable.

      Parameters:
      callable - the Callable to run.
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      Returns:
      the event scheduled
    • scheduleCall

      public TaskSimulationEvent scheduleCall(Callable callable, long delay, double tpriority)
      Schedule a call providing a delay and priority. The call method of a Callable will be run at a particular simulation time.

      For scripting languages that can handle Java lambda expressions, the Callable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Callable.

      Parameters:
      callable - the Callable to run.
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      tpriority - the priority level of the event at the time it is scheduled
      Returns:
      the event scheduled
    • scheduleScript

      public TaskSimulationEvent scheduleScript(String script, long delay) throws UnsupportedOperationException
      Schedule a script providing a delay.
      Parameters:
      script - the script to execute
      delay - the number of time units to wait, measured from the current simulation time, until the script is executed
      Returns:
      the event scheduled
      Throws:
      UnsupportedOperationException
    • scheduleScript

      public TaskSimulationEvent scheduleScript(String script, long delay, double tpriority) throws UnsupportedOperationException
      Schedule a script providing a delay and priority.
      Parameters:
      script - the script to execute
      delay - the number of time units to wait, measured from the current simulation time, until the script is executed
      tpriority - the priority level of the event at the time it is scheduled
      Returns:
      the event scheduled
      Throws:
      UnsupportedOperationException
    • scheduleCallObject

      public TaskSimulationEvent scheduleCallObject(Object scriptObject, long delay) throws UnsupportedOperationException
      Schedule a script object providing a delay. The script object's call() method will be run when the event is processed.
      Parameters:
      scriptObject - the script to execute
      delay - the number of time units to wait, measured from the current simulation time, until the script object's call() method is executed
      Returns:
      the event scheduled
      Throws:
      UnsupportedOperationException
    • scheduleCallObject

      public TaskSimulationEvent scheduleCallObject(Object scriptObject, long delay, double tpriority) throws UnsupportedOperationException
      Schedule a script object providing a delay and priority. The script object's call() method will be run when the event is processed.
      Parameters:
      scriptObject - the script to execute
      delay - the number of time units to wait, measured from the current simulation time, until the script object's call() method is executed
      tpriority - the priority level of the event at the time it is scheduled
      Returns:
      the event scheduled
      Throws:
      UnsupportedOperationException
    • scheduleCallPaused

      public TaskSimulationEvent scheduleCallPaused(Callable callable, long delay)
      Schedule a call providing a delay and with the simulation paused. The call method of a Callable will be run at a particular simulation time. The simulation will be put in a state in which it is paused (e.g. not running) while the scheduled call is being processed, so any calls put on the initialization queue will be processed when the simulation is restarted and before the next normal event is processed. Simulation listeners will be notified that the simulation has paused and restarted.

      For scripting languages that can handle Java lambda expressions, the Callable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Callable.

      Parameters:
      callable - the Callable to run.
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      Returns:
      the event scheduled
    • scheduleCallPaused

      public TaskSimulationEvent scheduleCallPaused(Callable callable, long delay, double tpriority)
      Schedule a call providing a delay and priority with the simulation paused. The call method of a Callable will be run at a particular simulation time. The simulation will be put in a state in which it is paused (e.g. not running) while the scheduled call is being processed, so any calls put on the initialization queue will be processed when the simulation is restarted and before the next normal event is processed. Simulation listeners will be notified that the simulation has paused and restarted.

      For scripting languages that can handle Java lambda expressions, the Callable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Callable.

      Parameters:
      callable - the Callable to run.
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      tpriority - the priority level of the event at the time it is scheduled
      Returns:
      the event scheduled
    • scheduleCall

      public TaskSimulationEvent scheduleCall(SimObjectCallable soc, long delay)
      Schedule a call specified by a SimObjectCallable, providing a delay. The call method of a Callable will be run at a particular simulation time. A SimObjectCallable allows the call to be annotated with data accessible in simulation state events (used to monitor or instrument a simulation).
      Parameters:
      soc - the SimObjectCallable to run.
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      Returns:
      the event scheduled
    • scheduleCall

      public TaskSimulationEvent scheduleCall(SimObjectCallable soc, long delay, double tpriority)
      Schedule a call specified by a SimObjectCallable, providing a delay and priority. The call method of a Callable will be run at a particular simulation time. A SimObjectCallable allows the call to be annotated with data accessible in simulation state events (used to monitor or instrument a simulation).
      Parameters:
      soc - the SimObjectCallable to run.
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      tpriority - the priority level of the event at the time it is scheduled
      Returns:
      the event scheduled
    • scheduleInitCall

      public TaskSimulationEvent scheduleInitCall(Callable callable, int priority)
      Schedule an initialization call. The call method of the Callable argument will be invoked when a run method of the simulation is called and before any scheduled simulation events are executed. This is intended for use by classes such as factory classes that need to schedule some further initialization events after other factories have had a chance to create their objects.

      For scripting languages that can handle Java lambda expressions, the Callable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Callable.

      Parameters:
      callable - the Callable to run.
      priority - the priority setting the order in which each Callable's call method is run, with lower values run first
      Returns:
      the event scheduled
    • unscheduledTaskThread

      public TaskThread unscheduledTaskThread(Runnable runnable)
      Create a task thread but do not schedule it for execution. After a task thread starts running, a program will not terminate until that task thread terminates, is canceled, or

      For scripting languages that can handle Java lambda expressions, the Runnable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Runnable. System.exit(int) is called by some thread.

      Parameters:
      runnable - the Runnable used by the thread
      Returns:
      the task thread
    • unscheduledTaskThread

      public TaskThread unscheduledTaskThread(SimObjectRunnable sor)
      Create a task thread specified by a SimObjectRunnable, but do not schedule it for execution. After a task thread starts running, a program will not terminate until that task thread terminates, is canceled, or System.exit(int) is called by some thread.
      Parameters:
      sor - the SimObjectRunnable used by the thread
      Returns:
      the task thread
    • scheduleTask

      public TaskThread scheduleTask(Runnable runnable, long delay)
      Schedule a Task given a delay. A thread executing the code provided by the Runnable will be started at a simulation time equal to the current simulation time + the value of delay. After a task thread starts running, a program will not terminate until that task thread terminates, is canceled, or System.exit(int) is called by some thread.

      For scripting languages that can handle Java lambda expressions, the Runnable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Runnable.

      Parameters:
      runnable - the Runnable to execute.
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      Returns:
      the thread that will run this task
    • scheduleTask

      public TaskThread scheduleTask(Runnable runnable, long delay, double tpriority)
      Schedule a Task given a delay and priority. A thread executing the code provided by the Runnable will be started at a simulation time equal to the current simulation time + the value of delay. After a task thread starts running, a program will not terminate until that task thread terminates, is canceled, or System.exit(int) is called by some thread.

      For scripting languages that can handle Java lambda expressions, the Runnable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Runnable.

      Parameters:
      runnable - the Runnable to execute.
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      tpriority - the priority level of the event at the time it is scheduled
      Returns:
      the thread that will run this task
    • scheduleTaskScript

      public TaskThread scheduleTaskScript(String script, long delay) throws UnsupportedOperationException
      Schedule a Task specified by a script and given a delay. A thread executing the code provided by the script will be started at a simulation time equal to the current simulation time + the value of delay. A simulation method pauseTask is provided for cases in which the scripting language does not make the class org.bzdev.devqsim.TaskThread accessible. If the task will not pause, it is more efficient to use scheduleScript instead.
      Parameters:
      script - the script implementing the task to schedule
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      Returns:
      the thread that will run this task
      Throws:
      UnsupportedOperationException
    • scheduleTaskScript

      public TaskThread scheduleTaskScript(String script, long delay, double tpriority) throws UnsupportedOperationException
      Schedule a Task specified by a script and given a delay and priority. A thread executing the code provided by the script will be started at a simulation time equal to the current simulation time + the value of delay. A simulation method pauseTask is provided for cases in which the scripting language does not make the class org.bzdev.devqsim.TaskThread accessible. If the task will not pause, it is more efficient to use scheduleScript instead.
      Parameters:
      script - the script implementing the task to schedule
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      tpriority - the priority level of the event at the time it is scheduled
      Returns:
      the thread that will run this task
      Throws:
      UnsupportedOperationException
    • scheduleTaskObject

      public TaskThread scheduleTaskObject(Object scriptObject, long delay) throws UnsupportedOperationException
      Schedule a task specified by a script object given a delay. A thread executing the code provided by the script object's run() method will be started at a simulation time equal to the current simulation time + the value of delay. A simulation method pauseTask is provided for cases in which the scripting language does not make the class org.bzdev.devqsim.TaskThread accessible. If the task will not pause, it is more efficient to use scheduleCallObject instead.
      Parameters:
      scriptObject - the script object whose run() method implements the task to schedule
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      Returns:
      the thread that will run this task
      Throws:
      UnsupportedOperationException
    • scheduleTaskObject

      public TaskThread scheduleTaskObject(Object scriptObject, long delay, double tpriority) throws UnsupportedOperationException
      Schedule a task specified by a script object given a delay and priority. A thread executing the code provided by the script object's run() method will be started at a simulation time equal to the current simulation time + the value of delay. A simulation method pauseTask is provided for cases in which the scripting language does not make the class org.bzdev.devqsim.TaskThread accessible. If the task will not pause, it is more efficient to use scheduleCallObject instead.
      Parameters:
      scriptObject - the script object whose run() method implements the task to schedule
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      tpriority - the priority level of the event at the time it is scheduled
      Returns:
      the thread that will run this task
      Throws:
      UnsupportedOperationException
    • scheduleTask

      public TaskThread scheduleTask(SimObjectRunnable sor, long delay)
      Schedule a Task specified by a SimObjectRunnable given a delay. A thread executing the code provided by the Runnable will be started at a simulation time equal to the current simulation time + the value of delay. After a task thread starts running, a program will not terminate until that task thread terminates, is canceled, or System.exit(int) is called by some thread.
      Parameters:
      sor - the SimObjectRunnable to execute.
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      Returns:
      the thread that will run this task
    • scheduleTask

      public TaskThread scheduleTask(SimObjectRunnable sor, long delay, double tpriority)
      Schedule a Task specified by a SimObjectRunnable given a delay and priority. A thread executing the code provided by the Runnable will be started at a simulation time equal to the current simulation time + the value of delay. After a task thread starts running, a program will not terminate until that task thread terminates, is canceled, or System.exit(int) is called by some thread.
      Parameters:
      sor - the SimObjectRunnable to execute.
      delay - the number of time units to wait, measured from the current simulation time, until the call is made
      tpriority - the priority level of the event at the time it is scheduled
      Returns:
      the thread that will run this task
    • scheduleTask

      public TaskThread scheduleTask(Runnable runnable)
      Start a simulation task with a default delay of zero. This is a convenience method that is equivalent to scheduleTask(runnable, 0); After a task thread starts running, a program will not terminate until that task thread terminates, is canceled, or System.exit(int) is called by some thread.

      For scripting languages that can handle Java lambda expressions, the Runnable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Runnable.

      Parameters:
      runnable - the Runnable to execute.
      Returns:
      the thread running this task
    • scheduleTaskWP

      public TaskThread scheduleTaskWP(Runnable runnable, double tpriority)
      Start a simulation task with a default delay of zero. This is a convenience method that is equivalent to scheduleTask(runnable, 0); After a task thread starts running, a program will not terminate until that task thread terminates, is canceled, or System.exit(int) is called by some thread.

      For scripting languages that can handle Java lambda expressions, the Runnable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Runnable.

      Parameters:
      runnable - the Runnable to execute.
      tpriority - the event priority at the current time
      Returns:
      the thread running this task
    • scheduleTask

      public TaskThread scheduleTask(SimObjectRunnable sor)
      Start a simulation task specified by a SimObjectRunnable, with a default delay of zero. This is a convenience method that is equivalent to scheduleTask(sor, 0); After a task thread starts running, a program will not terminate until that task thread terminates, is canceled, or System.exit(int) is called by some thread.
      Parameters:
      sor - the SimObjectRunnable to execute.
      Returns:
      the thread running this task
    • scheduleTaskWP

      public TaskThread scheduleTaskWP(SimObjectRunnable sor, double tpriority)
      Start a simulation task specified by a SimObjectRunnable, with a default delay of zero and a specified priority. This is a convenience method that is equivalent to scheduleTask(sor, 0); After a task thread starts running, a program will not terminate until that task thread terminates, is canceled, or System.exit(int) is called by some thread.

      For scripting languages that can handle Java lambda expressions, the Runnable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Runnable.

      Parameters:
      sor - the SimObjectRunnable to execute.
      tpriority - the event priority at the current time
      Returns:
      the thread running this task
    • startImmediateTask

      public TaskThread startImmediateTask(Runnable runnable) throws IllegalStateException
      Start a simulation task immediately, blocking the current task. This may be called only while the simulation is running. The task runs immediately, with the calling thread blocked, until the task pauses or terminates. After a task thread starts running, a program will not terminate until that task thread terminates, is canceled, or

      For scripting languages that can handle Java lambda expressions, the Runnable argument can be the expression in that scripting language that the script engine will treat as a lambda expression. For example, with the Nashorn ECMAScript implementation, the expression function() {...} will be converted into a lambda expression that Java will then convert into a Runnable. System.exit(int) is called by some thread.

      Parameters:
      runnable - the Runnable to execute.
      Returns:
      the thread running this task
      Throws:
      IllegalStateException
    • startImmediateTask

      public TaskThread startImmediateTask(SimObjectRunnable sor) throws IllegalStateException
      Immediately Start a simulation task specified by a SimObjectRunnable, blocking the current task. This may be called only while the simulation is running. The task runs immediately, with the calling thread blocked, until the task pauses or terminates. After a task thread starts running, a program will not terminate until that task thread terminates, is canceled, or System.exit(int) is called by some thread.
      Parameters:
      sor - the SimObjectRunnable to execute.
      Returns:
      the thread running this task
      Throws:
      IllegalStateException
    • run

      public void run()
      Run the simulation until the event queue empties. This method will return when either the event queue is empty or if the current thread is interrupted. A return caused by an interrupt will occur just before an event would have been pulled off of the event queue and will not change the thread's interrupt status.

      One should note that this method may return while tasks that have started to run have not yet terminated. If that is the case, the program will not terminate until System.exit(int) is called.

    • run

      public void run(long interval)
      Run simulation for a fixed number of time units. This method will return when the specified simulation time has expired, or if the current thread is interrupted. A return caused by an interrupt will occur just before an event would have been pulled off of the event queue and will not change the interrupt status. If the simulation ends before the end of the interval is reached, the simulation time will be advanced to the end of the interval.

      One should note that this method may return while tasks that have started to run have not yet terminated. If that is the case, the program will not terminate until System.exit(int) is called.

      Parameters:
      interval - the time interval over which to run the simulation
    • createMonitor

      public SimulationMonitor createMonitor(Object object) throws IllegalArgumentException
      Create a SimulationMonitor implemented in a scripting language. A simulation monitor is an object that controls when a simulation pauses versus continues to run. When implemented in a scripting language, the simulation monitor is represented by a object with a method named simulationPauses. This method takes the simulation as its argument and returns either
      • true, a non-zero integer, or some object if the simulation should pause.
      • false, 0, or null if the simulation should continue running.
      For example (using ECMAScript), if sim is a simulation, then
      
         count = 0;
         monitor = sim.createMonitor({
           simulationPauses: function(simulation) {
            count++;
            if (count % 1000 == 0) {
              return true;
            } else {
              return false;
            }
         }
       
      will make the simulation pause each time 1000 events have been processed. The argument simulation gives the monitor the simulation it is monitoring.

      Note: using a script to implement a simulation monitor is inefficient, but possibly useful during debugging.

      Parameters:
      object - the scripting-language object or a string that, when evaluated by the current scripting language, returns an object as defined above
      Returns:
      a simulation monitor
      Throws:
      IllegalArgumentException
    • run

      public void run(SimulationMonitor<? extends Simulation> monitor)
      Run a simulation under the control of a simulation monitor. The monitor will determine when the simulation stops or pauses. The class SimulationMonitor uses generics so that a monitor can make use of methods specific to a subclass of Simulation.

      One should note that this method may return while tasks that have started to run have not yet terminated. If that is the case, the program will not terminate until System.exit(int) is called.

      The method SimulationMonitor.simulationPauses() will be called once per iteration, and the simulation will pause if this method returns true.

      Parameters:
      monitor - the simulation monitor
    • addSimulationListener

      public void addSimulationListener(SimulationListener l)
      Add a simulation listener. Normally a user will use a simulation adapter, created by subclassing DefaultSimAdapter or by using the method createAdapter(Object) (if the adapter is written using a scripting language).
      Parameters:
      l - the action listener to add.
      See Also:
    • removeSimulationListener

      public void removeSimulationListener(SimulationListener l)
      Remove a simulation listener.
      Parameters:
      l - the action listener to remove.
    • createAdapter

      public SimulationListener createAdapter(Object object) throws IllegalArgumentException
      Create a simulation listener based on a script object that implements an adapter. In a scripting language, one might write the adapter as follows:
      
          adapter = simulation.createAdapter({
             simulationStart: function(sim) {println("simulation start");}
             simulationstop: function(sim) {println("simulation stop");}
          });
          simulation.addSimulationListener(adapter);
       
      where simulation is an instance of Simulation and the scripting language is ECMAScript.

      To respond to particular events, the script object must implement one or more methods. The arguments to these methods are:

      • sim. The simulation that scheduled the event
      • q. A task queue or server queue associated with the event.
      • server. A queue server associated with the event.
      • obj. A simulation object associated with the event by being responsible for generating it. Methods with this argument are the result of events generated by calling certain methods of the class SimObject or its subclasses.
      • tag. A tag labeling the event (for debugging/tracing purposes). The tag can be any object, but is typically a string or stack trace.
      Some methods use a subset of these arguments. The methods are:
      • simulationStart(sim). A simulation has started.
      • simulationStop(sim). A simulation has stopped (ended or paused).
      • callStart(sim,tag). A call scheduled by a simulation has started. The call was scheduled using a simulation's method scheduleCall, scheduleScript, or scheduleCallObject, and is not attributed to any particular simulation object. The argument representing the call must be either a Callable, a string providing a script to execute, or an object in a scripting language with a "call" method that has no arguments.
      • callEnd(sim, tag). A call scheduled by a simulation has ended. The call was scheduled using a simulation's method scheduleCall, scheduleScript, or scheduleCallObject, and is not attributed to any particular simulation object. The argument representing the call must be either a Callable, a string providing a script to execute, or an object in a scripting language with a "call" method that has no arguments.
      • callStartSimObject(sim,obj,tag). A call that a simulation object scheduled has started. The call was created using a simulation object's protected method named callableScript, scheduleScript, scheduleCall, scheduleCallObject, or bindCallable and is attributed to that simulation object.
      • callEndSimObject(sim,obj,tag). A call that an simulation object scheduled has ended. The call was created using a simulation object's protected method named callableScript, scheduleScript, scheduleCall, scheduleCallObject, or bindCallable and is attributed to that simulation object.
      • taskStart(sim,tag). A task scheduled by a simulation has started. The task was created by a simulation's public method scheduleTask, scheduleTaskScript, scheduleTaskObject, scheduleTaskWP, startImmediateTask, or unscheduledTaskThread and is not attributed to any particular simulation object. The argument representing a task must be either a Runnable, a string providing a script to execute, or an object in a scripting language with a "run" method that has no arguments.
      • taskPause(sim,tag). A task scheduled by a simulation has paused. The task was created by a simulation's public method scheduleTask, scheduleTaskScript, scheduleTaskObject, scheduleTaskWP, startImmediateTask, or unscheduledTaskThread and is not attributed to any particular simulation object. The argument representing a task must be either a Runnable, a string providing a script to execute, or an object in a scripting language with a "run" method that has no arguments.
      • taskResume(sim,tag). A task scheduled by a simulation has resumed. The task was created by a simulation's public method scheduleTask, scheduleTaskScript, scheduleTaskObject, scheduleTaskWP, startImmediateTask, or unscheduledTaskThread and is not attributed to any particular simulation object. The argument representing a task must be either a Runnable, a string providing a script to execute, or an object in a scripting language with a "run" method that has no arguments.
      • taskEnd(sim,tag). A task scheduled by a simulation has ended. The task was created by a simulation's public method scheduleTask, scheduleTaskScript, scheduleTaskObject, scheduleTaskWP, startImmediateTask, or unscheduledTaskThread and is not attributed to any particular simulation object. The argument representing a task must be either a Runnable, a string providing a script to execute, or an object in a scripting language with a "run" method that has no arguments.
      • taskStartSimObject(sim,obj,tag). A task that a simulation object scheduled has started. The task was created using a simulation object's protected method unscheduledTaskThread, scheduleTask, scheduleTaskScript, scheduleTaskObject startImmediateTask, runnableScript, runnableObject, or bindRunnable and is attributed to the simulation object.
      • taskPauseSimObject(sim,obj,tag). A task that a simulation object scheduled has paused. The task was created using a simulation object's protected method unscheduledTaskThread, scheduleTask, scheduleTaskScript, scheduleTaskObject startImmediateTask, runnableScript, runnableObject, or bindRunnable and is attributed to the simulation object.
      • taskResumeSimObject(sim,obj,tag). A task that a simulation object scheduled has resumed. The task was created using a simulation object's protected method unscheduledTaskThread, scheduleTask, scheduleTaskScript, scheduleTaskObject startImmediateTask, runnableScript, runnableObject, or bindRunnable and is attributed to the simulation object.
      • taskEndSimObject(sim,obj,tag). A task that a simulation object scheduled has ended. The task was created using a simulation object's protected method unscheduledTaskThread, scheduleTask, scheduleTaskScript, scheduleTaskObject startImmediateTask, runnableScript, runnableObject, or bindRunnable and is attributed to the simulation object.
      • taskQueueStart(sim,q). Processing of an element on a task queue of a simulation has started. Subsequent calls to other adapter methods may indicate details of that processing.
      • taskQueuePause(sim,q). Processing of an element on a task queue of a simulation has paused. Subsequent calls to other adapter methods may indicate details of that processing.
      • taskQueueResume(sim,q). Processing of an element on a task queue of a simulation has resumed. Subsequent calls to other adapter methods may indicate details of that processing.
      • taskQueueEnd(sim,q). Processing of an element on a task queue of a simulation has ended.
      • serverSelected(sim,q). A server was selected by a server queue in a simulation.
      • serverInteraction(sim,q,server,tag). A server associated with a server queue in a simulation begins interacting with the callable, runnable, or task it is serving. For this method, the task or callable is not associated with a simulation object.
      • serverCallable(sim,q,server,tag). A server associated with a server queue in a simulation finishes its interaction and a callable is run to continue the simulation. For this method, the task or callable is not associated with a simulation object.
      • serverRunnable(sim,q,server,tag). A server associated with a server queue in a simulation finishes its interaction and a Runnable starts execution to continue the simulation. For this method, the task or callable is not associated with a simulation object.
      • serverTask(sim,q,server,tag). A server associated with a server queue in a simulation finishes its interaction and the task that was queued resumes execution. For this method, the task or callable is not associated with a simulation object.
      • serverInteractionSimObject(sim,q,server,obj,tag). A server associated with a server queue in a simulation begins interacting with the object it is serving. The simulation object's protected method bindCallable or bindRunnable was used to create the Callable or Runnable and associate it with the simulation object, or a thread was created using the simulation object's unscheduledTaskThread or scheduleTask methods.
      • serverCallableSimObject(sim,q,server,obj,tag). A server associated with a server queue in a simulation finishes its interaction and a callable associated with a simulation object is run to continue the simulation. The simulation object's protected method bindCallable was used to create the Callable and associate it with the simulation object.
      • serverRunnableSimObject(sim,q,server,obj,tag). A server associated with a server queue in a simulation finishes its interaction and a Runnable associated with a simulation object starts execution to continue the simulation. The simulation object's protected method bindRunnable was used to create the Runnable and associate it with the simulation object.
      • serverTaskSimObject(sim,q,server,obj,tag). A server associated with a server queue in a simulation finishes its interaction and a Task associated with a simulation object resumes execution to continue the simulation. The task was associated with a simulation object when the task was created by creating the task by using one of the simulation object's unscheduledTaskThread or scheduleTask methods.

      Subclasses of Simulation may define additional methods (for example, DramaSimulation adds additional methods for message-related events).

      Parameters:
      object - the script object implementing the adapter
      Returns:
      the adapter
      Throws:
      IllegalArgumentException
    • pauseTask

      public void pauseTask(long delay)
      Pause the currently-running task thread given a delay. Equivalent to TaskThread.pause(delay), but provided primarily for use in scripts.
      Parameters:
      delay - the interval for which to pause
    • pauseTask

      public void pauseTask(long delay, double tpriority)
      Pause the currently-running task thread based on a delay and priority. Equivalent to TaskThread.pause(delay, tpriority), but provided primarily for use in scripts.
      Parameters:
      delay - the interval for which to pause
      tpriority - the priority level to use for the event associated with the task.
    • setTraceOutput

      public void setTraceOutput(Appendable appendable)
      Set the default trace output. By default, no trace output will be produced, so this method should be called to turn on tracing (alternatively, the corresponding method TraceSet.setOutput(Appendable) can be used for each trace set).
      Parameters:
      appendable - the appendable to use for output; null if the default is to print nothing
      See Also:
    • enableTracing

      public void enableTracing(boolean value)
      Set whether or not tracing is enabled. A trace will be printed when tracing is enabled if a simulation or a TraceSet created for this simulation has provided an Appendable for output. If tracing is not enabled, no trace messages will be displayed for any TraceSet associated with this simulation.
      Parameters:
      value - true if tracing is to be enabled; false if tracing is to be disabled
    • isTracingEnabled

      public boolean isTracingEnabled()
      Determine if tracing is enabled. A trace will be printed when tracing is enabled if a simulation or a TraceSet created for this simulation has provided an Appendable for output. If tracing is not enabled, no trace messages will be displayed for any TraceSet associated with this simulation.
      Returns:
      true if tracing is enabled; false otherwise
    • getNamedObjectClass

      public Class<SimObject> getNamedObjectClass()
      Get the class common to all named objects.
      Specified by:
      getNamedObjectClass in interface ObjectNamerOps<SimObject>
      Returns:
      the class
    • addObjectNamer

      public final void addObjectNamer(ObjectNamerOps<SimObject> altNamer)
      Add an alternative object namer for use by getObject methods.
      Specified by:
      addObjectNamer in interface ObjectNamerOps<SimObject>
      Parameters:
      altNamer - the alternative object namer
    • checkAltList

      public boolean checkAltList(ObjectNamerOps<SimObject> altNamer)
      Determine if the argument is equal to this object namer or a member of this object namer's object-namer list. This test is recursive. It is specified in this interface for technical reasons, and is not intended to be called otherwise. It is called by addObjectNamer to ensure that a depth-first search will terminate.
      Specified by:
      checkAltList in interface ObjectNamerOps<SimObject>
      Parameters:
      altNamer - the object namer to test
      Returns:
      true if he argument is equal to this object namer or a member of this object namer's object-namer list, tested recursively; false otherwise
    • getObject

      public SimObject getObject(String name)
      Get an object from the object namer's tables.
      Specified by:
      getObject in interface ObjectNamerOps<SimObject>
      Parameters:
      name - the name of the object
      Returns:
      the object corresponding to the name provided
    • getObjectNames

      public Set<String> getObjectNames()
      Get all the object names from a object namer's tables.
      Specified by:
      getObjectNames in interface ObjectNamerOps<SimObject>
      Returns:
      a set containing the names of all objects interned in the object namer's tables
    • getObjectNames

      public Set<String> getObjectNames(Class<?> clazz)
      Get some the object names from a object namer's tables. The object names are those of objects for which either their classes or one of their superclasses match the class passed as an argument.
      Specified by:
      getObjectNames in interface ObjectNamerOps<SimObject>
      Parameters:
      clazz - the class of the objects whose names are to appear in the set returned
      Returns:
      a set containing the names of all objects interned in the object namer's tables such that the class of that object or the class of a subclass of that object matches the clazz argument
    • getObject

      public <T> T getObject(String name, Class<T> clazz)
      Get a named object with a particular name, provided that the object is a subclass of a specific class.
      Specified by:
      getObject in interface ObjectNamerOps<SimObject>
      Type Parameters:
      T - the type specified by the argument clazz
      Parameters:
      name - the name of the object
      clazz - the class of the object
      Returns:
      the object or null if the object cannot be found
    • getObjects

      public Collection<SimObject> getObjects()
      Get a collection of all the interned named objects assocated with an object namer.
      Specified by:
      getObjects in interface ObjectNamerOps<SimObject>
      Returns:
      an unmodifiable collection of the objects interned in the object namer's tables.
    • getObjects

      public <T> Collection<T> getObjects(Class<T> clazz)
      Get a set of objects from a object namer's tables. The objects are those for which either their classes or one of their superclasses match the class passed as an argument.
      Specified by:
      getObjects in interface ObjectNamerOps<SimObject>
      Type Parameters:
      T - the type specified by the argument clazz
      Parameters:
      clazz - the class of the objects to get.
      Returns:
      a collection containing all interned objects whose class or one of its superclasses matches the class clazz passed as the method's argument
    • getObjects

      public Collection<SimObject> getObjects(String className)
      Get a collection of objects with a class constraint, expressed as a class name, from a object namer's tables. The objects are those for which either their classes or one of their superclasses match the class passed as an argument.

      Note: this method is provided because script engines do not provide a standard way of denoting a Java class (the class not an instance of it). The collection it returns is a collection of the common named object type. Except for scripting languages that do not provide compile-time type checking, one should nearly always use ObjectNamerOps.getObjects(Class).

      Parameters:
      className - the fully qualified class name of the objects to get.
      Returns:
      an unmodifiable collection containing all interned objects whose class or one of its superclasses matches the class clazz passed as the method's argument; an empty (and unmodifiable) collection if no objects can be found
    • configureFactorySupported

      public boolean configureFactorySupported()
      Determine if the configureFactory method is supported.
      Specified by:
      configureFactorySupported in interface ObjectNamerOps<SimObject>
      Returns:
      true if configure() is supported; false otherwise
    • configureFactory

      public void configureFactory(NamedObjectFactory factory, Object scriptObject) throws UnsupportedOperationException, IllegalArgumentException
      Configure a factory. This is an optional operation.
      Specified by:
      configureFactory in interface ObjectNamerOps<SimObject>
      Parameters:
      factory - the factory to be configured
      scriptObject - an object in a scripting language representing a specification for how this factory should be configured
      Throws:
      UnsupportedOperationException - the factory cannot be configured using a script object
      IllegalArgumentException - the scriptObject is ill formed
    • createFactories

      public void createFactories(String pkg, Object scriptObject) throws UnsupportedOperationException, IllegalArgumentException
      Description copied from interface: ObjectNamerOps
      Create multiple factories from a package in a single statement. The first argument is the fully qualified name of a package. The second is a scripting-language object specifying the individual factories and how they should be named. For the object-namer subclass Simulation and its subclasses (DramaSimulation and Animation2D are defined in this class library), the specification for ECMAScript is an ECMAScript objects whose property names are used as the name of a scripting language variable and whose value is a string containing the name of the factory class (excluding its package name, which is provided by the first argument). For example, with ECMAScript for one of these subclasses,
      
          a2d = new Animation2D(scripting, ...);
          a2d.createFactories("org.bzdev.anim2d", {
             alf: "AnimationLayer2DFactory",
             gvf: "GraphViewFactory"
          });
       
      will create two ECMAScript variables whose names are alf and gvf.

      Unless explicitly implemented, this method will throw an UnsupportedOperationException.

      Specified by:
      createFactories in interface ObjectNamerOps<SimObject>
      Parameters:
      pkg - the fully-qualified package name
      scriptObject - a scripting-language object specifying factories that should be created
      Throws:
      UnsupportedOperationException - this object namer does not support scripting or creating multiple factories specified by a scripting object
      IllegalArgumentException - an argument was not suitable for creating a factory.
    • createFactory

      public NamedObjectFactory createFactory(String varName, String packageName, String className) throws UnsupportedOperationException, IllegalArgumentException
      Create a factory and store it in a scripting-language variable. The factory must have a single-argument constructor that takes its object namer as its argument.

      This method is provided for convenience - to reduce the amount of typing when adding factories to a script. It returns the factory that was created in addition to storing it in a variable in case a user of this method tries to assign the value it returns.

      Specified by:
      createFactory in interface ObjectNamerOps<SimObject>
      Parameters:
      varName - the name of a scripting-language variable
      packageName - the name of the package (null or an empty string for the unnamed package)
      className - the class name of a factory, excluding the package name
      Returns:
      the factory that was created
      Throws:
      IllegalArgumentException - the factory is not listed in a META-INF/services/org.bzdev.NamedObjectFactory resource or the class name does not refer to subclass of NamedObjectFactory
      UnsupportedOperationException - this object namer does not support scripting;
    • createFactory

      public NamedObjectFactory createFactory(String className) throws IllegalArgumentException
      Create a factory. The factory must have a single-argument constructor that takes its object namer as its argument.
      Specified by:
      createFactory in interface ObjectNamerOps<SimObject>
      Parameters:
      className - the fully-qualified class name of a factory.
      Returns:
      a new factory
      Throws:
      IllegalArgumentException - the factory is not listed in a META-INF/services/org.bzdev.NamedObjectFactory resource or the class name does not refer to subclass of NamedObjectFactory
    • createFactory

      public NamedObjectFactory createFactory(Class clazz) throws IllegalArgumentException
      Create a factory given a class. The factory must have a single-argument constructor that takes its object namer as its argument.
      Specified by:
      createFactory in interface ObjectNamerOps<SimObject>
      Parameters:
      clazz - the factory's class
      Returns:
      a new factory
      Throws:
      IllegalArgumentException - the factory is not listed in a META-INF/services/org.bzdev.NamedObjectFactory resource or the class name does not refer to subclass of NamedObjectFactory