View Javadoc

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