SimJava
v2.0

eduni.simjava
Class Sim_entity

java.lang.Object
  |
  +--java.lang.Thread
        |
        +--eduni.simjava.Sim_entity
All Implemented Interfaces:
java.lang.Cloneable, java.lang.Runnable

public class Sim_entity
extends java.lang.Thread
implements java.lang.Cloneable

This class represents the types of entities or processes of the simulation.

To define an entity type for the simulation this class needs to be extended. The subclass needs to override body() to define the entity's behaviour. Methods beginning with the prefix sim_ are runtime methods to be called within body().

Since version 2.0, entities don't need to check transient or termination conditions. These are all maintained and checked by Sim_system. To check whether the termination condition has been satisfied, entities should use the Sim_system.running() method. As such. entities that exhibit a continuous, looping behaviour should have a body() as follows:

...
public void body() {
  while (Sim_system.running()) {
    ...
    // Entity's behaviour
    ...
  }
}
...

Entities are provided with a selection of runtime methods to implement their behaviour. The main runtime method families are the following:

In order to collect statistical measurements from entities a Sim_stat object needs to be defined for the entity. This is the object in charge of collecting observations and calculating measurements. Measures of interest could be default of custom. Default measures are those which can be considered in most simulations and whose update can be automatically carried out without user effort. Custom measures on the other hand are measures with simulation specific meaning that need to be updated by the user. An example of an entity defining and updating measures of interest follows:

class AnEntityType extends Sim_entity {
  ...
  Sim_stat stat;
  ...
  AnEntityType(String name) {
    ...
    stat = new Sim_stat();
    stat.add_measure(Sim_stat.UTILISATION); // A default measure
    stat.add_measure(Sim_stat.RESIDENCE_TIME); // Another default measure
    stat.add_measure("Loss rate", Sim_stat.RATE_BASED); // A rate-based custom measure
    set_stat(stat);
    ...
  }
  ...
  public void body() {
    ...
    if (aLossOccured) {
      stat.update("Loss rate", Sim_system.sim_clock()); // The custom measure is updated
    }
    ...
    sim_completed(e); // An event has completed service
    ...
  }
  ...
}

The sim_completed method seen above, is used to specify when a received event is considered to have completed all service at the entity. This method needs to be called to notify the entity's Sim_stat object and to notify Sim_system that an event has completed service. More details on statistical measurements can be found in the SimJava Tutorial.

One additional note concerning entities' behaviour has to do with output analysis. In the case of independent replications having been defined as an output analysis method, it could be necessary to provide code with which to reset an entity's fields. This is required since, for each replication, the entities must be reset to their original state. This is not required for primitive types or immutable objects. However if objects such as a Vector have been modified during the simulation run, they should be reset to their original state. This would take place at the end of the body() method. For example:

class AnEntityType extends Sim_entity {
  ...
  Vector aVector = new Vector();
  ...
  public void body() {
    while (Sim_system.running()) {
      ...
      aVector.add(anObject); // The Vector's contents are modified
      ...
    }
    aVector.clear(); // The Vector is reset to its original state
  }
  ...
}

See Also:
Sim_event, Sim_stat, Sim_system

Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Constructor Summary
Sim_entity(java.lang.String name)
          Creates a new entity.
Sim_entity(java.lang.String name, java.lang.String image_name, int x, int y)
          The constructor for use with the eduni.simanim animation package.
 
Method Summary
 void add_generator(Generator generator)
          Add a sample generator to this entity.
 void add_param(Anim_param param)
          Add a parameter to this entity.
 void add_port(Sim_port port)
          Add a port to this entity.
 void body()
          The method which defines the behaviour of the entity.
