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