scorej
Class S

java.lang.Object
  |
  +--scorej.S

public final class S

extends java.lang.Object

The primary class for ScoreJ. S contains all primary methods for defining the behaviors of agents and objects. It also includes the methods which control the environment in which the agents and objects are instantiated within.

Field Summary

static float

version ScoreJ version

Method Summary

static void	addScenario(java.lang.Class newScenario) Adds a scenario to a table of known scenarios.
static void	addScenario(java.lang.String name, java.lang.Class newScenario) Adds a scenario to a table of known scenarios and associates it with the specified name.
static OmarClock	createClock() A utility method that creates and returns an instance of the default clock class.
static OmarClock	createClock(java.lang.Class clockClass) A utility method that creates and returns an instance of the specified clock class.
static SignalWaitQueue	createSignalQueue(ID receiver, ID sender, java.lang.String[] subject, java.lang.Object[] pattern, SignalEvaluator func) Creates a signal queue for signals matching the specified receiver, sender subject, pattern and signalEvaluator function.
static SignalWaitQueue	createSignalQueue(java.lang.Object[] pattern) Create a signal wait Queue for a specific pattern
static SignalWaitQueue	createSignalQueue(SignalEvaluator func) Creates a queue of signals for which the SignalEvaluator function evaluates to true.
static SignalWaitQueue	createSignalQueue(java.lang.String[] subject) Create a signal wait Queue for a specific signal type
static SignalWaitQueue	createSignalQueue(java.lang.String[] subject, SignalEvaluator func) Creates a signal queue for signals matching the specified subject and SignalEvaluator function.
static void	failSelf() Throws a ScoreException, causing method to fail.
static void	failSelf(java.lang.String msg) Throws a ScoreException, causing method to fail.
static void	fork(Invocation invoke1) Spawns a new thread and executes the invocation method in that thread.
static OmarClock	getClock() Getter for the clock object registered at this node.
static Scenario	getCurrentScenario() Gets the current scenario.
static java.lang.String	getCurrentScenarioName() Gets the name of the current scenario.
static java.lang.Class	getDefaultClockClass() Gets the default clock class.
static ScoreID	getID() Returns the globally unique ID associated with this node.
static java.lang.String	getName() Returns the simulator's name.
static void	getResource(Resource[] resources, ScoreJThread owner, int priority) Grabs a set of resources.
static void	getResource(Resource resource, ScoreJThread owner, int priority) Grabs a resource.
static java.util.Vector	getScenarioNames() Gets the names of known scenarios.
static java.util.Vector	getScenarios() Gets the Classes of all known scenarios.
static void	initializeCommProtocol(java.lang.Class protocol, java.util.Properties props) Initializes a specific commumication protocol.
static boolean	isResourceAvailable(Resource resource, int priority) Checks whether a resource is available.
static Future	join(Invocation[] invocations) Join executes its method invocations in parallel in separate threads.
static Future	join(Invocation invoke1, Invocation invoke2) Join executes its method invocations in parallel in separate threads.
static Future	join(Invocation invoke1, Invocation invoke2, Invocation invoke3) Join executes its method invocations in parallel in separate threads.
static Future	join(Invocation invoke1, Invocation invoke2, Invocation invoke3, Invocation invoke4) Join executes its method invocations in parallel in separate threads.
static void	nameAndStartThread(java.lang.Thread t, java.lang.String name)
static void	pauseCurrentScenario() Pause running the current scenario.
static Future	race(Invocation[] invocations) Race, like satisfy(Invocation[] invocations) expresses alternative steps, only one of which needs to complete.
static Future	race(Invocation invoke1, Invocation invoke2) Race, like satisfy(Invocation invoke1, Invocation invoke2) expresses alternative steps, only one of which needs to complete successfully or fail for the race to finish.
static Future	race(Invocation invoke1, Invocation invoke2, Invocation invoke3) Race, like satisfy(Invocation invoke1, Invocation invoke2, Invocation invoke3) expresses alternative steps, only one of which needs to complete successfully or fail for the race to finish.
static Future	race(Invocation invoke1, Invocation invoke2, Invocation invoke3, Invocation invoke4) Race, like satisfy(Invocation invoke1, Invocation invoke2, Invocation invoke3, Invocation invoke4) expresses alternative steps, only one of which needs to complete successfully or fail for the race to finish.
static void	releaseResource(Resource[] resources, ScoreJThread owner) Releases a set of previously acquired resources.
static void	releaseResource(Resource resource, ScoreJThread owner) Releases a previously acquired resource.
static void	resume(java.lang.Thread t) Resumes a previosuly suspended thread.
static void	resumeCurrentScenario() Resume running the current scenario, which must have been paused.
static void	runClock(boolean isDaemonThread) Starts the clock in a separate thread.
static Future	satisfy(Invocation[] invocations) Satisfy, like race(Invocation[] invocations) expresses alternative steps, only one of which needs to complete.
static Future	satisfy(Invocation invoke1, Invocation invoke2) Satisfy, like race(Invocation invoke1, Invocation invoke2) expresses alternative steps, only one of which needs to complete successfully for the satisfy to finish.
static Future	satisfy(Invocation invoke1, Invocation invoke2, Invocation invoke3) Satisfy, like race(Invocation invoke1, Invocation invoke2, Invocation invoke3) expresses alternative steps, only one of which needs to complete successfully for the satisfy to finish.
static Future	satisfy(Invocation invoke1, Invocation invoke2, Invocation invoke3, Invocation invoke4) Satisfy, like race(Invocation invoke1, Invocation invoke2, Invocation invoke3, Invocation invoke4) expresses alternative steps, only one of which needs to complete.
static void	sendSignalGlobal(ID sender, java.lang.String[] subject, java.lang.Object[] signalArgs) Sends a signal with spcified sender, subject and signal arguments to all nodes eligible to receive it.
static void	sendSignalGlobal(java.lang.Object[] signalArgs) Sends a signal with specified signal arguments to all nodes eligible to receive it.
static void	sendSignalGlobal(Signal signal) Sends a signal to all nodes eligible to receive it.
static void	sendSignalGlobal(java.lang.String[] subject, java.lang.Object[] signalArgs) Sends a signal with subject and signal arguments to all nodes eligible to receive it.
static void	sendSignalGlobal(java.lang.String[] subject, java.lang.String signalArg) Sends a signal with specified sender, subject and signal name to all nodes eligible to receive it.
static void	sendSignalLocal(ID[] receivers, ID sender, java.lang.String[] subject, java.lang.Object[] signalArgs) Sends a signal within the local node.
static void	sendSignalLocal(ID receiver, ID sender, java.lang.String[] subject, java.lang.Object[] signalArgs) Sends a signal within the local node.
static void	sendSignalLocal(ID receiver, java.lang.Object[] signalArgs) Sends a signal with a null sender and null subject within the local node.
static void	sendSignalLocal(ID receiver, java.lang.String[] subject, java.lang.Object[] signalArgs) Sends a signal with a null sender within the local node.
static void	sendSignalLocal(java.lang.Object[] signalArgs) Sends a signal with a null sender, null subject and null receivers within the local node.
static void	sendSignalLocal(Signal signal) Sends a signal within the local node.
static void	sendSignalLocal(java.lang.String signalArg) Sends a signal with a null sender and null subject within the local node.
static void	sendSignalTo(ID[] receivers, ID sender, java.lang.String[] subject, java.lang.Object[] signalArgs) Sends a signal with the specified receivers, sender, subject and signal arguments to all nodes eligible to receive it.
static void	sendSignalTo(ID receiver, ID sender, java.lang.String[] subject, java.lang.Object[] signalArgs) Sends a signal with the specified receiver, sender, subject and signal arguments to all nodes eligible to receive it.
static void	sendSignalTo(ID receiver, java.lang.Object[] signalArgs) Sends a signal with the specified receiver and signal arguments to all nodes eligible to receive it.
static void	sendSignalTo(ID receiver, java.lang.String[] subject, java.lang.Object[] signalArgs) Sends a signal with the specified receiver, subject and signal arguments to all nodes eligible to receive it.
static void	sendSignalTo(Signal signal) Sends a signal with the receivers, sender, subject and signal arguments specified in the signal object to all nodes eligible to receive it.
static void	setClock(OmarClock newClock) Setter for the clock object at this node.
static void	setCurrentScenario(Scenario scen) Sets the current scenario.
static void	setCurrentScenario(java.lang.String scenName) Sets the current scenario.
static void	setDefaultClockClass(java.lang.Class c) Set the default clock class that will get created if you call Scenario.initialize with no clock parameter.
static void	setName(java.lang.String simulatorName) Each node gets a default non-null simulator name on startup.
static void	shutdownCommProtocol(java.lang.Class protocol) Call this method to close the communication mechanism that this node will use to communicate with other nodes and applications.
static void	sleep(double time) Suspends execution of the method until the specified amount of time has passed.
static void	sleepUntil(double time) Suspends execution of the method until a future time has been reached.
static Future	spawn(Invocation invoke1) Spawns a new thread and executes the invocation method in that thread.
static void	startCommProtocol(java.lang.Class protocol) Starts the communication mechanism that this node will use to communicate with other nodes and applications.
static void	startCurrentScenario() Initialize and start the current Scenario using the default clock.
static void	startCurrentScenario(OmarClock clock, boolean isClockDaemonThread) Initialize and start the current Scenario using the specified clock.
static void	stopCurrentScenario() Stop running the current scenario.
static boolean	suspend(java.lang.Thread t) Suspends a thread.
static void	transferOwnershipAndStart(ScoreJThread currentOwner, Resource[] resources, ScoreJThread newOwner) Atomically transfer the ownership of the set of resources to the specified thread and start the thread.
static void	transferOwnershipAndStart(ScoreJThread currentOwner, Resource resource, ScoreJThread newOwner) Atomically transfer the ownership of the resource to the specified thread and start the thread.
static Signal	waitForQueuedSignal(SignalWaitQueue queue) Wait for a signal that has a associated queue.
static Signal	waitForSignal(ID receiver, ID sender, java.lang.String[] subject, java.lang.Object[] pattern, SignalEvaluator func)
static Signal	waitForSignal(java.lang.Object[] pattern) Waits for a signal matching the specified pattern.
static Signal	waitForSignal(SignalEvaluator func) Waits for a signal on which the SignalEvaluator function evaluates to true.
static Signal	waitForSignal(java.lang.String signalArg) Waits for a signal with a given signal name.
static Signal	waitForSignal(java.lang.String[] subject) Waits for a signal with a given signal name.
static Signal	waitForSignal(java.lang.String[] subject, SignalEvaluator func) Waits for a signal matching the signal name and where the SignalEvaluator function evaluates to true.
static Signal	waitForSignal(java.lang.String signalArg, SignalEvaluator func) Waits for a signal matching the signal name and where the SignalEvaluator function evaluates to true.
static boolean	wasSuspended(double startTime, java.lang.Thread t) Checks whether the thread was suspended after a given time.

