1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.scxml2.invoke;
18
19 import java.util.Map;
20
21 import org.apache.commons.scxml2.SCXMLExecutor;
22 import org.apache.commons.scxml2.SCXMLIOProcessor;
23 import org.apache.commons.scxml2.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 "target" (attribute of <invoke>) with the
32 * parent <code>SCXMLParentIOProcessor</code>.</p>
33 *
34 * <p>The communication link between the parent state machine executor and
35 * the invoked activity is a asynchronous 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 "target", 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 * "target". The invoked activity must not fire any events after the "done"
46 * event. The name of the special "done" event must be "done.invoke.id" with
47 * the ID of the parent state wherein the corresponding <invoke> resides,</p>
48 *
49 * <p>The Invoker "lifecycle" is outlined below:
50 * <ol>
51 * <li>Instantiation via {@link Class#newInstance()}
52 * (Invoker implementation requires accessible constructor).</li>
53 * <li>Configuration (setters for invoke ID and
54 * {@link org.apache.commons.scxml2.SCXMLExecutor}).</li>
55 * <li>Initiation of invoked activity via invoke() method, passing
56 * the source URI and the map of params.</li>
57 * <li>Zero or more bi-directional event triggering.</li>
58 * <li>Either completion or cancellation.</li>
59 * </ol>
60 * </p>
61 *
62 * <p><b>Note:</b> The semantics of <invoke> are necessarily
63 * asynchronous, tending towards long(er) running interactions with external
64 * processes. Implementations cannot communicate with the parent state
65 * machine executor in a synchronous manner. For synchronous
66 * communication semantics, use <event> or custom actions instead.</p>
67 */
68 public interface Invoker {
69
70 /**
71 * @return get the invoke ID provided by the parent state machine executor
72 */
73 String getInvokeId();
74
75 /**
76 * Set the invoke ID provided by the parent state machine executor
77 * Implementations must use this ID for constructing the event name for
78 * the special "done" event (and optionally, for other event names
79 * as well).
80 *
81 * @param invokeId The invoke ID provided by the parent state machine executor.
82 */
83 void setInvokeId(String invokeId);
84
85 /**
86 * Sets the parent SCXMLExecutor through which this Invoker is initiated
87 * @param scxmlExecutor the parent SCXMLExecutor
88 */
89 void setParentSCXMLExecutor(SCXMLExecutor scxmlExecutor);
90
91 /**
92 * Get the child IO Processor to register for communication with
93 * the parent session.
94 *
95 * @return Child IO Processor
96 */
97 SCXMLIOProcessor getChildIOProcessor();
98
99 /**
100 * Begin this invocation.
101 *
102 * @param source The source URI of the activity being invoked.
103 * @param params The <param> values
104 * @throws InvokerException In case there is a fatal problem with
105 * invoking the source.
106 */
107 void invoke(String source, Map<String, Object> params)
108 throws InvokerException;
109
110 /**
111 * Forwards the event triggered on the parent state machine
112 * on to the invoked activity.
113 *
114 * @param event
115 * an external event which triggered during the last
116 * time quantum
117 *
118 * @throws InvokerException In case there is a fatal problem with
119 * processing the events forwarded by the
120 * parent state machine.
121 */
122 void parentEvent(TriggerEvent event)
123 throws InvokerException;
124
125 /**
126 * Cancel this invocation.
127 *
128 * @throws InvokerException In case there is a fatal problem with
129 * canceling this invoke.
130 */
131 void cancel()
132 throws InvokerException;
133 }
134