org.jscience.engineering.eventdriven
Class Model

java.lang.Object
  org.jscience.engineering.eventdriven.Model

public class Model
extends java.lang.Object

A Model object describes a state model by holding all the information about the valid states and events and the transitions that occur when events are delivered to entities that are in a given state. It also identifies the class of entities that are valid for the model and the initial state that new entities are created in.

Action code for each state is actually in the entity class. While this may seem strange, most state code manipulates entity data and if the state methods were implemented in the state class the entity reference would require a cast on entry to almost every state method. Placing the state code in the entity avoids this and improves overall performance.

Model objects can be set up by instantiating a Model object then adding states, events etc. Alternatively, and probably preferable for most applications, subclass Model and add the model details in the subclass constructor.

There are some basic rules that must be adhered to:

• States can not be registered before the entity class has been specified;
• The initial state can not be defined before that state has been registered;
• Transitions can not be specified until the states and events involved have been registered.

The suggested order to do things, then, is:

1. Specify the entity class;
2. Add the states;
3. Set the initial state;
4. Add the events;
5. Add the transitions.

Constructor Summary

Model(java.lang.String id)

Constructor.

Method Summary

void	addEventSpec(java.lang.String eventSpecId, java.lang.Class[] argClasses) Adds an event spec to the model, where the event's arguments are defined by a class array.
void	addEventSpec(java.lang.String eventSpecId, java.lang.String classListString) Adds an event spec to the model, where the event's arguments are defined by a comma/space-separated String of fully-qualified class names.
void	addExcursionTransition(java.lang.String startStateId, java.lang.String eventSpecId, java.lang.String endStateId) Add an EXCURSION transition.
void	addIgnoreTransition(java.lang.String startStateId, java.lang.String eventSpecId) Add an IGNORE transition.
void	addNoExecuteTransition(java.lang.String startStateId, java.lang.String eventSpecId, java.lang.String endStateId) Add a NO_EXECUTE transition.
void	addNormalTransition(java.lang.String startStateId, java.lang.String eventSpecId, java.lang.String endStateId) Add an NORMAL transition.
void	addState(java.lang.String stateId, java.lang.String methodName, java.lang.Class[] argClasses) Adds a state to the model, where the state's arguments are defined by a class array.
void	addState(java.lang.String stateId, java.lang.String methodName, java.lang.String classListString) Adds a state to the model, where the state's arguments are defined by a comma/space-separated String of fully-qualified class names.
void	addTransition(java.lang.String startStateId, java.lang.String eventSpecId, java.lang.String endStateId, int transitionType) Add a transition to the model.
void	setEntityClass(java.lang.Class entityClass) Set the entity class associated with the model.
void	setEntityClass(java.lang.String entityClassName) Set the entity class associated with the model.
void	setInitialState(java.lang.String initialStateId) Set the initial state for new entities created in this model.

Methods inherited from class java.lang.Object

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

Constructor Detail

Model

public Model(java.lang.String id)

Constructor.

Parameters:

id - The model name.

Throws:

java.lang.NullPointerException - DOCUMENT ME!

Method Detail

addEventSpec

public final void addEventSpec(java.lang.String eventSpecId,
                               java.lang.Class[] argClasses)
                        throws StateModelConfigurationException

Adds an event spec to the model, where the event's arguments are defined by a class array.

Parameters:

eventSpecId - The name to give to the event spec.

argClasses - The event's argument class list. Use new Class[0] when the event has no arguments.

Throws:

StateModelConfigurationException - if any arguments are null, the event spec name already exists in the model, or the entity class has not been set.

addEventSpec

public final void addEventSpec(java.lang.String eventSpecId,
                               java.lang.String classListString)
                        throws StateModelConfigurationException

Adds an event spec to the model, where the event's arguments are defined by a comma/space-separated String of fully-qualified class names.

Parameters:

eventSpecId - The name to give to the event spec.

classListString - Comma/space-separated list of argument class names. Use the empty string "" when no arguments are required.

Throws:

StateModelConfigurationException - if any arguments are null, any of the named classes can not be loaded, the event spec name already exists in the model, or the entity class has not been set.

addState

public final void addState(java.lang.String stateId,
                           java.lang.String methodName,
                           java.lang.Class[] argClasses)
                    throws StateModelConfigurationException

Adds a state to the model, where the state's arguments are defined by a class array.

Parameters:

stateId - The name to give to the state.

methodName - The name of the state's action method in the entity class.

