cz.zcu.fav.kiv.jsim
Class JSimSimulation

java.lang.Object
  cz.zcu.fav.kiv.jsim.JSimSimulation

Direct Known Subclasses:

JSimHLASimulation, UnsecureSimulation

public class JSimSimulation

extends java.lang.Object

The JSimSimulation class instances represent theoretical simulation models, containing processes, queues, and other elements. Every process and queue must have a simulation specified as a constructor parameter, otherwise the creation will not be successful. To the user, the JSimSimulation class provides the step() method -- execution of one simulation step. Alternatively, the runGUI() method can be used, causing the simulation to run in graphic mode.

Since:

J-Sim version 0.1.0

Version:

J-Sim version 0.3.0

Author:

Jarda KAČER, Pavel DOMECKÝ

Field Summary

protected JSimCalendar	calendar The simulation's calendar of events.
protected JSimHLAConnection	jSimHLAConnection The simulation's connection to the HLA Runtime Infrastructure (RTI).
static int	MODE_GUI_BATCH
static int	MODE_GUI_INTERACTIVE
static int	MODE_TXT
static long	NEW_PROCESS_FORBIDDEN
static long	NEW_QUEUE_FORBIDDEN
static long	NEW_SEMAPHORE_FORBIDDEN
static int	PRN_ERROR
static int	PRN_MESSAGE
static int	SIMULATION_IN_PROGRESS
static int	SIMULATION_NOT_STARTED
static int	SIMULATION_TERMINATED
static int	SIMULATION_WAITING_HLA
protected boolean	simulationHLA Flag saying that HLA is used.
protected double	time The simulation's current time.

Constructor Summary

JSimSimulation(java.lang.String name)
Creates a new simulation with no processes, no queues and no graphic window.

JSimSimulation(java.lang.String name, int mode)
Creates a new simulation with no processes, no queues and no graphic window.

JSimSimulation(java.lang.String name, int mode, double guiUpdateDelta)
Creates a new simulation with no processes, no queues and no graphic window.

Method Summary

