    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;
    018
    019    import java.util.List;
    020    import java.util.Set;
    021
    022    import org.apache.commons.scxml.model.ModelException;
    023    import org.apache.commons.scxml.model.SCXML;
    024
    025    /**
    026     * <p>The purpose of this interface is to separate the interpretation algorithm
    027     * from the <code>SCXMLExecutor</code> and therefore make it pluggable.</p>
    028     *
    029     * <p>Semantics agnostic utility functions and common operators as defined in
    030     * UML can be found in the <code>SCXMLHelper</code> or attached directly to
    031     * the SCXML model elements. Some of the possible semantic interpretations
    032     * are, for example:</p>
    033     *
    034     * <ul>
    035     * <li>STATEMATE
    036     * <li>RHAPSODY
    037     * <li>ROOMCharts
    038     * <li>UML 1.5
    039     * <li>UML 2.0
    040     * </ul>
    041     *
    042     * <p>Specific semantics can be created by subclassing
    043     * <code>org.apache.commons.scxml.semantics.SCXMLSemanticsImpl</code>.</p>
    044     */
    045    public interface SCXMLSemantics {
    046
    047        /**
    048         * Optional post processing immediately following Digester. May be used
    049         * for removing pseudo-states etc.
    050         *
    051         * @param input
    052         *            SCXML state machine
    053         * @return normalized SCXML state machine, pseudo states are removed, etc.
    054         * @param errRep
    055         *            ErrorReporter callback
    056         */
    057        SCXML normalizeStateMachine(final SCXML input, final ErrorReporter errRep);
    058
    059        /**
    060         * Determining the initial state(s) for this state machine.
    061         *
    062         * @param input
    063         *            SCXML state machine
    064         * @param states
    065         *            a set of States to populate
    066         * @param entryList
    067         *            a list of States and Parallels to enter
    068         * @param errRep
    069         *            ErrorReporter callback
    070         * @param scInstance
    071         *            The state chart instance
    072         *
    073         * @throws ModelException
    074         *             in case there is a fatal SCXML object model problem.
    075         */
    076        void determineInitialStates(final SCXML input, final Set states,
    077                final List entryList, final ErrorReporter errRep,
    078                final SCInstance scInstance)
    079        throws ModelException;
    080
    081        /**
    082         * Executes all OnExit/Transition/OnEntry transitional actions.
    083         *
    084         * @param step
    085         *            provides EntryList, TransitList, ExitList gets
    086         *            updated its AfterStatus/Events
    087         * @param stateMachine
    088         *            state machine - SCXML instance
    089         * @param evtDispatcher
    090         *            the event dispatcher - EventDispatcher instance
    091         * @param errRep
    092         *            error reporter
    093         * @param scInstance
    094         *            The state chart instance
    095         *
    096         * @throws ModelException
    097         *             in case there is a fatal SCXML object model problem.
    098         */
    099        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