org.jscience.engineering.eventdriven
Class Engine

java.lang.Object
  java.lang.Thread
      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:

• Thread-per-engine: All event delivery and state processing is handled by one thread. This is the default.
• Thread-per-model: One delivery thread is created for each model and handles processing for all entities using tha model.
• Thread-per-entity: Every entity has its own event queue and delivery/processing thread.

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.