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