View Javadoc

    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.scxml;
    18
    19  import java.util.List;
    20  import java.util.Set;
    21
    22  import org.apache.commons.scxml.model.ModelException;
    23  import org.apache.commons.scxml.model.SCXML;
    24
    25  /***
    26   * <p>The purpose of this interface is to separate the interpretation algorithm
    27   * from the <code>SCXMLExecutor</code> and therefore make it pluggable.</p>
    28   *
    29   * <p>Semantics agnostic utility functions and common operators as defined in
    30   * UML can be found in the <code>SCXMLHelper</code> or attached directly to
    31   * the SCXML model elements. Some of the possible semantic interpretations
    32   * are, for example:</p>
    33   *
    34   * <ul>
    35   * <li>STATEMATE
    36   * <li>RHAPSODY
    37   * <li>ROOMCharts
    38   * <li>UML 1.5
    39   * <li>UML 2.0
    40   * </ul>
    41   *
    42   * <p>Specific semantics can be created by subclassing
    43   * <code>org.apache.commons.scxml.semantics.SCXMLSemanticsImpl</code>.</p>
    44   */
    45  public interface SCXMLSemantics {
    46
    47      /***
    48       * Optional post processing immediately following Digester. May be used
    49       * for removing pseudo-states etc.
    50       *
    51       * @param input
    52       *            SCXML state machine
    53       * @return normalized SCXML state machine, pseudo states are removed, etc.
    54       * @param errRep
    55       *            ErrorReporter callback
    56       */
    57      SCXML normalizeStateMachine(final SCXML input, final ErrorReporter errRep);
    58
    59      /***
    60       * Determining the initial state(s) for this state machine.
    61       *
    62       * @param input
    63       *            SCXML state machine
    64       * @param states
    65       *            a set of States to populate
    66       * @param entryList
    67       *            a list of States and Parallels to enter
    68       * @param errRep
    69       *            ErrorReporter callback
    70       * @param scInstance
    71       *            The state chart instance
    72       *
    73       * @throws ModelException
    74       *             in case there is a fatal SCXML object model problem.
    75       */
    76      void determineInitialStates(final SCXML input, final Set states,
    77              final List entryList, final ErrorReporter errRep,
    78              final SCInstance scInstance)
    79      throws ModelException;
    80
    81      /***
    82       * Executes all OnExit/Transition/OnEntry transitional actions.
    83       *
    84       * @param step
    85       *            provides EntryList, TransitList, ExitList gets
    86       *            updated its AfterStatus/Events
    87       * @param stateMachine
    88       *            state machine - SCXML instance
    89       * @param evtDispatcher
    90       *            the event dispatcher - EventDispatcher instance
    91       * @param errRep
    92       *            error reporter
    93       * @param scInstance
    94       *            The state chart instance
    95       *
    96       * @throws ModelException
    97       *             in case there is a fatal SCXML object model problem.
    98       */
    99      void executeActions(final Step step, final SCXML stateMachine,
    100             final EventDispatcher evtDispatcher, final ErrorReporter errRep,
    101             final SCInstance scInstance)
    102     throws ModelException;
    103
    104     /***
    105      * Enumerate all the reachable transitions.
    106      *
    107      * @param stateMachine
    108      *            a state machine to traverse
    109      * @param step
    110      *            with current status and list of transitions to populate
    111      * @param errRep
    112      *            ErrorReporter callback
    113      */
    114     void enumerateReachableTransitions(final SCXML stateMachine,
    115             final Step step, final ErrorReporter errRep);
    116
    117     /***
    118      * Filter the transitions set, eliminate those whose guard conditions
    119      * are not satisfied.
    120      *
    121      * @param step
    122      *            with current status
    123      * @param evtDispatcher
    124      *            the event dispatcher - EventDispatcher instance
    125      * @param errRep
    126      *            ErrorReporter callback
    127      * @param scInstance
    128      *            The state chart instance
    129      *
    130      * @throws ModelException
    131      *             in case there is a fatal SCXML object model problem.
    132      */
    133     void filterTransitionsSet(final Step step,
    134             final EventDispatcher evtDispatcher, final ErrorReporter errRep,
    135             final SCInstance scInstance)
    136     throws ModelException;
    137
    138     /***
    139      * Follow the candidate transitions for this execution Step, and update the
    140      * lists of entered and exited states accordingly.
    141      *
    142      * @param step The current Step
    143      * @param errorReporter The ErrorReporter for the current environment
    144      * @param scInstance The state chart instance
    145      *
    146      * @throws ModelException
    147      *             in case there is a fatal SCXML object model problem.
    148      */
    149     void followTransitions(final Step step, final ErrorReporter errorReporter,
    150             final SCInstance scInstance)
    151     throws ModelException;
    152
    153     /***
    154      * Go over the exit list and update history information for
    155      * relevant states.
    156      *
    157      * @param step
    158      *            The current Step
    159      * @param errRep
    160      *            ErrorReporter callback
    161      * @param scInstance
    162      *            The state chart instance
    163      */
    164     void updateHistoryStates(final Step step, final ErrorReporter errRep,
    165             final SCInstance scInstance);
    166
    167     /***
    168      * Forward events to invoked activities, execute finalize handlers.
    169      *
    170      * @param events
    171      *            The events to be forwarded
    172      * @param errRep
    173      *            ErrorReporter callback
    174      * @param scInstance
    175      *            The state chart instance
    176      *
    177      * @throws ModelException
    178      *             in case there is a fatal SCXML object model problem.
    179      */
    180     void processInvokes(final TriggerEvent[] events,
    181             final ErrorReporter errRep, final SCInstance scInstance)
    182     throws ModelException;
    183
    184     /***
    185      * Initiate any new invoked activities.
    186      *
    187      * @param step
    188      *            The current Step
    189      * @param errRep
    190      *            ErrorReporter callback
    191      * @param scInstance
    192      *            The state chart instance
    193      *
    194      */
    195     void initiateInvokes(final Step step, final ErrorReporter errRep,
    196             final SCInstance scInstance);
    197
    198 }
    199