alma.acs.nc.sm.generic

Class AcsScxmlEngine<S extends java.lang.Enum<S>,A extends java.lang.Enum<A>>

java.lang.Object

alma.acs.nc.sm.generic.AcsScxmlEngine<S,A>

Type Parameters:

S - The SM-specific signal enum.

A - The SM-specific action enum.

public class AcsScxmlEngine<S extends java.lang.Enum<S>,A extends java.lang.Enum<A>>
extends java.lang.Object

Class that encapsulates the Scxml engine for ACS. It exposes only a subset of the many features offered by SCXML but also adds functionality. The focus is on compile time checking, connection of action handler code with other pieces of software, and exception handling. We hide dynamic changes to the state model and asynchronous (queued) processing of multiple events.

The code has been taken from ESO SM framework class SMEngine.``

Constructor Summary

Constructors

Constructor and Description
AcsScxmlEngine(java.lang.String scxmlFileName, java.util.logging.Logger logger, AcsScxmlActionDispatcher<A> actionDispatcher, java.lang.Class<S> signalType)

Method Summary

Modifier and Type	Method and Description
boolean	fireSignal(S signal) Sends a signal (event) to the state machine.
boolean	fireSignalWithErrorFeedback(S signal) Synchronous event handling as in fireSignal(Enum), but possibly with exceptions for the following cases: The signal gets checked if it can be handled by the current state(s); an AcsJIllegalStateEventEx exception is thrown if not.
java.util.Set<S>	getApplicableSignals() Gets the signals that would trigger transitions for the current state.
java.lang.String	getCurrentState() Retrieves the current state as a string.
SCXMLExecutor	getEngine() Exposes the underlying SCXMLExecutor engine, for more specialized calls that we don't put in API methods for.
boolean	isStateActive(java.lang.String stateName) Checks if a given state is active.
void	loadModel(java.lang.String scxmlFileName) Loads the SCXML model from an XML file stored inside of a jar file on the classpath.
void	startExecution() Starts SCXML execution.

Methods inherited from class java.lang.Object

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

Constructor Detail

AcsScxmlEngine

public AcsScxmlEngine(java.lang.String scxmlFileName,
                      java.util.logging.Logger logger,
                      AcsScxmlActionDispatcher<A> actionDispatcher,
                      java.lang.Class<S> signalType)

Parameters:

scxmlFileName - The qualified xml file name, e.g. "/alma/acs/nc/sm/EventSubscriberStates.xml", in the form that Class.getResource(String) can use to load the scxml definition file from the classpath.

logger -

actionDispatcher -

signalType - enum class, needed to convert signal names to enum values.

Throws:

java.lang.IllegalArgumentException - if any of the args are null or if the actionDispatcher is not complete for all possible actions.

Method Detail

loadModel

public void loadModel(java.lang.String scxmlFileName)

Loads the SCXML model from an XML file stored inside of a jar file on the classpath.

TODO: define and throw exception in case of load/parse failure.

Parameters:

scxmlFileName - The qualified xml file name, e.g. "/alma/acs/nc/sm/generated/EventSubscriberSCXML.xml"

startExecution

public void startExecution()

Starts SCXML execution.

TODO: define and throw exception in case of model failure.

getCurrentState

public java.lang.String getCurrentState()

Retrieves the current state as a string.

Returns:

The state name(s). Hierarchical states are separated by "::", with outer state first, e.g. "EnvironmentCreated::Connected::Suspended". Parallel states are separated by " ".

isStateActive

public boolean isStateActive(java.lang.String stateName)

Checks if a given state is active. The matching against the current state is done via String comparison, so that especially for hierarchical states it makes sense to call this method asking only for the outer state name(s).

TODO: Protect against mismatches that can occur if one state name includes another state name as a substring, e.g. by splitting names at "::" and comparing those fragements.

Parameters:

stateName - The state name (fragment). Hierarchical states are separated by "::", with outer state first, e.g. "EnvironmentCreated::Connected".

Returns:

true if the given state is active.

getEngine

public SCXMLExecutor getEngine()

Exposes the underlying SCXMLExecutor engine, for more specialized calls that we don't put in API methods for.

fireSignal

public boolean fireSignal(S signal)

Sends a signal (event) to the state machine. The call is synchronous and returns only when the state machine has gone through all transitions/actions, where of course a /do activity would still continue to run asynchronously. Note that the underlying SCXML engine also supports asynchronous sending of multiple events at a time, but we do not expose this feature in ACS.

TODO: How can the client find out whether the signal was applicable for the current state or was ignored?

Returns:

True - if all the states are final and there are not events pending from the last step. False - otherwise.

fireSignalWithErrorFeedback

public boolean fireSignalWithErrorFeedback(S signal)
                                    throws AcsJIllegalStateEventEx,
                                           AcsJStateMachineActionEx,
                                           ModelException

Synchronous event handling as in fireSignal(Enum), but possibly with exceptions for the following cases:

• The signal gets checked if it can be handled by the current state(s); an AcsJIllegalStateEventEx exception is thrown if not.
• If an executed action throws a AcsJStateMachineActionEx exception, that exception gets thrown here. Depending on the concrete state machine, an additional response to the error may be that the SM goes to an error state, due to an internal event triggered by the action.
• ModelException, as thrown by SCXMLExecutor#triggerEvent, unlikely with our static use of the SCXML engine.

Parameters:

signal -

Returns:

True - if all the states are final and there are not events pending from the last step. False - otherwise.

Throws:

AcsJIllegalStateEventEx

AcsJStateMachineActionEx

ModelException

getApplicableSignals

public java.util.Set<S> getApplicableSignals()

Gets the signals that would trigger transitions for the current state.

When actually sending such signals later on, the SM may have moved to a different state. To prevent this, you can synchronize on this AcsScxmlEngine, which will block concurrent calls to fireSignal(Enum).

This method can be useful for displaying applicable signals in a GUI, or to reject signals (with exception etc) that do not "fit" the current state (while normally such signals would be silently ignored). The latter gets used in fireSignalWithErrorFeedback(Enum).

See Also:

org.apache.commons.scxml.semantics.SCXMLSemanticsImpl#enumerateReachableTransitions(SCXML, Step, ErrorReporter)