1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 package org.apache.commons.scxml.invoke;
19
20 import java.util.Map;
21
22 import org.apache.commons.scxml.SCInstance;
23 import org.apache.commons.scxml.TriggerEvent;
24
25 /***
26 * <p>The Invoker interface is used to define the possible interactions
27 * between the parent state machine (executor) and the types of invocable
28 * activities.</p>
29 *
30 * <p>Invocable activities must first register an Invoker implementation class
31 * for the appropriate "targettype" (attribute of <invoke>) with the
32 * parent <code>SCXMLExecutor</code>.</p>
33 *
34 * <p>The communication link between the parent state machine executor and
35 * the invoked activity is a bi-directional events pipe.</p>
36 *
37 * <p>All events triggered on the parent state machine get forwarded to the
38 * invoked activity. The processing semantics for these events depend
39 * upon the "targettype", and thereby vary per concrete implementation of
40 * this interface.</p>
41 *
42 * <p>The invoked activity in turn must fire a special "done" event
43 * when it concludes. It may fire additional events before the "done"
44 * event. The semantics of any additional events depend upon the
45 * "targettype". The invoked activity must not fire any events after the
46 * "done" event. The name of the special "done" event must be
47 * the ID of the parent state wherein the corresponding <invoke>
48 * resides, with the String ".invoke.done" appended.</p>
49 *
50 * <p>The Invoker "lifecycle" is outlined below:
51 * <ol>
52 * <li>Instantiation via {@link Class#newInstance()}
53 * (Invoker implementation requires accessible constructor).</li>
54 * <li>Configuration (setters for parent state ID and
55 * {@link SCInstance}).</li>
56 * <li>Initiation of invoked activity via invoke() method, passing
57 * the source URI and the map of params.</li>
58 * <li>Zero or more bi-directional event triggering.</li>
59 * <li>Either completion or cancellation.</li>
60 * </ol>
61 * </p>
62 */
63 public interface Invoker {
64
65 /***
66 * Set the state ID of the owning state for the <invoke>.
67 * Implementations must use this ID for constructing the event name for
68 * the special "done" event (and optionally, for other event names
69 * as well).
70 *
71 * @param parentStateId The ID of the parent state.
72 */
73 void setParentStateId(String parentStateId);
74
75 /***
76 * Set the "context" of the parent state machine, which provides the
77 * channel.
78 *
79 * @param scInstance The "context" of the parent state machine.
80 */
81 void setSCInstance(SCInstance scInstance);
82
83 /***
84 * Begin this invocation.
85 *
86 * @param source The source URI of the activity being invoked.
87 * @param params The <param> values
88 * @throws InvokerException In case there is a fatal problem with
89 * invoking the source.
90 */
91 void invoke(String source, Map params)
92 throws InvokerException;
93
94 /***
95 * Forwards the events triggered on the parent state machine
96 * on to the invoked activity.
97 *
98 * @param evts
99 * an array of external events which triggered during the last
100 * time quantum
101 *
102 * @throws InvokerException In case there is a fatal problem with
103 * processing the events forwarded by the
104 * parent state machine.
105 */
106 void parentEvents(TriggerEvent[] evts)
107 throws InvokerException;
108
109 /***
110 * Cancel this invocation.
111 *
112 * @throws InvokerException In case there is a fatal problem with
113 * canceling this invoke.
114 */
115 void cancel()
116 throws InvokerException;
117
118 }
119