net.dpml.state
Interface StateMachine


public interface StateMachine

Defintion of the state machine. The state machine handles the maintenance of a single current state and supports the invocation of transition and operations relative to the current state. Invocation of transiton and operations are handled via two mechansims:

  1. triggers
  2. explicit invocation of the 'appply' and 'execute' operations

Triggers, Transitions, and Operations may be declared within any state and enter active scope when when the enclosing state is within the current state path (where the current state path is the sequence of state's from the current state to the root state).

Transitions and operations available at any given time are a function of all uniquely named transitions and operations exposed within the current state path. If multiple instances of a transition or operation share the same name, the instance closest to the current state takes precedence and the duplicate instance will not be exposed (equivalent to overriding the characteristics of a super-state).

Triggers are structures that hold a single action (transition or operation) and are invoked automatically by a state machine implementation as a part of initialization and termination requests. If a trigger contains a transition resulting that results in a change to the current state a state-machine will recursively evaluate triggers in the new current state path. The process of recursive evaluation of triggers will continue until a state is reached where no further trigger invocation is possible.

Version:
2.1.0
Author:
Digital Product Management Library

Method Summary
 void addStateListener(StateListener listener)
          Add a state change listener to the state machine.
 State apply(String name, Object object)
          Apply a named state transition.
 Object execute(String name, Object object, Object[] args)
          Execute a named operation on the supplied object.
 Interface[] getInterfaces()
          Return all of the available interfaces relative to the current state.
 Operation[] getOperations()
          Return all of the available operations relative to the current state.
 State getState()
          Return the current state.
 Transition[] getTransitions()
          Return all of the available transitions relative to the current state.
 State initialize(Object object)
          Invoke initialization of the supplied object using the initialization action declared under the current state path.
 Object invoke(Object object, String method, Object[] args)
          Invoke a management method on the supplied object.
 boolean isActive()
          Returns the active status of the state machine.
 void removeStateListener(StateListener listener)
          Remove a state listener from the state machine.
 State terminate(Object object)
          Invoke termination of the supplied object using the termination action declared under the current state path.
 

Method Detail

addStateListener

void addStateListener(StateListener listener)
Add a state change listener to the state machine.

Parameters:
listener - the state listener

removeStateListener

void removeStateListener(StateListener listener)
Remove a state listener from the state machine.

Parameters:
listener - the state listener

getState

State getState()
Return the current state.

Returns:
the current state

initialize

State initialize(Object object)
                 throws InvocationTargetException
Invoke initialization of the supplied object using the initialization action declared under the current state path.

Parameters:
object - the object to initialize
Returns:
the state established as a side-effect of initialization
Throws:
InvocationTargetException - if an invocation error occurs as a result of initialization

execute

Object execute(String name,
               Object object,
               Object[] args)
               throws UnknownOperationException,
                      InvocationTargetException
Execute a named operation on the supplied object.

Parameters:
name - an operation name
object - the target object
args - operation argument array
Returns:
the return value
Throws:
UnknownOperationException - if the operation is unknown
InvocationTargetException - if an invocation error occurs as a result of operation execution

invoke

Object invoke(Object object,
              String method,
              Object[] args)
              throws UnknownOperationException,
                     InvocationTargetException,
                     IllegalStateException
Invoke a management method on the supplied object.

Parameters:
object - the target object
method - the method name
args - method parameter arguments
Returns:
the return value
Throws:
IllegalStateException - if the method is recognized but not available
UnknownOperationException - if the operation is unknown
InvocationTargetException - if an invocation error occurs as a result of operation execution

apply

State apply(String name,
            Object object)
            throws UnknownTransitionException,
                   InvocationTargetException
Apply a named state transition.

Parameters:
name - the transition name
object - the object against which any transition handler action are to be applied
Returns:
the state established by the application of the transition
Throws:
UnknownTransitionException - if the transition is unknown
InvocationTargetException - if an invocation error occurs as a result of transition invocation

getTransitions

Transition[] getTransitions()
Return all of the available transitions relative to the current state.

Returns:
the available transitions

getOperations

Operation[] getOperations()
Return all of the available operations relative to the current state.

Returns:
the available operations

getInterfaces

Interface[] getInterfaces()
Return all of the available interfaces relative to the current state.

Returns:
the available interface declarations

terminate

State terminate(Object object)
Invoke termination of the supplied object using the termination action declared under the current state path.

Parameters:
object - the object to terminate
Returns:
the state established as a side-effect of the termination

isActive

boolean isActive()
Returns the active status of the state machine.

Returns:
TRUE if the state machine has invoked initialization and termination has not been performed otherwise FALSE