argClasses - The state's argument class list. Use new Class[0] when the event has no arguments.

Throws:

StateModelConfigurationException - if any arguments are null, the state name is already registered, the entity class has not been set or the specified method can not be located.

addState

public final void addState(java.lang.String stateId,
                           java.lang.String methodName,
                           java.lang.String classListString)
                    throws StateModelConfigurationException

Adds a state to the model, where the state's arguments are defined by a comma/space-separated String of fully-qualified class names.

Parameters:

stateId - The name to give to the state.

methodName - The name of the state's action method in the entity class.

classListString - Comma/space-separated list of argument class names. Use the empty string "" when no arguments are required.

Throws:

StateModelConfigurationException - if any arguments are null, any of the named classes can not be loaded, the state name is already registered, the entity class has not been set or the specified method can not be located.

addTransition

public final void addTransition(java.lang.String startStateId,
                                java.lang.String eventSpecId,
                                java.lang.String endStateId,
                                int transitionType)
                         throws StateModelConfigurationException

Add a transition to the model.

Parameters:

startStateId - The start state.

eventSpecId - The event that caused the transition.

endStateId - The end state (must be null for IGNORE transitions).

transitionType - The transition type code (use the constants defined in the ITransitionType interface).

Throws:

StateModelConfigurationException - if the transition type is invalid, the start state or event name is null, the end state is null for non-IGNORE transitions ot non-null for IGNORE transitions, the entity class has not been defined, or any of the state or event names have not been registered, or the arguments for the event do not match those for the end state.

addExcursionTransition

public final void addExcursionTransition(java.lang.String startStateId,
                                         java.lang.String eventSpecId,
                                         java.lang.String endStateId)
                                  throws StateModelConfigurationException

Add an EXCURSION transition. In these transitions the entity reverts to the original state after the end state action code has been executed.

Parameters:

startStateId - The start state.

eventSpecId - The event that caused the transition.

endStateId - The end state (must be null for IGNORE transitions).

Throws:

StateModelConfigurationException - under the same conditions as for addTransition().

addIgnoreTransition

public final void addIgnoreTransition(java.lang.String startStateId,
                                      java.lang.String eventSpecId)
                               throws StateModelConfigurationException

Add an IGNORE transition. In these transitions the target entity does not change state and no state code is executed.

Parameters:

startStateId - The start state.

eventSpecId - The event that caused the transition.

Throws:

StateModelConfigurationException - under the same conditions as for addTransition().

addNoExecuteTransition

public final void addNoExecuteTransition(java.lang.String startStateId,
                                         java.lang.String eventSpecId,
                                         java.lang.String endStateId)
                                  throws StateModelConfigurationException

Add a NO_EXECUTE transition. In these transitions the entity state changes in the usual way but the end state's action code is not executed.

Parameters:

startStateId - The start state.

eventSpecId - The event that caused the transition.

endStateId - The end state (must be null for IGNORE transitions).

Throws:

StateModelConfigurationException - under the same conditions as for addTransition().

addNormalTransition

public final void addNormalTransition(java.lang.String startStateId,
                                      java.lang.String eventSpecId,
                                      java.lang.String endStateId)
                               throws StateModelConfigurationException

Add an NORMAL transition.

Parameters:

startStateId - The start state.

eventSpecId - The event that caused the transition.

endStateId - The end state (must be null for IGNORE transitions).

Throws:

StateModelConfigurationException - under the same conditions as for addTransition().

setEntityClass

public final void setEntityClass(java.lang.Class entityClass)
                          throws StateModelConfigurationException

Set the entity class associated with the model.

Parameters:

entityClass - The entity class.

Throws:

StateModelConfigurationException - if the argument is null or an entity class has already been defined for this model.

setEntityClass

public final void setEntityClass(java.lang.String entityClassName)
                          throws java.lang.ClassNotFoundException,
                                 StateModelConfigurationException

Set the entity class associated with the model.

Parameters:

entityClassName - The entity class name.

Throws:

java.lang.ClassNotFoundException - if the named class can not be loaded.

StateModelConfigurationException - if an entity class has already been defined for this model.

setInitialState

public final void setInitialState(java.lang.String initialStateId)
                           throws StateModelConfigurationException

Set the initial state for new entities created in this model.

Parameters:

initialStateId - The name of the initial state.

Throws:

StateModelConfigurationException - if the argument is null, the initial state has already been set, or the state name does not exist in the model.