protected  java.lang.Object clone()
          Get a clone of the entity.
 int get_id()
          Get the unique id number assigned to this entity
 java.lang.String get_name()
          Get the name of this entity
 Sim_port get_port(Sim_event ev)
          Get the port through which an event arrived.
 Sim_port get_port(java.lang.String name)
          Get the port with a given name.
 Sim_stat get_stat()
          Get the entity's Sim_stat object.
 void send_on(Sim_event ev, Sim_port p)
          Send on an event to an other entity through a port.
 void set_invisible(boolean b)
          Make entity icon invisible
 void set_stat(Sim_stat stat)
          Define a Sim_stat object for this entity.
 int sim_cancel(Sim_predicate p, Sim_event ev)
          Cancel the first event matching a predicate waiting in the entity's future queue.
 void sim_completed(Sim_event e)
          Signal that an event has completed service.
 int sim_current()
          Get the id of the currently running entity
 void sim_get_next(Sim_event ev)
          Get the first event waiting in the entity's deferred queue, or if there are none, wait for an event to arrive.
 void sim_get_next(Sim_predicate p, Sim_event ev)
          Get the first event matching a predicate from the deferred queue, or if none match, wait for a matching event to arrive.
 double sim_hold_for(double delay, Sim_event ev)
          Deprecated. As of SimJava version 2.0, replaced by sim_pause_for(double delay, Sim_event ev). This method was deprecated because of the new statistical support present to entities. When an entity holds it must now be specified if the hold corrssponds to the entity being active or inactive. The original sim_hold() methods are equivalent to their respective sim_pause() methods.
 void sim_hold(double delay)
          Deprecated. As of SimJava version 2.0, replaced by sim_pause(double delay). This method was deprecated because of the new statistical support present to entities. When an entity holds it must now be specified if the hold corrssponds to the entity being active or inactive. The original sim_hold() methods are equivalent to their respective sim_pause() methods.
 double sim_pause_for(double delay, Sim_event ev)
          Set the entity to be inactive for a time period or until it is interrupted by the arrival of an event.
 double sim_pause_for(Sim_predicate p, double delay, Sim_event ev)
          Set the entity to be inactive for a time period or until it is interrupted by the arrival of an event matching a predicate.
 void sim_pause_until(Sim_event ev)
          Set the entity to be inactive until it receives an event.
 void sim_pause_until(Sim_predicate p, Sim_event ev)
          Set the entity to eb inactive until it receives an event matching a specific predicate.
 void sim_pause(double delay)
          Set the entity to be inactive for a time period.
 double sim_process_for(double delay, Sim_event ev)
          Set the entity to be active for a time period or until it is interrupted by the arrival of an event.
 double sim_process_for(Sim_predicate p, double delay, Sim_event ev)
          Set the entity to be active for a time period or until it is interrupted by the arrival of an event matching a predicate.
 void sim_process_until(Sim_event ev)
          Set the entity to be active until it receives an event.
 void sim_process_until(Sim_predicate p, Sim_event ev)
          Set the entity to be active until it receives an event matching a specific predicate.
 void sim_process(double delay)
          Set the entity to be active for a given time period.
 void sim_putback(Sim_event ev)
          Put an event back on the deferred queue.
 void sim_schedule(int dest, double delay, int tag)
          Send an event to another entity by id number and with no data.
 void sim_schedule(int dest, double delay, int tag, java.lang.Object data)
          Send an event to another entity by id number, with data.
 void sim_schedule(Sim_port dest, double delay, int tag)
          Send an event to another entity through a port, with no data.
 void sim_schedule(Sim_port dest, double delay, int tag, java.lang.Object data)
          Send an event to another entity through a port, with data.
 void sim_schedule(java.lang.String dest, double delay, int tag)
          Send an event to another entity through a port with a given name, with no data.
 void sim_schedule(java.lang.String dest, double delay, int tag, java.lang.Object data)
          Send an event to another entity through a port with a given name, with data.
 void sim_select(Sim_predicate p, Sim_event ev)
          Extract the first event matching a predicate waiting in the entity's deferred queue.
 void sim_trace(int level, java.lang.String msg)
          Write a trace message.
 double sim_wait_for(double delay, Sim_event ev)
          Wait for an event to arrive or until a time period elapsed.
 double sim_wait_for(Sim_predicate p, double delay, Sim_event ev)
          Wait for an event matching a specific predicate to arrive or until a time period elapses.
 void sim_wait_for(Sim_predicate p, Sim_event ev)
          Wait for an event matching a specific predicate.
 void sim_wait(Sim_event ev)
          Wait for an event to arrive.
 int sim_waiting()
          Count how many events are waiting in the entiy's deferred queue
 int sim_waiting(Sim_predicate p)
          Count how many events matching a predicate are waiting in the entity's deferred queue.
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, run, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, toString, yield
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Sim_entity

