001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.commons.scxml.invoke;
018:
019: import java.util.Map;
020:
021: import org.apache.commons.scxml.SCInstance;
022: import org.apache.commons.scxml.TriggerEvent;
023:
024: /**
025: * <p>The Invoker interface is used to define the possible interactions
026: * between the parent state machine (executor) and the types of invocable
027: * activities.</p>
028: *
029: * <p>Invocable activities must first register an Invoker implementation class
030: * for the appropriate "targettype" (attribute of <invoke>) with the
031: * parent <code>SCXMLExecutor</code>.</p>
032: *
033: * <p>The communication link between the parent state machine executor and
034: * the invoked activity is a bi-directional events pipe.</p>
035: *
036: * <p>All events triggered on the parent state machine get forwarded to the
037: * invoked activity. The processing semantics for these events depend
038: * upon the "targettype", and thereby vary per concrete implementation of
039: * this interface.</p>
040: *
041: * <p>The invoked activity in turn must fire a special "done" event
042: * when it concludes. It may fire additional events before the "done"
043: * event. The semantics of any additional events depend upon the
044: * "targettype". The invoked activity must not fire any events after the
045: * "done" event. The name of the special "done" event must be
046: * the ID of the parent state wherein the corresponding <invoke>
047: * resides, with the String ".invoke.done" appended.</p>
048: *
049: * <p>The Invoker "lifecycle" is outlined below:
050: * <ol>
051: * <li>Instantiation via {@link Class#newInstance()}
052: * (Invoker implementation requires accessible constructor).</li>
053: * <li>Configuration (setters for parent state ID and
054: * {@link SCInstance}).</li>
055: * <li>Initiation of invoked activity via invoke() method, passing
056: * the source URI and the map of params.</li>
057: * <li>Zero or more bi-directional event triggering.</li>
058: * <li>Either completion or cancellation.</li>
059: * </ol>
060: * </p>
061: */
062: public interface Invoker {
063:
064: /**
065: * Set the state ID of the owning state for the <invoke>.
066: * Implementations must use this ID for constructing the event name for
067: * the special "done" event (and optionally, for other event names
068: * as well).
069: *
070: * @param parentStateId The ID of the parent state.
071: */
072: void setParentStateId(String parentStateId);
073:
074: /**
075: * Set the "context" of the parent state machine, which provides the
076: * channel.
077: *
078: * @param scInstance The "context" of the parent state machine.
079: */
080: void setSCInstance(SCInstance scInstance);
081:
082: /**
083: * Begin this invocation.
084: *
085: * @param source The source URI of the activity being invoked.
086: * @param params The <param> values
087: * @throws InvokerException In case there is a fatal problem with
088: * invoking the source.
089: */
090: void invoke(String source, Map params) throws InvokerException;
091:
092: /**
093: * Forwards the events triggered on the parent state machine
094: * on to the invoked activity.
095: *
096: * @param evts
097: * an array of external events which triggered during the last
098: * time quantum
099: *
100: * @throws InvokerException In case there is a fatal problem with
101: * processing the events forwarded by the
102: * parent state machine.
103: */
104: void parentEvents(TriggerEvent[] evts) throws InvokerException;
105:
106: /**
107: * Cancel this invocation.
108: *
109: * @throws InvokerException In case there is a fatal problem with
110: * canceling this invoke.
111: */
112: void cancel() throws InvokerException;
113:
114: }
|