Class SimObject

java.lang.Object
org.bzdev.devqsim.SimObject
All Implemented Interfaces:
NamedObjectOps
Direct Known Subclasses:
AnimationObject2D, DefaultSimObject, GenericSimObject

public abstract class SimObject extends Object implements NamedObjectOps
Base class for simulation objects. This class provides the common methods needed to determine if an object can be looked up by name and to be able to get an object's name. It also allows scripts to be evaluated in a name space initialized with two variables: "sim" (the object's simulation) and "self" (the object itself), and allows these scripts to be scheduled on the event queue or run a script to implement a task.
  • Constructor Details

  • Method Details

    • evalScript

      protected Object evalScript(String script) throws ScriptException, UnsupportedOperationException
      Evaluate a script. This can be used to allow an object's behavior to be partially implemented in a scripting language. Each SimObject is initialized with two variables --- "sim", whose value is the simulation, and "self", whose value is the current SimObject.
      Parameters:
      script - the script to evaluate
      Returns:
      the value computed by the script
      Throws:
      ScriptException - an exception occurred while executing a script
      UnsupportedOperationException - scripting is not supported
    • callableScript

      protected Callable callableScript(String script)
      Create a Callable that will run a script using this object's name space.
      Parameters:
      script - the script
      Returns:
      the callable that will run a script
    • callScriptFunction

      protected Object callScriptFunction(String functionName, Object... args) throws ScriptException, UnsupportedOperationException
      Evaluate a script function. This can be used to allow an object's behavior to be partially implemented in a scripting language. Each SimObject is initialized with two variables --- "sim", whose value is the simulation, and "self", whose value is the current SimObject.
      Parameters:
      functionName - the script function to call
      args - the arguments
      Returns:
      the value computed by the function
      Throws:
      ScriptException - an exception occurred in a script object's method
      UnsupportedOperationException - scripting is not supported
    • callScriptMethod

      protected Object callScriptMethod(Object scriptObject, String methodName, Object... args) throws ScriptException, UnsupportedOperationException
      Evaluate a script object's method. This can be used to allow an object's behavior to be partially implemented in a scripting language. Each SimObject is initialized with two variables --- "sim", whose value is the simulation, and "self", whose value is the current SimObject.
      Parameters:
      scriptObject - the script object whose method is to be invoked
      methodName - the name of the method to invoke
      args - the arguments
      Returns:
      the value computed by the function
      Throws:
      ScriptException - an exception occurred in a script object's method
      UnsupportedOperationException - scripting is not supported
    • getScriptObject

      protected Object getScriptObject(String name)
      Get a script object given a name. The object is obtained from this SimObject's name space.
      Parameters:
      name - the name of the object
      Returns:
      the object; null if there is none
    • putScriptObject

      protected void putScriptObject(String name, Object object) throws UnsupportedOperationException, IllegalArgumentException
      Assign a name to a script object in a sim object's name space. The names "self" and "sim" are reserved.
      Parameters:
      name - the name to assign to the object
      object - the object
      Throws:
      UnsupportedOperationException - the simulation does not support scripting
      IllegalArgumentException - the name provided is a reserved name
    • scheduleScript

      protected 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 - scripting is not supported
    • scheduleCallObject

      protected 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 - scripting is not supported
    • callableObject

      protected Callable callableObject(Object scriptObject)
      Create a Callable that will invoke a script object's call method using this object's namespace.
      Parameters:
      scriptObject - the script object
      Returns:
      a callable that will execute the script object's call method
      Throws:
      UnsupportedOperationException - scripting is not supported
    • scheduleTaskScript

      protected TaskThread scheduleTaskScript(String script, long delay) throws UnsupportedOperationException
      Schedule a Task specified by a script. 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 - scripting is not supported
    • runnableScript

      protected Runnable runnableScript(String script) throws UnsupportedOperationException
      Create a Runnable that will run a script in this object's name space.
      Parameters:
      script - the script
      Returns:
      the runnable created
      Throws:
      UnsupportedOperationException - scripting is not supported
    • runnableObject

      protected Runnable runnableObject(Object scriptObject) throws UnsupportedOperationException
      Create a Runnable that will run a script object in this object's name space. The script object's run method will be called when a task thread is created and scheduled.
      Parameters:
      scriptObject - the script object
      Returns:
      the runnable created
      Throws:
      UnsupportedOperationException - scripting is not supported
    • scheduleTaskObject

      protected TaskThread scheduleTaskObject(Object scriptObject, long delay) throws UnsupportedOperationException
      Schedule a task specified by a script object. 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 - scripting is not supported
    • onDelete

      protected void onDelete()
      Complete the actions necessary to delete a named object. A subclass that overrides this method must call super.onDelete() at some point to complete the object deletion. This may not be within the onDelete method of the subclass if the deletion must be delayed for some reason (e.g., until some processing that is in progress has been completed). Once called, the object will be removed from the object-namer's tables and the object will be marked as deleted, so in general cleanup actions by a subclass should occur before it calls super.onDelete().
    • update

      protected void update(double t, long simtime)
      Update the object's state to that at a specified time. The values of t passed to this method should form an increasing sequence. The default implementation does nothing, and subclasses should override this method if the state needed for drawing must be updated before the drawing is completed. Aside from a direct subclass of SimObject, classes that override this method should call the same method on their superclass unless there is documentation to the contrary.
      Parameters:
      t - the time for which the object should be calculated.
      simtime - the simulation time
    • update

      public final void update()
      Update the object's state to that for the current simulation time. This method calls update(double,long) with appropriate arguments. Subclasses that need to call update should use the current method as it will call update(double,long) with the correct sequence of time arguments.

      The method update(double,long) should be implemented and the method update() should be called when an object's state is to be updated only when the updated value is needed. Update() is used in the org.bzdev.anim2d package for efficiency reasons. Calls to update are not built into methods such as printConfiguration() because for debugging purposes it may be desirable to print the configuration before and after update is called. Methods that are used by update(double,long) should not call update().

      Subclasses should document methods that call update(). The method update() is called by methods defined for the class AnimationObject2D, the base class for all anim2d objects.

    • printConfiguration

      public void printConfiguration()
      Print a simulation object's configuration using a default writer. When a scripting environment is used, the print writer configured for the scripting environment is used; otherwise System.out is used.

      The configuration itself is printed by the method printConfiguration(String,String,boolean,PrintWriter).

    • printConfiguration

      public void printConfiguration(String iPrefix)
      Print a simulation object's configuration using a default writer and specifying an initial prefix. When a scripting environment is used, the print writer configured for the scripting environment is used; otherwise System.out is used.

      The configuration itself is printed by the method printConfiguration(String,String,boolean,PrintWriter).

      Parameters:
      iPrefix - the prefix to use for an initial line with null treated as an empty string
    • printConfiguration

      public void printConfiguration(PrintStream out)
      Print a simulation object's configuration using an output stream. The default method calls printConfiguration(String,Writer) with a print writer constructed from the print stream.

      The configuration itself is printed by the method printConfiguration(String,String,boolean,PrintWriter).

      Parameters:
      out - the output print stream
    • printConfiguration

      public void printConfiguration(String iPrefix, PrintStream out)
      Print a simulation object's configuration using an output stream and specifying an initial prefix. The default method calls printConfiguration(Writer) with the print writer constructed from the print stream.

      The configuration itself is printed by the method printConfiguration(String,String,boolean,PrintWriter).

      Parameters:
      iPrefix - the prefix to use for an initial line with null treated as an empty string
      out - the output print stream
    • printConfiguration

      public void printConfiguration(Writer out)
      Print a simulation object's configuration using a writer. The default method calls printConfiguration(String,String,boolean,PrintWriter) with an empty prefix string for its first argument, a string containing four spaces for its second argument, and the value true as its third argument. The fourth argument is constructed from the out argument described for this method.

      The configuration itself is printed by the method printConfiguration(String,String,boolean,PrintWriter).

      Parameters:
      out - the output print stream
    • printConfiguration

      public void printConfiguration(String iPrefix, Writer out)
      Print a simulation object's configuration using a writer and specifying an initial prefix. The default method calls printConfiguration(String,String,boolean,java.io.PrintWriter) with iPrefix as its first argument, a string containing four spaces appended to iPrefix as its second argument, and with the value true as its third argument. The fourth argument is constructed from the out argument described for this method.

      The configuration itself is printed by the method printConfiguration(String,String,boolean,PrintWriter).

      Parameters:
      iPrefix - the prefix to use for an initial line with null treated as an empty string
      out - the output print stream
    • printConfiguration

      public void printConfiguration(String iPrefix, String prefix, boolean printName, PrintWriter out)
      Print a simulation object's configuration. Simulation objects should implement this method to report how they were configured. The default method just prints a line with the object's name when the second argument has the value true. A subclass must override this method and call printConfiguration(String,String,boolean,PrintWriter) (PrintWriter is defined in the package java.io) on the superclass of the subclass. The overridden method's arguments and the arguments passed to super.printConfiguration must be the same. Furthermore, this call must be the first statement. Additional lines may then be printed with the appropriate indentation. As a recommendation, each additional indentation should typically consist of 4 spaces.

      Whenever this method is overridden, documentation should be provided, at a minimum in the Javadoc comments for the method, indicating what is being printed by the overridden method itself so that programmers do not duplicate the same data when overriding this method

      The methods printConfiguration and printState are analogous. The intention is for printConfiguration to show static or slowly varying data whereas printState should show more rapidly-varying data.

      Normally the printName argument has the value true. Sometimes, however, one might choose to call this method to fill in a table for some other class. In that case, printName should be set to false (e.g., when the caller itself prints the name). The prefix includes the standard indentation, which the other printConfiguration methods in this class set to four spaces. When calling this method explicitly, any previous prefix should be extended with additional spaces. Regardless of the prefix, if printName is true, the line giving the object name will have the indentation specified by iPrefix. When printing lines, one should use either prefix to determine the indentation (iPrefix is used by SimObject itself. Calls to methods such as printConfiguration(String,Writer) that provide iPrefix but not prefix will set prefix to iPrefix concatenated with four spaces.

      To document printConfiguration(String,String,boolean,PrintWriter) methods that override this method, one should follow the following recommendations:

      • for the first subclasses of this class that implements printConfiguration(String,String,boolean,PrintWriter), use the following comment:
        
          /**
           * Print this simulation object's configuration.
           * Documentation for the use of this method is provided by 
           * the documentation for the {@link org.bzdev.devqsim.SimObject}
           * method
           * {@link SimObject#printConfiguration(String,String,boolean,PrintWriter)}.
           * When the third argument has a value of true, the object name and
           * class name will be printed in a standard format with its indentation
           * provided by the iPrefix argument.
           * @param iPrefix {@inheritDoc}
           * @param prefix {@inheritDoc}
           * @param printName {@inheritDoc}
           * @param out {@inheritDoc}
           */
               
        If the printConfiguration(String,String,boolean,PrintWriter) prints something after invoking the same method on its superclass, add the following before the parameter declarations:
        
           * In addition, the configuration that is printed includes the
           * following items.
           * <P>
           * Defined in {@link ...}:
           * <UL>
           *     ...
           * </UL>
               
        where the link is to the subclass overriding this method and the unnumbered list contains items describing each line or set of lines in the output.
      • For subclasses of classes that have overridden printConfiguration(String,String,boolean,PrintWriter) and that are following these conventions, use the following javadoc comment:
        
          /**
           * {@inheritDoc}
           * <P>
           * Defined in {@link ...}:
           * <UL>
           *    ...
           * </UL>
           * @param iPrefix {@inheritDoc}
           * @ param prefix {@inheritDoc}
           * @param printName {@inheritDoc}
           * @param out {@inheritDoc}
           */
               
        For this case, if no superclass contains the following, it should be added after the first @inheritDoc directive:
        
           * In addition, the configuration that is printed includes the
           * following items.
               
      • For separate libraries, the @inheritDoc mechanism will not be able to find text to copy as access to the source code is needed by the javadoc program. In this case, the printConfiguration(String,String,boolean,PrintWriter) methods of each subclasses whose first superclass implements printConfiguration(String,String,boolean,PrintWriter) should either duplicate the javadoc comment so that the @inheritDoc mechanism can append additional list items as done above or it should include a link to the method providing those items.
      For examples of the documentation this convention generates, please look at the documentation for AnimationObject2D.printConfiguration(String,String,boolean,PrintWriter) and AnimationLayer2D.printConfiguration(String,String,boolean,PrintWriter).

      These recommendations, if followed, will simply documenting this method for subclasses of SimObject as one can use the inheritDoc mechanism so that each method's documentation will list all the fields it prints.

      Parameters:
      iPrefix - the prefix to use for an initial line when printName is true with null treated as an empty string
      prefix - a prefix string (typically whitespace) to put at the start of each line other than the initial line that is printed when printName is true
      printName - requests printing the name of an object
      out - the output print writer
    • printState

      public void printState()
      Print a simulation object's state on a default output stream. When a scripting environment is used, the print writer configured for the scripting environment is used; otherwise System.out is used.

      The state itself is printed by the method printState(String,String,boolean,PrintWriter).

    • printState

      public void printState(String iPrefix)
      Print a simulation object's state on a default output stream and specifying an initial prefix. When a scripting environment is used, the print writer configured for the scripting environment is used; otherwise System.out is used.

      The state itself is printed by the method printState(String,String,boolean,PrintWriter).

      Parameters:
      iPrefix - the prefix to use for an initial line when printName is true with null treated as an empty string
    • printState

      public void printState(Writer out)
      Print a simulation object's state using a writer. The default method calls printState(String,String,boolean,PrintWriter) with an empty string as its first argument, a string containing four spaces as its second argument, and the value truefor its third argument. The fourth argument is constructed from the out argument described for this method.

      The state itself is printed by the method printState(String,String,boolean,PrintWriter).

      Parameters:
      out - the output writer
    • printState

      public void printState(String iPrefix, Writer out)
      Print a simulation object's state using a writer. The default method calls printState(String,String,boolean,java.io.PrintWriter) with iPrefix as the first argument, four spaces appended to iPrefix as the second argument, true as its third argument, and a print writer (constructed from out if necessary) as its fourth argument.

      The state itself is printed by the method printState(String,String,boolean,PrintWriter).

      Parameters:
      iPrefix - the prefix to use for an initial line when printName is true with null treated as an empty string
      out - the output print stream
    • printState

      public void printState(PrintStream out)
      Print a simulation object's state using a print stream. The default method calls printState(Writer).

      The state itself is printed by the method printState(String,String,boolean,PrintWriter).

      Parameters:
      out - the output print stream
    • printState

      public void printState(String iPrefix, PrintStream out)
      Print a simulation object's state using a print stream and specifying an initial prefix. The default method calls printState(String,Writer).

      The state itself is printed by the method printState(String,String,boolean,PrintWriter).

      Parameters:
      iPrefix - the prefix to use for an initial line when printName is true with null treated as an empty string
      out - the output print stream
    • printState

      public void printState(String iPrefix, String prefix, boolean printName, PrintWriter out)
      Print a simulation object's state. Simulation objects should implement this method to report how they were configured. The default method just prints a line with the object's name when the second argument has the value true. A subclass must override this method and call printState(java.lang.String,boolean,PrintWriter) (PrintWriter is defined in the package java.io) on the superclass of the subclass. The overridden method's arguments and the arguments passed to super.printState must be the same. Furthermore, this call must be the first statement. Additional lines may then be printed with the appropriate indentation. As a recommendation, each additional indentation should typically consist of 4 spaces.

      Whenever this method is overridden, documentation should be provided, at a minimum in the Javadoc comments for the method, indicating what is being printed by the overridden method itself so that programmers do not duplicate the same data when overriding this method

      The methods printConfiguration and printState are analogous. The intention is for printConfiguration to show static or slowly varying data whereas printState should show more rapidly-varying data.

      Normally the printName argument has the value true. Sometimes, however, one might choose to call this method to fill in a table for some other class. In that case, printName should be set to false (e.g., when the caller itself prints the name). The prefix includes the standard indentation, which the other printConfiguration methods in this class set to four spaces. When calling this method explicitly, any previous prefix should be extended with additional spaces. Regardless of the prefix, if printName is true, the line giving the object name will have no indentation.

      To document printState(String,String,boolean,PrintWriter) methods that override this method, one should follow the following recommendations:

      • for the first subclasses of this class that implements printState(String,String,boolean,PrintWriter) use the following comment:
        
          /**
           * Print this simulation object's state.
           * Documentation for the use of this method is provided by
           * the documentation for the {@link org.bzdev.devqsim.SimObject}
           * method
           * {@link SimObject#printState(String,String,boolean,PrintWriter)}.
           * When the third argument has a value of true, the object name and
           * class name will be printed in a standard format with its indentation
           * provided by the iPrefix argument.
           * @param iPrefix {@inheritDoc}
           * @param prefix {@inheritDoc}
           * @param printName {@inheritDoc}
           * @param out {@inheritDoc}
           */
               
        If the method printState(String,String,boolean,PrintWriter) prints something after invoking the same method on its superclass, add the following before the parameter declarations:
        
           * In addition, the state that is printed includes the
           * following items.
           * <P>
           * Defined in {@link ...}:
           * <UL>
           *     ...
           * </UL>
               
        where the link is to the subclass overriding this method and the unnumbered list contains items describing each line or set of lines in the output.
      • For subclasses of classes that have overridden printState(String,String,boolean,PrintWriter) and that are following these conventions, use the following javadoc comment:
        
          /**
           * {@inheritDoc}
           * Defined in {@link ...}:
           * <UL>
           *    ...
           * </UL>
           * @param iPrefix {@inheritDoc}
           * @ param prefix {@inheritDoc}
           * @param printName {@inheritDoc}
           * @param out {@inheritDoc}
           */
               
        For this case, if no superclass contains the following, it should be added after the first @inheritDoc directive:
        
           * In addition, the state that is printed includes the
           * following items.
               
      • For separate libraries, the @inheritDoc mechanism will not be able to find text to copy as access to the source code is needed by the javadoc program. In this case, the printState(String,String,boolean,PrintWriter) methods of each subclasses whose first superclass implements printState(String,String,boolean,PrintWriter) should either duplicate the javadoc comment so that the @inheritDoc mechanism can append additional list items as done above or it should include a link to the method providing those items.
      For examples of the documentation this convention generates, please look at the documentation for AnimationObject2D.printState(String,String,boolean,PrintWriter) and DirectedObject2D.printState(String,String,boolean,PrintWriter).

      These recommendations, if followed, will simply documenting this method for subclasses of SimObject as one can use the inheritDoc mechanism so that each method's documentation will list all the fields it prints.

      Parameters:
      iPrefix - the prefix to use for an initial line when printName is true with null treated as an empty string
      prefix - a prefix string (typically whitespace) to put at the start of each line other than the initial line that is printed when printName is true
      printName - requests printing the name of an object
      out - the output print writer
    • scheduleCall

      protected 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);
      Parameters:
      callable - the Callable to run.
      Returns:
      the event scheduled
    • scheduleCall

      protected TaskSimulationEvent scheduleCall(Callable callable, String tag)
      Schedule a call, adding a tag. 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:
      callable - the Callable to run.
      tag - a descriptive string for the Callable
      Returns:
      the event scheduled
    • scheduleCall

      protected 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.
      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

      protected TaskSimulationEvent scheduleCall(Callable callable, long delay, String tag)
      Schedule a call, providing a delay and adding a tag. The call method of a Callable will be run at a particular simulation time.
      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
      tag - a descriptive string for the Callable
      Returns:
      the event scheduled
    • unscheduledTaskThread

      protected TaskThread unscheduledTaskThread(Runnable runnable)
      Create a task thread but do not schedule it for execution.
      Parameters:
      runnable - the Runnable used by the thread
      Returns:
      the task thread
    • unscheduledTaskThread

      protected TaskThread unscheduledTaskThread(Runnable runnable, String tag)
      Create a task thread, adding a tag, but do not schedule it for execution.
      Parameters:
      runnable - the Runnable used by the thread
      tag - a string describing a task thread
      Returns:
      the task thread
    • scheduleTask

      protected TaskThread scheduleTask(Runnable runnable, long delay)
      Schedule a Task. 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.
      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

      protected TaskThread scheduleTask(Runnable runnable, long delay, String tag)
      Schedule a Task, adding a tag. 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.
      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
      tag - a string describing a task thread
      Returns:
      the thread that will run this task
    • scheduleTask

      protected TaskThread scheduleTask(Runnable runnable)
      Start a simulation task with a delay of 0. This is a convenience method that is equivalent to scheduleTask(runnable, 0);
      Parameters:
      runnable - the Runnable to execute.
      Returns:
      the thread running this task
    • scheduleTask

      protected TaskThread scheduleTask(Runnable runnable, String tag)
      Start a simulation task with a delay of 0, adding a tag. This is a convenience method that is equivalent to scheduleTask(runnable, 0);
      Parameters:
      runnable - the Runnable to execute.
      tag - a string describing a task thread
      Returns:
      the thread running this task
    • startImmediateTask

      protected 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.
      Parameters:
      runnable - the Runnable to execute.
      Returns:
      the thread running this task
      Throws:
      IllegalStateException
    • startImmediateTask

      protected TaskThread startImmediateTask(Runnable runnable, String tag) throws IllegalStateException
      Start a simulation task immediately, blocking the current task and adding a tag. 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.
      Parameters:
      runnable - the Runnable to execute.
      tag - a string describing a task thread
      Returns:
      the thread running this task
      Throws:
      IllegalStateException
    • bindCallable

      protected final SimObjectCallable bindCallable(Callable callable)
      Bind a callable to the current object. The use of this method allows simulation listeners to appropriately attribute a callable to a simulation object when this would not otherwise be possible. It specifically supports task queues and server queues.
      Parameters:
      callable - the callable
      Returns:
      a binding of the current object with the callable.
    • bindCallable

      protected final <Server extends QueueServer> SimObjQueueCallable<Server> bindCallable(QueueCallable<Server> callable)
      Bind a queue callable to the current object. The use of this method allows simulation listeners to appropriately attribute a callable to a simulation object when this would not otherwise be possible. It specifically supports task queues and server queues.
      Type Parameters:
      Server - the type of a server for the callable
      Parameters:
      callable - the callable
      Returns:
      a binding of the current object with the callable.
    • bindCallable

      protected final SimObjectCallable bindCallable(Callable callable, String tag)
      Bind a callable to the current object, providing a descriptive string. The use of this method allows simulation listeners to appropriately attribute a callable to a simulation object when this would not otherwise be possible. It specifically supports task queues and server queues.
      Parameters:
      callable - the callable
      tag - a descriptive string
      Returns:
      a binding of the current object with the callable.
    • bindCallable

      protected final <Server extends QueueServer> SimObjQueueCallable bindCallable(QueueCallable<Server> callable, String tag)
      Bind a queue callable to the current object, providing a descriptive string. The use of this method allows simulation listeners to appropriately attribute a callable to a simulation object when this would not otherwise be possible. It specifically supports task queues and server queues.
      Type Parameters:
      Server - the type of a server for the callable
      Parameters:
      callable - the callable
      tag - a descriptive string
      Returns:
      a binding of the current object with the callable.
    • bindRunnable

      protected final SimObjectRunnable bindRunnable(Runnable runnable)
      Bind a runnable to the current object. The use of this method allows simulation listeners to appropriately attribute a runnable to a simulation object when this would not otherwise be possible. It specifically supports task queues and server queues.
      Parameters:
      runnable - the runnable
      Returns:
      a binding of the current object with the runnable.
    • bindRunnable

      protected final <Server extends QueueServer> SimObjQueueRunnable<Server> bindRunnable(QueueRunnable<Server> runnable)
      Bind a queue runnable to the current object. The use of this method allows simulation listeners to appropriately attribute a runnable to a simulation object when this would not otherwise be possible. It specifically supports task queues and server queues.
      Type Parameters:
      Server - the type of a server for the runnable
      Parameters:
      runnable - the queue runnable
      Returns:
      a binding of the current object with the runnable.
    • bindRunnable

      protected final SimObjectRunnable bindRunnable(Runnable runnable, String tag)
      Bind a runnable to the current object, providing a descriptive string. The use of this method allows simulation listeners to appropriately attribute a runnable to a simulation object when this would not otherwise be possible. It specifically supports task queues and server queues.
      Parameters:
      runnable - the runnable
      tag - a descriptive string
      Returns:
      a binding of the current object with the runnable.
    • bindRunnable

      protected final <Server extends QueueServer> SimObjQueueRunnable<Server> bindRunnable(QueueRunnable<Server> runnable, String tag)
      Bind a queue runnable to the current object, providing a descriptive string. The use of this method allows simulation listeners to appropriately attribute a runnable to a simulation object when this would not otherwise be possible. It specifically supports task queues and server queues.
      Type Parameters:
      Server - the type of a server for the runnable
      Parameters:
      runnable - the runnable
      tag - a descriptive string
      Returns:
      a binding of the current object with the runnable.
    • addSimulationListener

      public void addSimulationListener(SimulationListener l)
      Add a simulation listener.
      Parameters:
      l - the action listener to add.
    • removeSimulationListener

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

      protected EvntListenerList getEventListenerList()
      Get the event listener list. All listeners in the list should be of type SimulationListener. Callers should treat the list as a read-only one.
      Returns:
      the listener list
      See Also:
    • getTraceSets

      public TraceSet[] getTraceSets()
      Get the trace sets currently in use.
      Returns:
      an array containing the trace sets for this object
    • usesTraceSet

      public boolean usesTraceSet(TraceSet traceSet)
      Determine if a trace set is being used.
      Parameters:
      traceSet - the traceSet to check
      Returns:
      true if traceSet is a member of the current object's set of trace sets; false otherwise
    • addTraceSet

      public void addTraceSet(TraceSet traceSet)
      Add a trace set.
      Parameters:
      traceSet - the trace set to add
    • removeTraceSet

      public void removeTraceSet(TraceSet traceSet)
      Remove a trace set.
      Parameters:
      traceSet - the trace set to remove
    • clearTraceSets

      public void clearTraceSets()
      Remove all trace sets.
    • trace

      protected void trace(int level, String format, Object... args)
      Generate a trace message. The message will be displayed for all trace sets added to this object provided. For each trace set, there must be a defined output and the level passed to this method must not be larger than the level specified by the trace set. Each trace set can define an output, with the simulation providing a default. Regardless, if the level passed to this method is negative, nothing will be printed. If the output and the simulation default output is null, nothing is printed.

      Each call will print a formatted string starting with a tag delimited by square brackets. This tag contains the following items:

      • <N> where N is level argument.
      • the name of this object.
      • the current time in simulation-tick units.
      • the current time as a real number, surrounded by parentheses.

      A useful convention is to create a configuration class for each package that makes use of this method. This class should contain several static package-private fields such as

           static int level1 = -1;
           static int level2 = -1;
       
      and two corresponding methods
            public static void setTraceLevels(int lev1, int lev2( P
               if (level1 < -1 || level2 < -1)
                   throw new IllegalArgumentException(...)
               }
               level1 = lev1;
               level2 = lev2;
            }
      
            public static
               <T extends Enum<T>>
               void setTraceLevels(T lev1, T lev2)
            {
               level1 = (level1 == null)? -1: lev1.ordinal();
               level2 = (level2 == null)? -1: lev2.ordinal();
            }
       
      The second of these two methods is useful when one would like to define trace levels using an enumeration to provide better mnemonics for users of a package. Regardless, the class or methods that set trace levels should include documentation describing what is being traced at a given level.
      Parameters:
      level - the trace level
      format - a format string
      args - the arguments printed according to the format string
    • trace

      protected void trace(Enum<?> level, String format, Object... args)
      Generate a trace message specifying the level via an enumeration constant. The message will be displayed for all trace sets added to this object provided that the level argument is no larger than the level defined for a given trace set. For each trace set, there must be a defined output for an output to be displaced. Each trace set can define an output, with the simulation providing a default. If all alternative outputs are null, nothing will be printed.

      This method is provided so that one can create an enum to represent debugging levels, thus giving them symbolic names. It is equivalent to calling trace(int,String, Object...) with its first argument set to the ordinal value of the enumeration. The disadvantage is that the enumeration must be known at compile time and as a result, one cannot configure trace levels at run time (configuring at run time is useful for when independently written class libraries are used).

      Each call will print a formatted string starting with a tag delimited by square brackets. This tag contains the following items:

      • <N> where N is the ordinal value of the level argument.
      • the name of this object.
      • the current time in simulation-tick units.
      • the current time as a real number, surrounded by parentheses.
      Parameters:
      level - an enum whose ordinal value provides the trace level; null if nothing is to be printed
      format - a format string
      args - the arguments printed according to the format string
    • clone

      protected Object clone() throws CloneNotSupportedException
      Creates and returns a copy of this object. This method will throw the exception CloneNotSupportedException if the object is interned.
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException - a clone could not be created
      See Also:
    • isInterned

      public boolean isInterned()
      Determine if an object is interned in a object namer's tables.
      Specified by:
      isInterned in interface NamedObjectOps
      Returns:
      true if the object is interned; false if not
    • getObjectNamer

      protected Simulation getObjectNamer()
      Get the object namer for a named object.
      Returns:
      the object namer for this named object
    • getName

      public final String getName()
      Get an object's name.
      Specified by:
      getName in interface NamedObjectOps
      Returns:
      the name of the object
    • canDelete

      public boolean canDelete()
      Determine if this named object can be deleted. A named object can be deleted if the method delete has not been called and if the object is not in a state that prevents the object from being deleted. Subclasses that override this method must call canDelete() for their superclasses and return false if the superclass' canDelete method returns false. The default method returns true if delete() has not been called and returned true.
      Specified by:
      canDelete in interface NamedObjectOps
      Returns:
      true if this object can be deleted; false otherwise
    • delete

      public final boolean delete()
      Delete an object. An object can only be deleted once. If this method returns true, the object (if interned) will have been removed from the object namer tables.

      The implementations provided by DefaultNamedObect and generated because of a @NamedObject annotation provide a protected method named onDelete. A subclass that overrides onDelete() must call the onDelete method of its superclass after it's onDelete method has been called and any cleanup actions performed. In some cases, this may happen at a later time (e.g., if a thread is used for some of the cleanup operations or if it is otherwise necessary to wait).

      Specified by:
      delete in interface NamedObjectOps
      Returns:
      true if the deletion request was accepted; false otherwise
    • isDeleted

      public final boolean isDeleted()
      Determine if an object has been deleted. An object is deleted if the method delete() has been called and returned true.
      Specified by:
      isDeleted in interface NamedObjectOps
      Returns:
      true if deleted; false otherwise
    • deletePending

      public final boolean deletePending()
      Determine if an object is being deleted. An deletion is pending if the method delete() has been called and returned true but the deletion has not been completed.
      Specified by:
      deletePending in interface NamedObjectOps
      Returns:
      true if deletion is pending; false otherwise