org.apache.commons.scxml.invoke
Interface Invoker

All Known Implementing Classes:

SimpleSCXMLInvoker

public interface Invoker

The Invoker interface is used to define the possible interactions between the parent state machine (executor) and the types of invocable activities.

Invocable activities must first register an Invoker implementation class for the appropriate "targettype" (attribute of <invoke>) with the parent SCXMLExecutor.

The communication link between the parent state machine executor and the invoked activity is a bi-directional events pipe.

All events triggered on the parent state machine get forwarded to the invoked activity. The processing semantics for these events depend upon the "targettype", and thereby vary per concrete implementation of this interface.

The invoked activity in turn must fire a special "done" event when it concludes. It may fire additional events before the "done" event. The semantics of any additional events depend upon the "targettype". The invoked activity must not fire any events after the "done" event. The name of the special "done" event must be the ID of the parent state wherein the corresponding <invoke> resides, with the String ".invoke.done" appended.

The Invoker "lifecycle" is outlined below:

1. Instantiation via Class.newInstance() (Invoker implementation requires accessible constructor).
2. Configuration (setters for parent state ID and SCInstance).
3. Initiation of invoked activity via invoke() method, passing the source URI and the map of params.
4. Zero or more bi-directional event triggering.
5. Either completion or cancellation.

Note: The semantics of <invoke> are necessarily asynchronous, tending towards long(er) running interactions with external processes. Implementations must not communicate with the parent state machine executor in a synchronous manner. For synchronous communication semantics, use <event> or custom actions instead.

Method Summary

void	cancel() Cancel this invocation.
void	invoke(java.lang.String source, java.util.Map params) Begin this invocation.
void	parentEvents(TriggerEvent[] evts) Forwards the events triggered on the parent state machine on to the invoked activity.
void	setParentStateId(java.lang.String parentStateId) Set the state ID of the owning state for the <invoke>.
void	setSCInstance(SCInstance scInstance) Set the "context" of the parent state machine, which provides the channel.

Method Detail

setParentStateId

void setParentStateId(java.lang.String parentStateId)

Set the state ID of the owning state for the <invoke>. Implementations must use this ID for constructing the event name for the special "done" event (and optionally, for other event names as well).

Parameters:

parentStateId - The ID of the parent state.

setSCInstance

void setSCInstance(SCInstance scInstance)

Set the "context" of the parent state machine, which provides the channel.

Parameters:

scInstance - The "context" of the parent state machine.

invoke

void invoke(java.lang.String source,
            java.util.Map params)
            throws InvokerException

Begin this invocation.

Parameters:

source - The source URI of the activity being invoked.

params - The <param> values

Throws:

InvokerException - In case there is a fatal problem with invoking the source.

parentEvents

void parentEvents(TriggerEvent[] evts)
                  throws InvokerException

Forwards the events triggered on the parent state machine on to the invoked activity.

Parameters:

evts - an array of external events which triggered during the last time quantum

Throws:

InvokerException - In case there is a fatal problem with processing the events forwarded by the parent state machine.

cancel

void cancel()
            throws InvokerException

Cancel this invocation.

Throws:

InvokerException - In case there is a fatal problem with canceling this invoke.