View Javadoc

1   /*
2    *
3    *   Copyright 2006 The Apache Software Foundation.
4    *
5    *  Licensed under the Apache License, Version 2.0 (the "License");
6    *  you may not use this file except in compliance with the License.
7    *  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   */
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 &lt;invoke&gt;) 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 &lt;invoke&gt;
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 &lt;invoke&gt;.
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 &lt;param&gt; 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