public Sim_entity(java.lang.String name)
Creates a new entity.
Parameters:
name - The name to be associated with this entity

Sim_entity

public Sim_entity(java.lang.String name,
                  java.lang.String image_name,
                  int x,
                  int y)
The constructor for use with the eduni.simanim animation package.
Parameters:
name - The name to be associated with this entity
image_name - The name of the gif image file for this entity's icon (without the .gif extension).
x - The X co-ordinate at which the entity should be drawn
y - The Y co-ordinate at which the entity should be drawn
Method Detail

set_invisible

public void set_invisible(boolean b)
Make entity icon invisible

get_name

public java.lang.String get_name()
Get the name of this entity
Returns:
The entity's name

get_id

public int get_id()
Get the unique id number assigned to this entity
Returns:
The id number

get_port

public Sim_port get_port(Sim_event ev)
Get the port through which an event arrived.
Parameters:
ev - The event
Returns:
The port which sent the event or null if it could not be found

get_port

public Sim_port get_port(java.lang.String name)
Get the port with a given name.
Parameters:
name - The name of the port to search for
Returns:
The port or null if it could not be found

add_port

public void add_port(Sim_port port)
Add a port to this entity.
Parameters:
port - The port to add

add_param

public void add_param(Anim_param param)
Add a parameter to this entity. Used with the eduni.simanim package for animation.
Parameters:
param - The parameter to add

set_stat

public void set_stat(Sim_stat stat)
Define a Sim_stat object for this entity.
Parameters:
param - The Sim_stat object

get_stat

public Sim_stat get_stat()
Get the entity's Sim_stat object.
Returns:
The Sim_stat object defined for this entity or null if none is defined.

body

public void body()
The method which defines the behaviour of the entity. This method should be overidden in subclasses of Sim_entity.

sim_trace

public void sim_trace(int level,
                      java.lang.String msg)
Write a trace message.
Parameters:
level - The level at which the trace should be printed, used with Sim_system.set_trace_level() to control what traces are printed
msg - The message to be printed

sim_completed

public void sim_completed(Sim_event e)
Signal that an event has completed service.
Parameters:
e - The event that has completed service

sim_schedule

public void sim_schedule(int dest,
                         double delay,
                         int tag,
                         java.lang.Object data)
Send an event to another entity by id number, with data. Note that the tag 9999 is reserved.
Parameters:
dest - The unique id number of the destination entity
delay - How long from the current simulation time the event should be sent
tag - An user-defined number representing the type of event.
data - The data to be sent with the event.

sim_schedule

public void sim_schedule(int dest,
                         double delay,
                         int tag)
Send an event to another entity by id number and with no data. Note that the tag 9999 is reserved.
Parameters:
dest - The unique id number of the destination entity
delay - How long from the current simulation time the event should be sent
tag - An user-defined number representing the type of event.

sim_schedule

public void sim_schedule(Sim_port dest,
                         double delay,
                         int tag,
                         java.lang.Object data)
Send an event to another entity through a port, with data. Note that the tag 9999 is reserved.
Parameters:
dest - The port to send the event through
delay - How long from the current simulation time the event should be sent
tag - An user-defined number representing the type of event.
data - The data to be sent with the event.

sim_schedule

public void sim_schedule(Sim_port dest,
                         double delay,
                         int tag)
Send an event to another entity through a port, with no data. Note that the tag 9999 is reserved.
Parameters:
dest - The port to send the event through
delay - How long from the current simulation time the event should be sent
tag - An user-defined number representing the type of event.

sim_schedule

public void sim_schedule(java.lang.String dest,
                         double delay,
                         int tag,
                         java.lang.Object data)
Send an event to another entity through a port with a given name, with data. Note that the tag 9999 is reserved.
Parameters:
dest - The name of the port to send the event through
delay - How long from the current simulation time the event should be sent
tag - An user-defined number representing the type of event.
data - The data to be sent with the event.

