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