Methods inherited from class java.lang.Object

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

Field Detail

version

public static final float version

ScoreJ version

See Also:

Constant Field Values

Method Detail

setDefaultClockClass

public static void setDefaultClockClass(java.lang.Class c)
                                 throws java.lang.ClassNotFoundException

Set the default clock class that will get created if you call Scenario.initialize with no clock parameter.

java.lang.ClassNotFoundException

getDefaultClockClass

public static java.lang.Class getDefaultClockClass()

Gets the default clock class.

Returns:

the default clock class.

createClock

public static final OmarClock createClock()
                                   throws java.lang.NoSuchMethodException,
                                          java.lang.InstantiationException,
                                          java.lang.IllegalAccessException,
                                          java.lang.reflect.InvocationTargetException

A utility method that creates and returns an instance of the default clock class. It invokes the default constructor of the default clock class to create an instance of the clock class. This method leaves the default clock class unchanged. Use {S#setDefaultClockClass} to achive that effect. This method also does not change the clock object currently registered at this node. Use setClock(scorej.OmarClock) to achieve that effect.

java.lang.NoSuchMethodException

java.lang.InstantiationException

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

createClock

public static final OmarClock createClock(java.lang.Class clockClass)
                                   throws java.lang.NoSuchMethodException,
                                          java.lang.InstantiationException,
                                          java.lang.IllegalAccessException,
                                          java.lang.reflect.InvocationTargetException

A utility method that creates and returns an instance of the specified clock class. It invokes the default constructor of the specified clock class to create an instance of the clock class. This method leaves the default clock class unchanged. This method also does not change the clock object currently registered at this node. Use setClock(scorej.OmarClock) to achieve that effect.

java.lang.NoSuchMethodException

java.lang.InstantiationException

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

runClock

public static final void runClock(boolean isDaemonThread)

Starts the clock in a separate thread. If the clock has already started, dont restart it, just put it back in a running state.

Parameters:

isDaemonThread - when true, clock thread is set to be a daemon thread. This has the effect of ending the clock thread when all non-daemon threads, (such as the scenario thread) have ended. When this parameter is set to false, the clok will continue running even when the scenario has come to an end.

getClock

public static final OmarClock getClock()

Getter for the clock object registered at this node.

setClock

public static final void setClock(OmarClock newClock)

Setter for the clock object at this node. This method kills an existing clock thread, if running before setting the new clock object. Calling this method simply sets the clock object without starting the clock thread. Call runClock(boolean) to start the clock thread.

initializeCommProtocol

public static void initializeCommProtocol(java.lang.Class protocol,
                                          java.util.Properties props)

Initializes a specific commumication protocol. This is the protocol that this node or application will use to communicate with other nodes and applications.

Parameters:

protocol - a class that implements CommProtocol.

props - A Properties object that contains initialization parameters for the protocol. This argument can be null if the protocol does not require initialization parameters or can initialize with a set of default initialization parameters.

startCommProtocol

public static void startCommProtocol(java.lang.Class protocol)
                              throws java.lang.Exception

Starts the communication mechanism that this node will use to communicate with other nodes and applications. This method will throw an exception if it is called before initializeCommProtocol(java.lang.Class, java.util.Properties) is called.

java.lang.Exception

shutdownCommProtocol

public static void shutdownCommProtocol(java.lang.Class protocol)

Call this method to close the communication mechanism that this node will use to communicate with other nodes and applications. This method will throw an exception if it is called before initializeCommProtocol(java.lang.Class, java.util.Properties) is called.

getID

public static final ScoreID getID()

Returns the globally unique ID associated with this node.

Returns:

The ID object representing this node.

getName

public static final java.lang.String getName()

Returns the simulator's name. The name can be specified using setName(java.lang.String), otherwise one will be generated.

setName

public static final void setName(java.lang.String simulatorName)

Each node gets a default non-null simulator name on startup. This method allows the default name to be changed with a non-null value.

nameAndStartThread

public static void nameAndStartThread(java.lang.Thread t,
                                      java.lang.String name)

sleep

public static void sleep(double time)

Suspends execution of the method until the specified amount of time has passed. In discrete event time the clock is advanced to the next earliest sleep wakeup time after all threads are in a wait/sleep state.

Parameters:

time - - length of time to sleep

sleepUntil

public static void sleepUntil(double time)

Suspends execution of the method until a future time has been reached.

Parameters:

time - - absolute time at which to wake up (relative to time step zero in simulation time).

suspend

public static boolean suspend(java.lang.Thread t)

Suspends a thread. This call blocks until thread t either sleeps or begins waiting on a signal or begins waiting on a future before suspending it.

Parameters:

t - thread to be suspended

Returns:

true if the thread was successfully suspended, false if thread finished executing before it could be suspended or if some other error occurs.

resume

public static void resume(java.lang.Thread t)

Resumes a previosuly suspended thread. If the thread was sleeping at the time of suspension, it is put back to sleep for an amount of time equal to the difference between its scheduled wakeup time and the clock time just before it was suspended.

Parameters:

t - thread to be resumed.

wasSuspended

public static boolean wasSuspended(double startTime,
                                   java.lang.Thread t)

Checks whether the thread was suspended after a given time.

Parameters:

startTime - - time after which to check for a suspension

t - thread object.

Returns:

true if the thread was suspended after startTime, false otherwise.

join

public static Future join(Invocation invoke1,
                          Invocation invoke2)

Join executes its method invocations in parallel in separate threads. Join returns a Future object whose Future.getValue() method returns an object array, but only after all methods complete successfully. If any method fails, Future.getValue() immediately throws an exception.

Parameters:

invoke1 - method Invocation

invoke2 - method Invocation

Returns:

Future object enabling acquisition of the return values of the methods invoked by the join.

join

public static Future join(Invocation invoke1,
                          Invocation invoke2,
                          Invocation invoke3,
                          Invocation invoke4)

Join executes its method invocations in parallel in separate threads. Join returns a Future object whose Future.getValue() method returns an object array, but only after all methods complete successfully. If any method fails, Future.getValue() immediately throws an exception.

Parameters:

invoke1 - method Invocation

invoke2 - method Invocation

invoke3 - method Invocation

invoke4 - method Invocation

Returns:

Future object enabling acquisition of the return values of the methods invoked by the join.

join

public static Future join(Invocation invoke1,
                          Invocation invoke2,
                          Invocation invoke3)

Join executes its method invocations in parallel in separate threads. Join returns a Future object whose Future.getValue() method returns an object array, but only after all methods complete successfully. If any method fails, Future.getValue() immediately throws an exception.

Parameters:

invoke1 - method Invocation

invoke2 - method Invocation

invoke3 - method Invocation

Returns:

Future object enabling acquisition of the return values of the methods invoked by the join.

join

public static Future join(Invocation[] invocations)

Join executes its method invocations in parallel in separate threads. Join returns a Future object whose Future.getValue() method returns an object array, but only after all methods complete successfully. If any method fails, Future.getValue() immediately throws an exception.

Parameters:

invocations - array of method invocations

Returns:

Future object enabling acquisition of the return values of the methods invoked by the join.

race

public static Future race(Invocation invoke1,
                          Invocation invoke2)

Race, like satisfy(Invocation invoke1, Invocation invoke2) expresses alternative steps, only one of which needs to complete successfully or fail for the race to finish. Race executes its method invocations in parallel by starting a separate thread for each method invocation. It returns a Future object whose Future.getValue() method returns the return value of the first method to complete. If any method fails prior to a method completing, Future.getValue() immediately throws an exception. After the first method completes, all other methods are shut down.

Parameters:

invoke1 - method Invocation

invoke2 - method Invocation

Returns:

Future object enabling acquisition of the return value.

race

public static Future race(Invocation invoke1,
                          Invocation invoke2,
                          Invocation invoke3)

Race, like satisfy(Invocation invoke1, Invocation invoke2, Invocation invoke3) expresses alternative steps, only one of which needs to complete successfully or fail for the race to finish. Race executes its method invocations in parallel by starting a separate thread for each method invocation. It returns a Future object whose Future.getValue() method returns the return value of the first method to complete. If any method fails prior to a method completing, Future.getValue() immediately throws an exception. After the first method completes, all other methods are shut down.

Parameters:

invoke1 - method Invocation

invoke2 - method Invocation

invoke3 - method Invocation

Returns:

Future object enabling acquisition of the return value.

race

public static Future race(Invocation invoke1,
                          Invocation invoke2,
                          Invocation invoke3,
                          Invocation invoke4)

Race, like satisfy(Invocation invoke1, Invocation invoke2, Invocation invoke3, Invocation invoke4) expresses alternative steps, only one of which needs to complete successfully or fail for the race to finish. Race executes its method invocations in parallel by starting a separate thread for each method invocation. It returns a Future object whose Future.getValue() method returns the return value of the first method to complete. If any method fails prior to a method completing, Future.getValue() immediately throws an exception. After the first method completes, all other methods are shut down.

Parameters:

invoke1 - method Invocation

invoke2 - method Invocation

invoke3 - method Invocation

invoke4 - method Invocation

Returns:

Future object enabling acquisition of the return value.

race

public static Future race(Invocation[] invocations)

Race, like satisfy(Invocation[] invocations) expresses alternative steps, only one of which needs to complete. Race executes its method invocations in parallel by starting a separate thread for each method invocation. It returns a Future object whose Future.getValue() method returns the return value of the first method to complete. If any method fails prior to a method completing, Future.getValue() immediately throws an exception. After the first method completes, all other methods are shut down.

Parameters:

invocations - array of method invocations

Returns:

Future object enabling acquisition of the return value.

spawn

public static Future spawn(Invocation invoke1)

Spawns a new thread and executes the invocation method in that thread. Returns a Future whose Future.getValue() method will return the result of the invoked method.

Note: the calling thread is recorded with the simulation clock, if the clock doesn't already know about it. This means that simulation time will not advance until the calling thread enters a Scorej wait state (for example, by calling getValue() on the returned Future). In practice, it is best to use fork(scorej.Invocation) instead of spawn if you are not going to retrieve the return value.

Parameters:

invoke1 - method Invocation

Returns:

Future object enabling acquisition of the return value.

fork

public static void fork(Invocation invoke1)

Spawns a new thread and executes the invocation method in that thread.

Parameters:

invoke1 - method Invocation

satisfy

public static Future satisfy(Invocation invoke1,
                             Invocation invoke2)

Satisfy, like race(Invocation invoke1, Invocation invoke2) expresses alternative steps, only one of which needs to complete successfully for the satisfy to finish. Satisfy executes its method invocations in parallel by starting a separate thread for each method invocation. It returns a Future object whose Future.getValue() method returns the return value of the first method to successfully complete. If all methods fail, Future.getValue() throws the exception from the last failed method. After the first method completes, all other methods are shut down.

Parameters:

invoke1 - method Invocation

invoke2 - method Invocation

Returns:

Future object enabling acquisition of the return value.

satisfy

public static Future satisfy(Invocation invoke1,
                             Invocation invoke2,
                             Invocation invoke3)

Satisfy, like race(Invocation invoke1, Invocation invoke2, Invocation invoke3) expresses alternative steps, only one of which needs to complete successfully for the satisfy to finish. Satisfy executes its method invocations in parallel by starting a separate thread for each method invocation. It returns a Future object whose Future.getValue() method returns the return value of the first method to successfully complete. If all methods fail, Future.getValue() throws the exception from the last failed method. After the first method completes, all other methods are shut down.

Parameters:

invoke1 - method Invocation

invoke2 - method Invocation

invoke3 - method Invocation

Returns:

Future object enabling acquisition of the return value.

satisfy

public static Future satisfy(Invocation invoke1,
                             Invocation invoke2,
                             Invocation invoke3,
                             Invocation invoke4)

Satisfy, like race(Invocation invoke1, Invocation invoke2, Invocation invoke3, Invocation invoke4) expresses alternative steps, only one of which needs to complete. Satisfy executes its method invocations in parallel by starting a separate thread for each method invocation. It returns a Future object whose Future.getValue() method returns the return value of the first method to successfully complete. If all methods fail, Future.getValue() throws the exception from the last failed method. After the first method completes, all other methods are shut down.

Parameters:

invoke1 - method Invocation

invoke2 - method Invocation

invoke3 - method Invocation

invoke4 - method Invocation

Returns:

Future object enabling acquisition of the return value.

satisfy

public static Future satisfy(Invocation[] invocations)

Satisfy, like race(Invocation[] invocations) expresses alternative steps, only one of which needs to complete. Satisfy executes its method invocations in parallel by starting a separate thread for each method invocation. It returns a Future object whose Future.getValue() method returns the return value of the first method to successfully complete. If all methods fail, Future.getValue() throws the exception from the last failed method. After the first method completes, all other methods are shut down.

Parameters:

invocations - array of method invocations

Returns:

Future object enabling acquisition of the return value.

sendSignalTo

public static void sendSignalTo(ID receiver,
                                java.lang.Object[] signalArgs)

Sends a signal with the specified receiver and signal arguments to all nodes eligible to receive it. The sender and subject fields of the signal are set to null. A node is eligible to receive a signal sent by this method if it satisfies one of the following tests:

• It contains the specified receiver and it has registered to receive signals meant for itself, coming from any sender and having any subject, OR
• It is registered to receive signals meant for any (or at least the specified) receiver, coming from any sender and having any subject.

  Parameters:

  receiver - The receiver for whom the signal is intended. Should not be null.

  signalArgs - The signal arguments. These should never be null or empty.

sendSignalTo

public static void sendSignalTo(ID receiver,
                                java.lang.String[] subject,
                                java.lang.Object[] signalArgs)

Sends a signal with the specified receiver, subject and signal arguments to all nodes eligible to receive it. The sender field of the signal is set to null. A node is eligible to receive a signal sent by this method if it satisfies one of the following tests:

• It contains the specified receiver and it has registered to receive signals meant for itself, coming from any sender and having any (or at least the specified) subject, OR
• It is registered to receive signals meant for any (or at least the specified) receiver, coming from any sender and having any (or at least the specified) subject.

  Parameters:

  receiver - The receiver for whom the signal is intended. Should not be null.

  subject - A string array specifying the subject of the signal.

  signalArgs - The signal arguments. These should never be null or empty.

sendSignalTo

public static void sendSignalTo(ID receiver,
                                ID sender,
                                java.lang.String[] subject,
                                java.lang.Object[] signalArgs)

Sends a signal with the specified receiver, sender, subject and signal arguments to all nodes eligible to receive it. A node is eligible to receive a signal sent by this method if it satisfies one of the following tests:

• It contains the specified receiver and it has registered to receive signals meant for itself, coming from any (or at least the specified) sender and having any (or at least the specified) subject, OR
• It is registered to receive signals meant for any (or at least the specified) receiver, coming from any (or at least the specified) sender and having any (or at least the specified) subject.

  Parameters:

  receiver - The receiver for whom the signal is intended. Should not be null.

  sender - The sender of the signal. Can be null. If this parameter is null, it matches with only nodes that have registered to receive signals from every possible sender.

  subject - A string array specifying the subject of the signal.

  signalArgs - The signal arguments. These should never be null or empty.

sendSignalTo

public static void sendSignalTo(ID[] receivers,
                                ID sender,
                                java.lang.String[] subject,
                                java.lang.Object[] signalArgs)

Sends a signal with the specified receivers, sender, subject and signal arguments to all nodes eligible to receive it. A node is eligible to receive a signal sent by this method if it satisfies one of the following tests:

• It contains at least one of the specified receivers and it has registered to receive signals meant for itself, coming from any (or at least the specified) sender and having any (or at least the specified) subject, OR
• It is registered to receive signals meant for any (or at least one of the specified) receivers, coming from any (or at least the specified) sender and having any (or at least the specified) subject.

  Note that each node eligible to receive the signal is sent this signal only once.

  Parameters:

  sender - The sender of the signal. Can be null. If this parameter is null, it matches with only nodes that have registered to receive signals from every possible sender.

  subject - A string array specifying the subject of the signal.

  signalArgs - The signal arguments. These should never be null or empty.

sendSignalTo

public static void sendSignalTo(Signal signal)

Sends a signal with the receivers, sender, subject and signal arguments specified in the signal object to all nodes eligible to receive it. A node is eligible to receive a signal sent by this method if it satisfies one of the following tests:

• It contains at least one of the receivers specified in the signal and it has registered to receive signals meant for itself, coming from any sender (or at least the sender specified in the signal) and having any subject (or at least the subject specified in the signal), OR
• It is registered to receive signals meant for any receiver (or at least one of the receivers specified in the signal), coming from any sender (or at least the sender specified in the signal) and having any subject (or at least the subject specified in the signal).

  Note that each node eligible to receive the signal is sent this signal only once.

  Parameters:

  signal - Signal containing an array of receivers, a sender, a subject and of signal arguments

sendSignalLocal

public static void sendSignalLocal(java.lang.String signalArg)

Sends a signal with a null sender and null subject within the local node.

Parameters:

signalArg - The name of the signal. This forms the first and only signal argument.

sendSignalLocal

public static void sendSignalLocal(java.lang.Object[] signalArgs)

Sends a signal with a null sender, null subject and null receivers within the local node.

Parameters:

signalArgs - The signal arguments. These should never be null or empty.

sendSignalLocal

public static void sendSignalLocal(ID receiver,
                                   java.lang.Object[] signalArgs)

Sends a signal with a null sender and null subject within the local node.

Parameters:

receiver - The receiver for whom the signal is intended.

signalArgs - The signal arguments. These should never be null or empty.

sendSignalLocal

public static void sendSignalLocal(ID receiver,
                                   java.lang.String[] subject,
                                   java.lang.Object[] signalArgs)

Sends a signal with a null sender within the local node.

Parameters:

receiver - The receiver for whom the signal is intended.

subject - A string array specifying the subject of the signal.

signalArgs - The signal arguments. These should never be null or empty.

sendSignalLocal

public static void sendSignalLocal(ID receiver,
                                   ID sender,
                                   java.lang.String[] subject,
                                   java.lang.Object[] signalArgs)

Sends a signal within the local node.

Parameters:

receiver - The receiver for whom the signal is intended.

sender - The sender of the signal.

subject - A string array specifying the subject of the signal.

signalArgs - The signal arguments. These should never be null or empty.

sendSignalLocal

public static void sendSignalLocal(ID[] receivers,
                                   ID sender,
                                   java.lang.String[] subject,
                                   java.lang.Object[] signalArgs)

Sends a signal within the local node.

Parameters:

receivers - An array of receivers for whom the signal is intended.

sender - The sender of the signal.

subject - A string array specifying the subject of the signal.

signalArgs - The signal arguments. These should never be null or empty.

sendSignalLocal

public static void sendSignalLocal(Signal signal)

Sends a signal within the local node.

Parameters:

signal - Signal containing an array of receivers, a sender, a subject and of signal arguments

sendSignalGlobal

public static void sendSignalGlobal(java.lang.Object[] signalArgs)

Sends a signal with specified signal arguments to all nodes eligible to receive it. The receivers and sender fields of the signal are set to null. A node is eligible to receive a global signal sent by this method if it satisfies both of the following tests:

• It is registered to receive signals sent by any sender.
• It is registered to receive signals having any subject.

  Note that each node eligible to receive the signal is sent this signal only once.

sendSignalGlobal

public static void sendSignalGlobal(java.lang.String[] subject,
                                    java.lang.String signalArg)

Sends a signal with specified sender, subject and signal name to all nodes eligible to receive it. The sender is set to null. The signalArg forms the first and only signal argument. A node is eligible to receive a global signal sent by this method if it satisfies both of the following tests:

• It is registered to receive signals sent by any sender.
• It is registered to receive signals having any subject or at least the specific subject mentioned in the signal. If the signal contains a null subject, only those nodes that can receive signals of any subject will satisfy this test.

  Note that each node eligible to receive the signal is sent this signal only once.

sendSignalGlobal

public static void sendSignalGlobal(java.lang.String[] subject,
                                    java.lang.Object[] signalArgs)

Sends a signal with subject and signal arguments to all nodes eligible to receive it. The sender is set to null, A node is eligible to receive a global signal sent by this method if it satisfies both of the following tests:

• It is registered to receive signals sent by any sender.
• It is registered to receive signals having any subject or at least the specific subject mentioned in the signal. If the signal contaisn a null subject, only those nodes that can receive signals of any subject will satisfy this test.

  Note that each node eligible to receive the signal is sent this signal only once.

sendSignalGlobal

public static void sendSignalGlobal(ID sender,
                                    java.lang.String[] subject,
                                    java.lang.Object[] signalArgs)

Sends a signal with spcified sender, subject and signal arguments to all nodes eligible to receive it. A node is eligible to receive a global signal sent by this method if it satisfies both of the following tests:

• It is registered to receive signals sent by any sender or at least the specific sender mentioned in the signal. If the signal contains a null sender, only those nodes that can receive signals from any sender will satisfy this particular test.
• It is registered to receive signals having any subject or at least the specific subject mentioned in the signal. If the signal contaisn a null subject, only those nodes that can receive signals of any subject will satisfy this test.

  Note that each node eligible to receive the signal is sent this signal only once.

sendSignalGlobal

public static void sendSignalGlobal(Signal signal)

Sends a signal to all nodes eligible to receive it. A node is eligible to receive a global signal sent by this method if it satisfies both of the following tests:

• It is registered to receive signals sent by any sender or at least the specific sender mentioned in the signal. If the signal contains a null sender, only those nodes that can receive signals from any sender will satisfy this particular test.
• It is registered to receive signals having any subject or at least the specific subject mentioned in the signal. If the signal contaisn a null subject, only those nodes that can receive signals of any subject will satisfy this test.

  Note that each node eligible to receive the signal is sent this signal only once.

  Parameters:

  signal - Signal containing an array of receivers, a sender, a subject and array of signal arguments.

waitForSignal

public static Signal waitForSignal(java.lang.String[] subject)

Waits for a signal with a given signal name.

Parameters:

subject - matches subject of signal

Returns:

signal with matching signal argument

waitForSignal

public static Signal waitForSignal(java.lang.String signalArg)

Waits for a signal with a given signal name.

Parameters:

signalArg - simple signal argument consisting of a string

Returns:

signal with matching signal argument

waitForSignal

public static Signal waitForSignal(java.lang.Object[] pattern)

Waits for a signal matching the specified pattern. All objects in the pattern array are compared against the corresponding objects in the signal. A null object in the pattern array represents a wildcard, meaning any value matches that object.

Parameters:

pattern - the pattern the signal is matched against.

Returns:

signal that matches the pattern

waitForSignal

public static Signal waitForSignal(java.lang.String[] subject,
                                   SignalEvaluator func)

Waits for a signal matching the signal name and where the SignalEvaluator function evaluates to true.

Parameters:

func - signal evaluation function

Returns:

matching signal

waitForSignal

public static Signal waitForSignal(java.lang.String signalArg,
                                   SignalEvaluator func)

Waits for a signal matching the signal name and where the SignalEvaluator function evaluates to true.

Parameters:

signalArg - simple signal argument consisting of a string

func - signal evaluation function

Returns:

matching signal

waitForSignal

public static Signal waitForSignal(SignalEvaluator func)

Waits for a signal on which the SignalEvaluator function evaluates to true.

Parameters:

func - signal evaluation function

Returns:

matching signal

waitForSignal

public static Signal waitForSignal(ID receiver,
                                   ID sender,
                                   java.lang.String[] subject,
                                   java.lang.Object[] pattern,
                                   SignalEvaluator func)

createSignalQueue

public static SignalWaitQueue createSignalQueue(java.lang.String[] subject)

Create a signal wait Queue for a specific signal type

Returns:

new SignalWaitQueue

createSignalQueue

public static SignalWaitQueue createSignalQueue(java.lang.Object[] pattern)

Create a signal wait Queue for a specific pattern

Parameters:

pattern - Object[] signal pattern

Returns:

new SignalWaitQueue

createSignalQueue

public static SignalWaitQueue createSignalQueue(SignalEvaluator func)

Creates a queue of signals for which the SignalEvaluator function evaluates to true.

Parameters:

func - signal evaluation function

Returns:

new SignalWaitQueue

createSignalQueue

public static SignalWaitQueue createSignalQueue(java.lang.String[] subject,
                                                SignalEvaluator func)

Creates a signal queue for signals matching the specified subject and SignalEvaluator function.

Parameters:

func - signal evaluation function

Returns:

new SignalWaitQueue

createSignalQueue

public static SignalWaitQueue createSignalQueue(ID receiver,
                                                ID sender,
                                                java.lang.String[] subject,
                                                java.lang.Object[] pattern,
                                                SignalEvaluator func)

Creates a signal queue for signals matching the specified receiver, sender subject, pattern and signalEvaluator function.

Parameters:

receiver - recipient of the signal

sender - sender of the signal

pattern - the pattern the signal is matched against.

func - signal evaluation function

Returns:

new SignalWaitQueue

waitForQueuedSignal

public static Signal waitForQueuedSignal(SignalWaitQueue queue)

Wait for a signal that has a associated queue.

Parameters:

queue - SignalWaitQueue object returned from a call to createSignalQueue

Returns:

a Signal

failSelf

public static void failSelf(java.lang.String msg)

Throws a ScoreException, causing method to fail.

Throws:

ScoreException - with specified detail message

failSelf

public static void failSelf()

Throws a ScoreException, causing method to fail.

Throws:

ScoreException - with no detail message

addScenario

public static void addScenario(java.lang.Class newScenario)

Adds a scenario to a table of known scenarios. The newScenario is hashed into this table using newScenario.getName() as the scenario name key. Generates an error if newScenario does not directly or indirectly extend Scenario class.

Parameters:

newScenario - new scenario class

addScenario

public static void addScenario(java.lang.String name,
                               java.lang.Class newScenario)

Adds a scenario to a table of known scenarios and associates it with the specified name.

Parameters:

newScenario - new scenario class

name - the name to associate the new scenario class with

getScenarios

public static java.util.Vector getScenarios()

Gets the Classes of all known scenarios.

Returns:

vector of scenario Class objects

getScenarioNames

public static java.util.Vector getScenarioNames()

Gets the names of known scenarios.

Returns:

vector of scenario names

setCurrentScenario

public static void setCurrentScenario(java.lang.String scenName)

Sets the current scenario. Throws an IllegalArgumentException if no known scenario by the specified name exists.

Parameters:

scenName - the name of the scenario

setCurrentScenario

public static void setCurrentScenario(Scenario scen)

Sets the current scenario.

Parameters:

scen - the scenario

getCurrentScenario

public static Scenario getCurrentScenario()

Gets the current scenario.

Returns:

the current scenario. null if no current scenario is set.

getCurrentScenarioName

public static java.lang.String getCurrentScenarioName()

Gets the name of the current scenario.

Returns:

the current scenario. null if no current scenario is set.

startCurrentScenario

public static void startCurrentScenario()

Initialize and start the current Scenario using the default clock.

startCurrentScenario

public static void startCurrentScenario(OmarClock clock,
                                        boolean isClockDaemonThread)

Initialize and start the current Scenario using the specified clock.

stopCurrentScenario

public static void stopCurrentScenario()

Stop running the current scenario.

pauseCurrentScenario

public static void pauseCurrentScenario()

Pause running the current scenario. Call resumeCurrentScenario to resume running.

resumeCurrentScenario

public static void resumeCurrentScenario()

Resume running the current scenario, which must have been paused.

getResource

public static void getResource(Resource resource,
                               ScoreJThread owner,
                               int priority)

Grabs a resource.

Parameters:

resource - resource to be acquired.

owner - the new owner of the resource.

priority - the priority at which the resources are requested.

getResource

public static void getResource(Resource[] resources,
                               ScoreJThread owner,
                               int priority)

Grabs a set of resources. Does pessimistic locking. i.e. tries to acquire resources one after the other. If it fails to acquire any resource, it releases previously owned resources and starts all over again.

Parameters:

resources - array of resources to be acquired.

owner - the new owner of the resource.

priority - the priority at which the resources are requested.

releaseResource

public static void releaseResource(Resource resource,
                                   ScoreJThread owner)

Releases a previously acquired resource.

Parameters:

resource - the resource to be released.

owner - the current owner of the resource.

releaseResource

public static void releaseResource(Resource[] resources,
                                   ScoreJThread owner)

Releases a set of previously acquired resources.

Parameters:

owner - the current owner of the resources.

transferOwnershipAndStart

public static void transferOwnershipAndStart(ScoreJThread currentOwner,
                                             Resource resource,
                                             ScoreJThread newOwner)

Atomically transfer the ownership of the resource to the specified thread and start the thread. This allows the holder of a resource to transfer ownership of a resource to a thread and then start it without being suspended in between. The new thread that is started is now the new owner of the resource and the thread that called this method loses ownership of the resource.

Parameters:

resource - the resource whose ownership is to be transfered.

transferOwnershipAndStart

public static void transferOwnershipAndStart(ScoreJThread currentOwner,
                                             Resource[] resources,
                                             ScoreJThread newOwner)

Atomically transfer the ownership of the set of resources to the specified thread and start the thread. This method first acquires a lock on the specified set of resources using the pessimistic locking protocol, i.e. it releases previously acquired locks the moment it cannot immediately acquire a lock, then sleeps for while before starting over.

Parameters:

resources - the set of resources whose ownership is to be transfered.

isResourceAvailable

public static boolean isResourceAvailable(Resource resource,
                                          int priority)

Checks whether a resource is available.

Parameters:

resource - the resource for which availability is checked.

Returns:

true if the resource is available, false otherwise.