sim_schedule

public void sim_schedule(java.lang.String dest,
                         double delay,
                         int tag)
Send an event to another entity through a port with a given name, with no data. Note that the tag 9999 is reserved.
Parameters:
dest - The name of the port to send the event through
delay - How long from the current simulation time the event should be sent
tag - An user-defined number representing the type of event.

sim_waiting

public int sim_waiting(Sim_predicate p)
Count how many events matching a predicate are waiting in the entity's deferred queue.
Parameters:
p - The event selection predicate
Returns:
The count of matching events

sim_waiting

public int sim_waiting()
Count how many events are waiting in the entiy's deferred queue
Returns:
The count of events

sim_select

public void sim_select(Sim_predicate p,
                       Sim_event ev)
Extract the first event matching a predicate waiting in the entity's deferred queue.
Parameters:
p - The event selection predicate
ev - The event matched is copied into <body>ev</body> if it points to a blank event, or discarded if ev is null

sim_cancel

public int sim_cancel(Sim_predicate p,
                      Sim_event ev)
Cancel the first event matching a predicate waiting in the entity's future queue.
Parameters:
p - The event selection predicate
ev - The event matched is copied into ev if it points to a blank event, or discarded if ev is null
Returns:
The number of events cancelled (0 or 1)

sim_putback

public void sim_putback(Sim_event ev)
Put an event back on the deferred queue.
Parameters:
ev - The event to put back

sim_get_next

public void sim_get_next(Sim_predicate p,
                         Sim_event ev)
Get the first event matching a predicate from the deferred queue, or if none match, wait for a matching event to arrive.
Parameters:
p - The predicate to match
ev - The event matched is copied into ev if it points to a blank event, or discarded if ev is null

sim_get_next

public void sim_get_next(Sim_event ev)
Get the first event waiting in the entity's deferred queue, or if there are none, wait for an event to arrive.
Parameters:
ev - The event matched is copied into ev if it points to a blank event, or discarded if ev is null

sim_current

public int sim_current()
Get the id of the currently running entity
Returns:
The currently running entity's id number

send_on

public void send_on(Sim_event ev,
                    Sim_port p)
Send on an event to an other entity through a port.
Parameters:
ev - The event to send
p - The port through which to send the event

clone

protected java.lang.Object clone()
                          throws java.lang.CloneNotSupportedException
Get a clone of the entity. This is used when independent replications have been specified as an output analysis method. Clones or backups of the entities are made in the beginning of the simulation in order to reset the entities for each subsequent replication. This method should not be called by the user.
Overrides:
clone in class java.lang.Object
Returns:
A clone of the entity

add_generator

public void add_generator(Generator generator)
Add a sample generator to this entity. This method is used in order to allow Sim_system to reseed the generator. This is performed when independent replications have been selected as an output analysis method. If this method is not used for a generator then the seed used in the subsequent replication will be the last one produced by the generator in the previous run.
Parameters:
generator - The sample generator to be added to the entity

sim_process

public void sim_process(double delay)
Set the entity to be active for a given time period.
Parameters:
delay - The time period for which the entity will be active

sim_process_until

public void sim_process_until(Sim_event ev)
Set the entity to be active until it receives an event. Note that the entity will be interrupted only by future events.
Parameters:
ev - The event to which the arriving event will be copied to

sim_process_until

public void sim_process_until(Sim_predicate p,
                              Sim_event ev)
Set the entity to be active until it receives an event matching a specific predicate. Note that the entity will be interrupted only by future events.
Parameters:
p - The predicate to match
ev - The event to which the arriving event will be copied to

sim_process_for

public double sim_process_for(double delay,
                              Sim_event ev)
Set the entity to be active for a time period or until it is interrupted by the arrival of an event. Note that the entity will be interrupted only by future events.
Parameters:
delay - The time period for which the entity will be active unless interrupted
ev - The event to which the arriving event will be copied to
Returns:
The time of the specified time period remaining after the arrival occured

sim_process_for

public double sim_process_for(Sim_predicate p,
                              double delay,
                              Sim_event ev)
