org.jscience.engineering.eventdriven
Class Engine

java.lang.Object
  extended by java.lang.Thread
      extended by org.jscience.engineering.eventdriven.Engine
All Implemented Interfaces:
java.lang.Runnable

public final class Engine
extends java.lang.Thread

This is the run-time core of the state engine system. This thread is responsible for controlling the dispatchers and data structures of the whole system.

The engine can be configured to run with one of three thread schemes:

The thread-per-model and thread-per-entity schemes may improve performance on systems with more than one processor. The thread scheme is set by calling setThreadScheme() with a string parameter value of "engine","model" or "entity" (the string is not case-sensitive and can contain leading or trailing white space). Passing a null value or an empty string sets the default mode.

When setting up an Engine the recommended sequence of operations is:

  1. Create the Model objects;
  2. Create the Engine object;
  3. Add the models to the Engine;
  4. Start the Engine (Engine.start());

Once running, entities can be created and events delivered to them. To stop the engine thread cleanly, call shutdown() then Engine.join() to wait for it to terminate.


Nested Class Summary
 
Nested classes/interfaces inherited from class java.lang.Thread
java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler
 
Field Summary
static java.util.Properties cfgProp
          

Configuration properties, if any.

static int THREAD_PER_ENGINE
          

Preset value for thread-per-engine thread scheme.

static int THREAD_PER_ENTITY
          

Preset value for thread-per-entity thread scheme.

static int THREAD_PER_MODEL
          

Preset value for thread-per-model thread scheme.

 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Constructor Summary
Engine(java.lang.String id)
          

Constructor.

 
Method Summary
 void addModel(Model model)
          

Add a model to the Engine's internal data.

 AbsEntity createEntity(java.lang.String modelId, java.lang.String entityId, java.lang.Object[] initArgs)
          

Creates a new Entity for a specific Model.

 void generateEvent(java.lang.String entityId, java.lang.String eventSpecId)
          

Generate an event with no arguments for delivery to a specified entity.

 void generateEvent(java.lang.String entityId, java.lang.String eventSpecId, java.lang.Object[] args)
          

Generate an event for delivery to a specified entity.

 void run()
           
 void setExceptionHandler(IExceptionHandler exceptionHandler)
          

Set the exception handler.

 void setStateChangeHandler(IStateChangeHandler stateChangeHandler)
          

Set the state change handler.

 void setThreadScheme(int threadSchemeValue)
          

Set the thread scheme.

 void setThreadScheme(java.lang.String threadSchemeString)
          

Set the thread scheme.

 void shutdown()
          

Order the Engine thread to terminate.

 void start()
           
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, stop, stop, suspend, toString, yield
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

THREAD_PER_ENGINE

public static final int THREAD_PER_ENGINE

Preset value for thread-per-engine thread scheme.

See Also:
Constant Field Values

THREAD_PER_MODEL

public static final int THREAD_PER_MODEL

Preset value for thread-per-model thread scheme.

See Also:
Constant Field Values

THREAD_PER_ENTITY

public static final int THREAD_PER_ENTITY

Preset value for thread-per-entity thread scheme.

See Also:
Constant Field Values

cfgProp

public static java.util.Properties cfgProp

Configuration properties, if any. By default this will be empty (not null). The location of a property file can be provided as a system property on the command line (using the -Djspasm.configuration=location setting).

Constructor Detail

Engine

public Engine(java.lang.String id)

Constructor.

Parameters:
id - The name to give to the engine.
Method Detail

addModel

public void addModel(Model model)
              throws StateModelConfigurationException

Add a model to the Engine's internal data.

Parameters:
model - The model to register.
Throws:
StateModelConfigurationException - if the supplied model is null or already registered.
java.lang.IllegalStateException - DOCUMENT ME!

createEntity

public AbsEntity createEntity(java.lang.String modelId,
                              java.lang.String entityId,
                              java.lang.Object[] initArgs)
                       throws StateProcessingException,
                              java.lang.InstantiationException,
                              java.lang.IllegalAccessException

Creates a new Entity for a specific Model. The Entity class is as defined by the Model.

Parameters:
modelId - The model to create the entity in.
entityId - The unique id to give to the entity.
initArgs - The initialization arguments (must match the arguments for the Model's initial state).
Returns:
the new Entity subclass.
Throws:
StateProcessingException - if any arguments are null, the model does not exist or the entity id already exists.
java.lang.InstantiationException - if the entity cannot be instantiated.
java.lang.IllegalAccessException - if the state method of the initialization state cannot be executed.
java.lang.IllegalStateException - DOCUMENT ME!

generateEvent

public void generateEvent(java.lang.String entityId,
                          java.lang.String eventSpecId,
                          java.lang.Object[] args)
                   throws StateProcessingException

Generate an event for delivery to a specified entity.

Parameters:
entityId - The target of the event.
eventSpecId - The event type to be generated.
args - The event arguments.
Throws:
StateProcessingException - if any arguments are null, the event or entity names do not exist, etc.

generateEvent

public void generateEvent(java.lang.String entityId,
                          java.lang.String eventSpecId)
                   throws StateProcessingException

Generate an event with no arguments for delivery to a specified entity.

Parameters:
entityId - The target of the event.
eventSpecId - The event type to be generated.
Throws:
StateProcessingException - if any arguments are null, the event or entity names do not exist, etc.

run

public void run()
Specified by:
run in interface java.lang.Runnable
Overrides:
run in class java.lang.Thread

start

public void start()
Overrides:
start in class java.lang.Thread

setExceptionHandler

public void setExceptionHandler(IExceptionHandler exceptionHandler)

Set the exception handler. Exception handling is disabled by setting the exception handler to null.

Parameters:
exceptionHandler - Exception handler instance, or null.
Throws:
java.lang.IllegalStateException - DOCUMENT ME!

setStateChangeHandler

public void setStateChangeHandler(IStateChangeHandler stateChangeHandler)

Set the state change handler. Change handling is disabled by setting the state change handler to null.

Parameters:
stateChangeHandler - StateChangeHandler instance, or null.
Throws:
java.lang.IllegalStateException - DOCUMENT ME!

setThreadScheme

public void setThreadScheme(int threadSchemeValue)
                     throws java.lang.Exception

Set the thread scheme.

Parameters:
threadSchemeValue - The thread scheme value.
Throws:
java.lang.Exception - if the engine is already running or the scheme value is invalid.
java.lang.IllegalStateException - DOCUMENT ME!

setThreadScheme

public void setThreadScheme(java.lang.String threadSchemeString)
                     throws java.lang.Exception

Set the thread scheme.

Parameters:
threadSchemeString - The thread scheme name.
Throws:
java.lang.Exception - if the engine is already running or the scheme name is not recognized.
java.lang.IllegalStateException - DOCUMENT ME!

shutdown

public void shutdown()

Order the Engine thread to terminate.