Invoker (Apache Commons SCXML 2.0-SNAPSHOT API)

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 "target" (attribute of <invoke>) with the parent SCXMLParentIOProcessor.

The communication link between the parent state machine executor and the invoked activity is a asynchronous 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 "target", 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 "target". The invoked activity must not fire any events after the "done" event. The name of the special "done" event must be "done.invoke.id" with the ID of the parent state wherein the corresponding <invoke> resides,

The Invoker "lifecycle" is outlined below:
1. Instantiation via Class.newInstance() (Invoker implementation requires accessible constructor).
2. Configuration (setters for invoke ID and SCXMLExecutor).
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 cannot communicate with the parent state machine executor in a synchronous manner. For synchronous communication semantics, use <event> or custom actions instead.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`cancel()` Cancel this invocation.
`SCXMLIOProcessor`	`getChildIOProcessor()` Get the child IO Processor to register for communication with the parent session.
`String`	`getInvokeId()`
`void`	`invoke(String source, Map<String,Object> params)` Begin this invocation.
`void`	`parentEvent(TriggerEvent event)` Forwards the event triggered on the parent state machine on to the invoked activity.
`void`	`setInvokeId(String invokeId)` Set the invoke ID provided by the parent state machine executor Implementations must use this ID for constructing the event name for the special "done" event (and optionally, for other event names as well).
`void`	`setParentSCXMLExecutor(SCXMLExecutor scxmlExecutor)` Sets the parent SCXMLExecutor through which this Invoker is initiated

- Method Detail
  - getInvokeId
```
String getInvokeId()
```
    Returns:
    get the invoke ID provided by the parent state machine executor
  - setInvokeId
```
void setInvokeId(String invokeId)
```
    Set the invoke ID provided by the parent state machine executor Implementations must use this ID for constructing the event name for the special "done" event (and optionally, for other event names as well).
    
    Parameters:
    invokeId - The invoke ID provided by the parent state machine executor.
  - setParentSCXMLExecutor
```
void setParentSCXMLExecutor(SCXMLExecutor scxmlExecutor)
```
    Sets the parent SCXMLExecutor through which this Invoker is initiated
    
    Parameters:
    scxmlExecutor - the parent SCXMLExecutor
  - getChildIOProcessor
```
SCXMLIOProcessor getChildIOProcessor()
```
    Get the child IO Processor to register for communication with the parent session.
    
    Returns:
    Child IO Processor
  - invoke
```
void invoke(String source,
          Map<String,Object> 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.
  - parentEvent
```
void parentEvent(TriggerEvent event)
                 throws InvokerException
```
    Forwards the event triggered on the parent state machine on to the invoked activity.
    
    Parameters:
    event - an external event 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.

Interface Invoker

Method Summary

Method Detail

getInvokeId

setInvokeId

setParentSCXMLExecutor

getChildIOProcessor

invoke

parentEvent

cancel