Commons SCXML FAQ

General

1. What is SCXML?
2. What is Commons SCXML?
3. Do you have a simple example where Commons SCXML is used?
4. What are the core requirements of SCXML?

Expression languages

1. Which expression languages does the Commons SCXML implementation support?
2. Can I use more than one expression language in the same SCXML document?

The SCXMLExecutor

1. Once I set up an SCXMLExecutor (call the constructor, set the state machine) is there anything I have to do to "activate" it?
2. Can I have multiple instances of SCXMLExecutor all working off of a single instance of the SCXML class?
3. Can multiple threads safely interact with an instance of SCXMLExecutor?
4. Are SCXMLExecutor instances serializable?

General

What is SCXML?

State Chart XML (SCXML) is a general-purpose event-based state machine language that can be used in many ways. It is currently a W3C Working Draft, available here.

[top]

---

What is Commons SCXML?

Commons SCXML is aimed at creating and maintaining an open-source Java SCXML engine capable of executing a state machine defined using a SCXML document, while abstracting out the environment interfaces.

[top]

---

Do you have a simple example where Commons SCXML is used?

Sure, take a look at the stopwatch usecase.

[top]

---

What are the core requirements of SCXML?

The "core" requirements for Commons SCXML are Commons Logging. You will need to choose an expression language for your SCXML documents (details in next section of this FAQ). See the dependencies page for details about the dependency versions.

[top]

Expression languages

Which expression languages does the Commons SCXML implementation support?

Commons SCXML currently supports Commons JEXL, Javascript, XPath and Groovy. For details, see the trying out and contexts and evaluators pages of the user guide.

[top]

---

Can I use more than one expression language in the same SCXML document?

No, the expressions throughout the document must be homogeneous. This also applies to any external documents that may be referred by this document, for example via "src" attributes.

[top]

The SCXMLExecutor

Once I set up an SCXMLExecutor (call the constructor, set the state machine) is there anything I have to do to "activate" it?

Yes, you must call the marker method, SCXMLExecutor#go(). This serves as an indication that you have finished configuring the SCXMLExecutor instance and are now ready to begin executing the state machine described by your SCXML document. For example, you may attach zero, one or many SCXMLListeners to interesting "nodes" within the SCXML document, such as the document root i.e. the SCXML object, and/or particular State and Transition objects as well. See the SCXMLExecutor section of the user guide for more.

[top]

---

Can I have multiple instances of SCXMLExecutor all working off of a single instance of the SCXML class?

Yes. The Commons SCXML object model does not store any information related to a particular execution of the state machine. It is therefore possible to use a single SCXML instance as the state machine for multiple SCXMLExecutor instances. This also means that a SCXML document needs to be parsed only once, irrespective of the number of "instances" of the state machine that may execute.

[top]

---

Can multiple threads safely interact with an instance of SCXMLExecutor?

To a certain extent. The execution of an SCXML state machine through an SCXMLExecutor instance may only be done, as per the specification, sequentially.

Multiple threads may 'send' or 'register' new events on a state machine through its #addEvent methods, which then will be processed sequentially by the SCXMLExecutor.

If such events are registered while the state machine is executing, these will processed automatically before the state machine 'returns' in a stable state.

If such events are registered or added while the state machine is in a stable state, the SCXMLExecutor its #triggerEvents method will have to be invoked for the state machine to proceed with processing these events.

The SCXMLExecutor methods themselves are not thread save, and thus it is the responsibility of the 'manager' of the SCXMLExecutor, typically the thread creating and initializing the state machine to also execute the state machine and check upon its state.

Other threads collaborating with the state machine however should refrain to only use the #addEvent methods, or otherwise be (externally) coordinated such that only one thread at a time is triggering the execution of the state machine.

[top]

---

Are SCXMLExecutor instances serializable?

No, but the SCInstance of an SCXMLExecutor, which contains all the 'state' of the state machine including the SCXML document itself, is serializable after detaching through its #detachInstance method as long as all associated user-defined content is too.

A detached SCInstance can be re-attached to the SCXMLExecutor using its #attachInstance method.

[top]