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