Set the entity to be active for a time period or until it is interrupted by the arrival of an event matching a predicate. Note that the entity will be interrupted only by future events.
Parameters:
p - The predicate to match
delay - The time period for which the entity will be active unless interrupted
ev - The event to which the arriving event will be copied to
Returns:
The time of the specified time period remaining after the arrival occured

sim_pause

public void sim_pause(double delay)
Set the entity to be inactive for a time period.
Parameters:
delay - The time period for which the entity will be inactive

sim_pause_until

public void sim_pause_until(Sim_event ev)
Set the entity to be inactive until it receives an event. Note that the entity will be interrupted only by future events.
Parameters:
ev - The event to which the arriving event will be copied to

sim_pause_until

public void sim_pause_until(Sim_predicate p,
                            Sim_event ev)
Set the entity to eb inactive until it receives an event matching a specific predicate. Note that the entity will be interrupted only by future events.
Parameters:
p - The predicate to match
ev - The event to which the arriving event will be copied to

sim_pause_for

public double sim_pause_for(double delay,
                            Sim_event ev)
Set the entity to be inactive for a time period or until it is interrupted by the arrival of an event. Note that the entity will be interrupted only by future events.
Parameters:
delay - The time period for which the entity will be inactive unless interrupted
ev - The event to which the arriving event will be copied to
Returns:
The time of the specified time period remaining after the arrival occured

sim_pause_for

public double sim_pause_for(Sim_predicate p,
                            double delay,
                            Sim_event ev)
Set the entity to be inactive for a time period or until it is interrupted by the arrival of an event matching a predicate. Note that the entity will be interrupted only by future events.
Parameters:
p - The predicate to match
delay - The time period for which the entity will be inactive unless interrupted
ev - The event to which the arriving event will be copied to
Returns:
The time of the specified time period remaining after the arrival occured

sim_wait

public void sim_wait(Sim_event ev)
Wait for an event to arrive. Note that this method doesn't check the entity's deferred queue.
Parameters:
ev - The event to which the arriving event will be copied to

sim_wait_for

public void sim_wait_for(Sim_predicate p,
                         Sim_event ev)
Wait for an event matching a specific predicate. This method doesn't check the entity's deferred queue.

Since 2.0 Sim_syztem checks the predicate for the entity. This avoids unnecessary context switches for non-matching events.

Parameters:
p - The predicate to match
ev - The event to which the arriving event will be copied to

sim_wait_for

public double sim_wait_for(double delay,
                           Sim_event ev)
Wait for an event to arrive or until a time period elapsed. This method doesn't check the entity's deferred queue.
Parameters:
delay - The maximum time to wait
ev - The event to which the arrving event will be copied to
Returns:
The time remaining when the arrival occured

sim_wait_for

public double sim_wait_for(Sim_predicate p,
                           double delay,
                           Sim_event ev)
Wait for an event matching a specific predicate to arrive or until a time period elapses. This method doesn't check the entity's deferred queue.
Parameters:
p - The predicate to match
delay - The maximum time period for which to wait
ev - The event to which the arriving event will be copied to
Returns:
The time remaining when the arrival occured

sim_hold

public void sim_hold(double delay)
Deprecated. As of SimJava version 2.0, replaced by sim_pause(double delay). This method was deprecated because of the new statistical support present to entities. When an entity holds it must now be specified if the hold corrssponds to the entity being active or inactive. The original sim_hold() methods are equivalent to their respective sim_pause() methods.

Hold for a time period
Parameters:
delay - The time period for which to hold

sim_hold_for

public double sim_hold_for(double delay,
                           Sim_event ev)
Deprecated. As of SimJava version 2.0, replaced by sim_pause_for(double delay, Sim_event ev). This method was deprecated because of the new statistical support present to entities. When an entity holds it must now be specified if the hold corrssponds to the entity being active or inactive. The original sim_hold() methods are equivalent to their respective sim_pause() methods.

Hold for a time period or until an event arrives. This method doesn't check the entity's deferred queue.
Parameters:
delay - The maximum time period for which to hold
ev - The event to which the arriving event will be copied to
Returns:
The time remaining when the arrival occured

SimJava
v2.0

The University of Edinburgh, 2002