protected void	addEntryToCalendar(double absoluteTime, JSimProcess process) Adds a new event to the calendar, with the specified absolute time and the specified process.
protected void	addProcess(JSimProcess process) Adds a new process to the simulation.
protected void	addQueue(JSimHead queue) Adds a new queue to the simulation.
void	addSemaphore(JSimSemaphore semaphore) Adds a new semaphore to the simulation.
protected int	deleteEntriesInCalendar(JSimProcess process, boolean all) Deletes one or more entries in the calendar, concerning a process.
protected void	deleteProcess(JSimProcess process) Deletes a process from the simulation.
void	error(java.lang.String s) Prints out a text error message, either to the error output or to the simulation window.
double	getCurrentTime() Returns the simulation's current time.
long	getFreeProcessNumber() Returns a unique number that can be assigned to a newly created process.
long	getFreeQueueNumber() Returns a unique number that can be assigned to a newly created queue.
long	getFreeSemaphoreNumber() Returns a unique number that can be assigned to a newly created semaphore.
java.lang.Object	getGraphicLock() Returns the lock object used for synchronization between the simulation and its GUI window.
JSimChange	getChange() Returns an observable object notifying the GUI about possible changes.
java.lang.String	getName() Returns the simulation's name.
int	getNumber() Returns the simulation's unique number.
long	getNumberOfProcesses() Returns the number of processes present within the simulation.
long	getNumberOfQueues() Returns the number of queues present within the simulation.
long	getNumberOfSemaphores() Returns the number of semaphores present within the simulation.
java.util.SortedSet	getObjectsToBeDisplayed(int elementType) Returns a set containing information about simulation elements that are to be displayed in the GUI.
protected java.util.SortedSet	getProcesses() Returns simulation's processes.
protected java.util.SortedSet	getQueues() Returns simulation's queues.
JSimProcess	getRunningProcess() Returns the currently running process.
int	getSimulationMode() Returns the simulation's mode.
int	getSimulationState() Returns the simulation's state.
java.lang.Object	getStepLock() Returns the lock object that protects the step() method from being invoked in parallel.
boolean	getTalking() Returns true if talking is on, otherwise returns false.
java.io.PrintStream	getTalkStream() Returns the talk stream where talking is directed to.
boolean	getWaitingForWindowClosure() Returns true if the simulation is waiting in waitForWindowClosure().
java.lang.Object	getWindowClosureLock() Returns the lock object used for synchronization between the simulation and its GUI window, while waiting in waitForWindowClosure().
java.io.PrintStream	changeTalkStream(java.io.PrintStream newStream) Changes the talk stream where talking is directed to.
boolean	isRunningGUI() Returns true if the simulation is running in a GUI window.
void	message(java.lang.String s) Prints out a text message, either to the standard output or to the simulation window.
void	messageNoNL(java.lang.String s) Prints out a text message, either to the standard output or to the simulation window, but does not terminate the line.
void	printString(java.lang.String s, int code, boolean newLine) Prints a standard message or an error message.
boolean	runGUI() Opens a graphic window and lets the user control the simulation's execution using this window.
protected void	setSimulationState(int newState) Changes simulation's state.
void	setTalking(boolean yesOrNo) Switches talking on/off.
void	shutdown() Shutdowns the simulation by interrupting all living processes.
boolean	step() Executes one simulation step.
protected void	switchToNobody() Switches the execution to the main thread.
void	talk(boolean x) Prints a boolean value to the stream used for talking, if talking is set on.
void	talk(double x) Prints a double value to the stream used for talking, if talking is set on.
void	talk(float x) Prints a float value to the stream used for talking, if talking is set on.
void	talk(char x) Prints a char value to the stream used for talking, if talking is set on.
void	talk(char[] x) Prints an array of chars to the stream used for talking, if talking is set on.
void	talk(int x) Prints an int value to the stream used for talking, if talking is set on.
void	talk(long x) Prints a long value to the stream used for talking, if talking is set on.
void	talk(java.lang.Object x) Prints an object to the stream used for talking, if talking is set on.
void	talk(java.lang.String x) Prints a string to the stream used for talking, if talking is set on.
void	waitForWindowClosure() Suspends the calling thread until the `Quit' button of the main window is pressed.
void	windowIsClosing(JSimMainWindow caller) The simulation is informed about the main window's closure.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MODE_TXT

public static final int MODE_TXT

See Also:

Constant Field Values

MODE_GUI_BATCH

public static final int MODE_GUI_BATCH

See Also:

Constant Field Values

MODE_GUI_INTERACTIVE

public static final int MODE_GUI_INTERACTIVE

See Also:

Constant Field Values

SIMULATION_NOT_STARTED

public static final int SIMULATION_NOT_STARTED

See Also:

Constant Field Values

SIMULATION_IN_PROGRESS

public static final int SIMULATION_IN_PROGRESS

See Also:

Constant Field Values

SIMULATION_TERMINATED

public static final int SIMULATION_TERMINATED

See Also:

Constant Field Values

SIMULATION_WAITING_HLA

public static final int SIMULATION_WAITING_HLA

See Also:

Constant Field Values

PRN_MESSAGE

public static final int PRN_MESSAGE

See Also:

Constant Field Values

PRN_ERROR

public static final int PRN_ERROR

See Also:

Constant Field Values

NEW_PROCESS_FORBIDDEN

public static final long NEW_PROCESS_FORBIDDEN

See Also:

Constant Field Values

NEW_QUEUE_FORBIDDEN

public static final long NEW_QUEUE_FORBIDDEN

See Also:

Constant Field Values

NEW_SEMAPHORE_FORBIDDEN

public static final long NEW_SEMAPHORE_FORBIDDEN

See Also:

Constant Field Values

calendar

protected JSimCalendar calendar

The simulation's calendar of events. Since J-Sim 0.3.0, this field is protected, not private. This allows all subclasses and J-Sim classes to directly manipulate with the calendar, which is required e.g. in UnsecureSimulation. If you subclass JSimSimulation, be very careful about the calendar. You had better not touch it at all!

time

protected double time

The simulation's current time. Since J-Sim 0.3.0, this field is protected, not private. This allows all subclasses and J-Sim classes to directly manipulate with the simulation time, which is required e.g. in UnsecureSimulation. If you subclass JSimSimulation, be very careful about the simulation time. You had better not touch it at all!

simulationHLA

protected boolean simulationHLA

Flag saying that HLA is used. This flag should never get true if instance of JSimSimulation is created. It is set to true only if instance of JSimHLASimulation is created. It can not be declared in JSimHLASimulation, because step() method needs to use it.

jSimHLAConnection

protected JSimHLAConnection jSimHLAConnection

The simulation's connection to the HLA Runtime Infrastructure (RTI). It should never be used if instance of JSimSimulation is created. It is used only if instance of JSimHLASimulation is created. It is protected, because it is used in JSimHLASimulation. It can not be declared in JSimHLASimulation, because step() method needs to use it.

Constructor Detail

JSimSimulation

public JSimSimulation(java.lang.String name)
               throws JSimInvalidParametersException

Creates a new simulation with no processes, no queues and no graphic window. The simulation will run in text (console) mode and no graphic output will be allowed.

Parameters:

name - Name of the simulation.

Throws:

JSimInvalidParametersException - This exception is thrown out if the specified name is is null.

JSimSimulation

public JSimSimulation(java.lang.String name,
                      int mode)
               throws JSimInvalidParametersException

Creates a new simulation with no processes, no queues and no graphic window. According to the simulation mode specified as a parameter, it will / will not be allowed to use graphic output later. If GUI batch or interactive mode is used, the output will be updated after every step.

Parameters:

name - Name of the simulation.

mode - Simulation mode. Possible values are MODE_TXT, MODE_GUI_BATCH, and MODE_GUI_INTERACTIVE.

Throws:

JSimInvalidParametersException - This exception is thrown out if the specified name is is null or an invalid simulation mode is given to the constructor.

JSimSimulation

public JSimSimulation(java.lang.String name,
                      int mode,
                      double guiUpdateDelta)
               throws JSimInvalidParametersException

Creates a new simulation with no processes, no queues and no graphic window. According to the simulation mode specified as a parameter, it will / will not be allowed to use graphic output later.

Parameters:

name - Name of the simulation.

mode - Simulation mode. Possible values are MODE_TXT, MODE_GUI_BATCH, and MODE_GUI_INTERACTIVE.

Throws:

JSimInvalidParametersException - This exception is thrown out if the specified name is is null, an invalid simulation mode is given to the constructor, or if the update interval is less than zero.

Method Detail

addProcess

protected final void addProcess(JSimProcess process)
                         throws JSimInvalidParametersException

Adds a new process to the simulation. You should never call this method. It is called automatically from JSimProcess constructor.

Parameters:

process - The process that has to be added to the simulation.

Throws:

JSimInvalidParametersException - This exception is thrown out if the specified process is null.

addQueue

protected final void addQueue(JSimHead queue)
                       throws JSimInvalidParametersException

Adds a new queue to the simulation. You should never call this method. It is called automatically from JSimHead constructor.

Parameters:

queue - The queue that has to be added to the simulation.

Throws:

JSimInvalidParametersException - This exception is thrown out if the specified queue is null.

addSemaphore

public final void addSemaphore(JSimSemaphore semaphore)
                        throws JSimInvalidParametersException

Adds a new semaphore to the simulation. You should never call this method. It is called automatically from JSimSemaphore constructor.

Parameters:

semaphore - The semaphore that has to be added to the simulation.

Throws:

JSimInvalidParametersException - This exception is thrown out if the specified semaphore is null.

deleteProcess

protected final void deleteProcess(JSimProcess process)

Deletes a process from the simulation. You should never call this method. This method is called by a process which is volunteering to die. Other processes, killed during shutdown, do not call this method. We do not care about notStartedProcesses because the process is volunteering to die and therefore has been started already. There is no need to kill the deleted process by interrupt(). It is at the end of its life in finish() and will die as soon as it gets out from this method.

Parameters:

process - The process to be deleted from the simulation.

step

public final boolean step()
                   throws JSimMethodNotSupportedException

Executes one simulation step. A step is a unit of activity that is terminated by a process' call to the passivate() or hold() method or by a process' death. If there is no process within the simulation or no processes are scheduled or the quit button in GUI batch mode is pressed, simulation will terminate and false will be returned. In all other cases, true will be returned. The method is synchronized with a special lock (stepLock) instead of the implicit one. The reason for not using the implicit lock is that the simulation would block before entering the synchronized(processLock) section because a process would have this lock (processLock) acquired while demanding to call a method synchronized with the implicit lock (e.g. getRunningProcess() in getReady()) and the implicit lock would never be released in step(), even not after passivation of the main thread.

Returns:

False if the step could not be executed because there were no events in the calendar or there were no processes in the simulation or the quit button in the GUI was pressed, true otherwise (the step was successufully completed).

Throws:

JSimKernelPanicException - This exception is thrown out when the state of the simulation cannot be determined or when an inconsistency of J-Sim internal structures (such as the calendar) is revealed.

JSimMethodNotSupportedException - This exception is thrown out when the simulation is running in GUI interactive mode and step() is called from elsewhere than GUI.

shutdown

public void shutdown()

Shutdowns the simulation by interrupting all living processes. If GUI has been used, it exits the current instance of JVM, too. You must always call this function, preferably in the finally block at the end of your main program.

getNumber

public int getNumber()

Returns the simulation's unique number.

Returns:

The Simulation's unique number.

getName

public java.lang.String getName()

Returns the simulation's name.

Returns:

The simulation's name.

getNumberOfProcesses

public final long getNumberOfProcesses()

Returns the number of processes present within the simulation.

Returns:

Number of processes present within the simulation.

getNumberOfQueues

public final long getNumberOfQueues()

Returns the number of queues present within the simulation.

Returns:

Number of queues present within the simulation.

getNumberOfSemaphores

public final long getNumberOfSemaphores()

Returns the number of semaphores present within the simulation.

Returns:

Number of semaphores present within the simulation.

getRunningProcess

public final JSimProcess getRunningProcess()

Returns the currently running process. If no process is running JSimCalendar.NOBODY (=null) will be returned.

Returns:

The currently running process or JSimCalendar.NOBODY.

getFreeProcessNumber

public final long getFreeProcessNumber()

Returns a unique number that can be assigned to a newly created process. You should never call this method.

Returns:

A unique number that can be assigned to a newly created process.

getFreeQueueNumber

public final long getFreeQueueNumber()

Returns a unique number that can be assigned to a newly created queue. You should never call this method.

Returns:

A unique number that can be assigned to a newly created queue.

getFreeSemaphoreNumber

public final long getFreeSemaphoreNumber()

Returns a unique number that can be assigned to a newly created semaphore. You should never call this method.

Returns:

A unique number that can be assigned to a newly created semaphore.

switchToNobody

protected final void switchToNobody()

Switches the execution to the main thread. You should never call this method. This method is called by a process from its hold(), passivate(), or reactivate(). Calling this method does not guarantee the physical thread switch itself, it just sets up the running thread variable.

getCurrentTime

public final double getCurrentTime()

Returns the simulation's current time.

Returns:

The simulation's current time.

getSimulationState

public final int getSimulationState()

Returns the simulation's state.

Returns:

The simulation's state.

getSimulationMode

public final int getSimulationMode()

Returns the simulation's mode.

Returns:

The simulation's mode.

getGraphicLock

public final java.lang.Object getGraphicLock()

Returns the lock object used for synchronization between the simulation and its GUI window. You should never call this method.

Returns:

The lock object used for sychronization between the simulation and its GUI window.

getStepLock

public final java.lang.Object getStepLock()

Returns the lock object that protects the step() method from being invoked in parallel. It is also used for synchronization between the simulation and its GUI window, while being paused. You should never call this method.

Returns:

The lock object that protects the step() method.

getWindowClosureLock

public final java.lang.Object getWindowClosureLock()

Returns the lock object used for synchronization between the simulation and its GUI window, while waiting in waitForWindowClosure(). You should never call this method.

Returns:

The lock object used for synchronization between the simulation and its GUI window.

getChange

public final JSimChange getChange()

Returns an observable object notifying the GUI about possible changes. You should never call this method.

Returns:

An observable object notifying the GUI about possible changes.

getObjectsToBeDisplayed

public java.util.SortedSet getObjectsToBeDisplayed(int elementType)
                                            throws JSimInvalidParametersException

Returns a set containing information about simulation elements that are to be displayed in the GUI. You should never call this method.

Parameters:

elementType - Specifies the type of elements whose information should be returned. Available constants are JSimMainWindow.LIST_TYPE_*.

Returns:

A set containing information about simulation elements.

Throws:

JSimInvalidParametersException - This exception is thrown out if the elementType parameter does not specify a valid type of simulation elements.

addEntryToCalendar

protected void addEntryToCalendar(double absoluteTime,
                                  JSimProcess process)
                           throws JSimInvalidParametersException

Adds a new event to the calendar, with the specified absolute time and the specified process. You should never call this method. Processes themeselves use this method when they have to be scheduled.

Parameters:

absoluteTime - Absolute simulation time of the event being added to the calendar.

process - Process that will be activated at the specified time.

Throws:

JSimInvalidParametersException - This exception is thrown out if the time or the process specified are invalid and were rejected by the calendar.

deleteEntriesInCalendar

protected int deleteEntriesInCalendar(JSimProcess process,
                                      boolean all)
                               throws JSimInvalidParametersException

Deletes one or more entries in the calendar, concerning a process. You should never call this method.

Parameters:

process - Process whose events are to be deleted.

all - Flag saying whether just one (false) or all (true) events of the process should be deleted.

Returns:

Number of events deleted.

Throws:

JSimInvalidParametersException - This exception is thrown out when the process specified is invalid and was rejected by the calendar.

setTalking

public void setTalking(boolean yesOrNo)

Switches talking on/off. When talking is on, the simulation informs the user about all its activities by printing messages to a print stream.

Parameters:

yesOrNo - Flag saying whether to switch talking on or off.

getTalking

public boolean getTalking()

Returns true if talking is on, otherwise returns false.

Returns:

True if talking is on, false otherwise.

getTalkStream

public java.io.PrintStream getTalkStream()

Returns the talk stream where talking is directed to.

Returns:

The talk stream where talking is directed to.

changeTalkStream

public java.io.PrintStream changeTalkStream(java.io.PrintStream newStream)

Changes the talk stream where talking is directed to.

Parameters:

newStream - A new stream that should be used for talking.

Returns:

The old stream that has been used so far.

talk

public void talk(boolean x)

Prints a boolean value to the stream used for talking, if talking is set on.

Parameters:

x - The value to be printed out.

talk

public void talk(char x)

Prints a char value to the stream used for talking, if talking is set on.

Parameters:

x - The value to be printed out.

talk

public void talk(char[] x)

Prints an array of chars to the stream used for talking, if talking is set on.

Parameters:

x - The value to be printed out.

talk

public void talk(double x)

Prints a double value to the stream used for talking, if talking is set on.

Parameters:

x - The value to be printed out.

talk

public void talk(float x)

Prints a float value to the stream used for talking, if talking is set on.

Parameters:

x - The value to be printed out.

talk

public void talk(int x)

Prints an int value to the stream used for talking, if talking is set on.

Parameters:

x - The value to be printed out.

talk

public void talk(long x)

Prints a long value to the stream used for talking, if talking is set on.

Parameters:

x - The value to be printed out.

talk

public void talk(java.lang.Object x)

Prints an object to the stream used for talking, if talking is set on.

Parameters:

x - The object to be printed out.

talk

public void talk(java.lang.String x)

Prints a string to the stream used for talking, if talking is set on.

Parameters:

x - The string to be printed out.

printString

public void printString(java.lang.String s,
                        int code,
                        boolean newLine)

Prints a standard message or an error message. If not running in a GUI window, standard messages are printed to the standard output and error messages to the error output. When running in a GUI window, all messages are printed to the user text area at the bottom of the window. You should never use this method since there are methods message() and error() in the JSimProcess class.

Parameters:

s - The text message to be printed out.

code - Code saying whether it is an info message (PRN_MESSAGE) or an error (PRN_ERROR).

newLine - Flag indicating that the new line character should be appended to the text.

isRunningGUI

public final boolean isRunningGUI()

Returns true if the simulation is running in a GUI window.

Returns:

True if the simulation is running in a GUI window, false otherwise.

runGUI

public final boolean runGUI()
                     throws JSimMethodNotSupportedException

Opens a graphic window and lets the user control the simulation's execution using this window. Does not exit until the user presses the `Quit' button. This method can be used in GUI interactive mode only.

