| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Copyright 2005-2006 The Apache Software Foundation |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <document> |
| |
| <properties> |
| <title>Commons SCXML Usage - API notes - Triggering Events</title> |
| <author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author> |
| </properties> |
| |
| <body> |
| |
| <section name="Commons SCXML - Firing events on the SCXML engine"> |
| |
| <p>Once the SCXML engine has been initialized, the state machine |
| progresses based on the events that are fired on it. When an event |
| is fired, if the current set of states have transitions waiting |
| for that event, and the guard condition on one of those transitions |
| is satisfied, the state machine is said to "follow" that |
| transition, which may possibly yield a new set of current states. |
| Most state machines will ultimately reach a "final" state, |
| wherein the state machine has said to have executed to completion. |
| </p> |
| |
| <subsection name="Usage"> |
| <p>An event "foo.bar" may be fired on the engine as |
| follows:</p> |
| <pre> |
| //import org.apache.commons.scxml.SCXMLExecutor; |
| //import org.apache.commons.scxml.TriggerEvent; |
| //import org.apache.commons.scxml.model.ModelException; |
| |
| // where "exec" is the SCXMLExecutor instance |
| TriggerEvent[] te = { new TriggerEvent("foo.bar", |
| TriggerEvent.SIGNAL_EVENT) }; |
| try { |
| exec.triggerEvents(te); |
| } catch (ModelException me) { |
| // The events left the engine in inconsistent state |
| } |
| </pre> |
| |
| <p>If the resulting events leave the state machine in an inconsistent |
| state, a <code>ModelException</code> may be thrown. |
| </p> |
| |
| <p>More than one events may be triggered on the state machine at a |
| time. After the engine processes a set of trigger events, it is |
| customary to check whether the state machine has reached a <final> |
| state.</p> |
| |
| <p>The following snippet illustrates how the <code>SCXMLExecutor</code> |
| <code>Status</code> is queried for state machine run to completion.</p> |
| |
| <pre> |
| //import org.apache.commons.scxml.SCXMLExecutor; |
| //import org.apache.commons.scxml.Status; |
| |
| // where "exec" is the SCXMLExecutor instance |
| Status status = exec.getCurrentStatus(); |
| if (status.isFinal()) { |
| // run to completion, release cached objects |
| } |
| </pre> |
| |
| <p>The <code>TriggerEvent</code> Javadoc is available |
| <a href="../apidocs/org/apache/commons/scxml/TriggerEvent.html"> |
| here</a>.<br/> |
| The <code>Status</code> Javadoc is available |
| <a href="../apidocs/org/apache/commons/scxml/Status.html"> |
| here</a><br/> |
| </p> |
| </subsection> |
| |
| <subsection name="API notes set"> |
| <p>The previous note in this set describes the |
| <a href="core-engine.html">SCXML engine</a>.</p> |
| </subsection> |
| |
| </section> |
| |
| </body> |
| |
| </document> |
