| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You 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>Using custom semantics for the Commons SCXML engine</title> |
| <author email="dev@commons.apache.org">Commons Documentation Team</author> |
| </properties> |
| |
| <body> |
| |
| <section name="SCXML Semantics"> |
| |
| <p><b>This section is for advanced users only, and will probably not |
| be needed by most users of the Commons SCXML library.</b></p> |
| |
| <subsection name="Pluggable semantics"> |
| |
| <p>The Commons SCXML state machine engine is really a tuple, the |
| <a href="../apidocs/org/apache/commons/scxml/SCXMLExecutor.html">SCXMLExecutor</a> |
| (an API that new users can code to, and is almost always sufficient) |
| accompanied by a |
| <a href="../apidocs/org/apache/commons/scxml/SCXMLSemantics.html">SCXMLSemantics</a> |
| implementation (an API that advanced users can code to, to change the |
| engine behavior to suit their needs).</p> |
| |
| <p>The basic modus operandi for an engine is simple - when an event is |
| triggered, figure out which (if any) transition(s) to follow, and |
| transit to the new set of states executing any specified actions along |
| the way. The default semantics available in the Commons SCXML distribution |
| can be replaced with custom semantics provided by the user using the |
| <code>SCXMLExecutor</code> constructor that takes the |
| <code>SCXMLSemantics</code> parameter i.e. the engine semantics are |
| "pluggable".</p> |
| |
| </subsection> |
| |
| <subsection name="Example scenario"> |
| |
| <p>Consider dispute resolution for example -- when more than one |
| outbound transitions from a single state hold true. The default |
| <code>SCXMLSemantics</code> implementation available in the distribution |
| does none, it will follow all filtered transitions, possibly leading to a |
| <code>ModelException</code> immediately or down the road. However, a user |
| may want:</p> |
| |
| <ul> |
| <li>The transition defined closest to the document root to be |
| followed</li> |
| <li>The transition defined farthest from the document root to be |
| followed</li> |
| <li>The transition whose origin and target have the lowest common |
| ancestor to be followed</li> |
| <li>The transition whose origin and target have the highest common |
| ancestor to be followed</li> |
| </ul> |
| |
| <p>Even after one of above dispute resolution algorithms is applied, if |
| there are more than one candidate transitions, the user may want:</p> |
| |
| <ul> |
| <li>A <code>ModelException</code> to be thrown</li> |
| <li>The transition that appears first in document order to be |
| followed</li> |
| <li>The transition that appears last in document order to be |
| followed</li> |
| </ul> |
| |
| <p>To implement any of the above choices, the user may extend the |
| default <code>SCXMLSemantics</code> implementation, override the |
| <code>filterTransitionsSet()</code> method (or write a new implementation |
| from scratch), and plug in the new semantics while instantiating the |
| <code>SCXMLExecutor</code>. The pluggability allows differing semantics |
| to be developed for the Commons SCXML engine, independent of the Commons |
| SCXML codebase.</p> |
| |
| </subsection> |
| |
| </section> |
| |
| </body> |
| |
| </document> |