Returns:

True if GUI creation was succesful, false otherwise.

Throws:

JSimMethodNotSupportedException - This exception is thrown out if the simulation is not running in GUI interactive mode.

windowIsClosing

public final void windowIsClosing(JSimMainWindow caller)

The simulation is informed about the main window's closure. You should never use this method. Only the main window can call this method although it is public. Used in GUI interactive mode.

Parameters:

caller - The main window informing about its closure.

waitForWindowClosure

public void waitForWindowClosure()
                          throws JSimMethodNotSupportedException

Suspends the calling thread until the `Quit' button of the main window is pressed. Use this method in GUI batch mode to keep the main window open after the simulation is done (when step() is no longer called) to let the user see the results. The simulation need not necessarily be in terminated state.

Throws:

JSimMethodNotSupportedException - This exception is thrown out if the simulation is not running in GUI batch mode.

getWaitingForWindowClosure

public boolean getWaitingForWindowClosure()

Returns true if the simulation is waiting in waitForWindowClosure().

Returns:

True if the simulation is waiting in waitForWindowClosure(), false otherwise.

message

public void message(java.lang.String s)

Prints out a text message, either to the standard output or to the simulation window.

Parameters:

s - The message to be printed out.

messageNoNL

public void messageNoNL(java.lang.String s)

Prints out a text message, either to the standard output or to the simulation window, but does not terminate the line.

Parameters:

s - The message to be printed out.

error

public void error(java.lang.String s)

Prints out a text error message, either to the error output or to the simulation window.

Parameters:

s - The error message to be printed out.

getProcesses

protected java.util.SortedSet getProcesses()

Returns simulation's processes. It is used by JSimHLASimulation. You should never call this method.

Returns:

Simulation's processes.

getQueues

protected java.util.SortedSet getQueues()

Returns simulation's queues. It is used by JSimHLASimulation. You should never call this method.

Returns:

Simulation's processes.

setSimulationState

protected void setSimulationState(int newState)

Changes simulation's state. It is used by JSimHLASimulation. You should never call this method.

Parameters:

newState - New state of simulation.