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