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