State Machine Schema
From Arizona CopperSoft
Contents |
Introduction
The state machine schema is an XML Schema document that defines the valid structure of a state machine.
Namespace
The namespace of this schema is:
http://www.arizonacoppersoft.com/BigRed/SM/02-15-2009
For the sake of convenience, the namespace is also a URL to the actual XSD file.
Unicode
Big Red supports Unicode characters. When Big Red generates helper classes for input signals, it will attempt to convert the name of the signal and the signal-states to acceptable Java identifiers. This feature is implemented in manner that allows developers to provide a custom class for converting names to identifiers.
Types
io-type
The io-type is an enumeration that allows the values "input" and "output". The io-type is used by the signal element to indicate if the signal is used for input or output.
command-name-type
The command-name-type defines an enumeration of possible command names to be used in the command element. Possible values are:
- Add - Add the specified signal-state to the output.
- Subtract - Subtract the specified signal-state from the output.
- Clear - Clear all of the signal-states from the output.
Elements
action
The action element defines an action to be perform on the state machine's output. The element should contain command elements which defines which signal-states should be added and subtracted.
Example:
<action> <name>Do Alarm</name> <command name="Add"> <output state="ON" signal="Alarm" /> </command> <command name="Subtract"> <output signal="Alarm" state="OFF" /> </command> </action>
annotation
The annotation element allows additional information to be attached to an element. An annotation may contain any number of documentation elements. Annotations may be added to most elements.
Example:
<annotation> <documentation xml:lang="en"> <!-- this is a comment and will not appear in the docuementation --> <p>This <strong>sensor</strong> will be reused in the secondary state machine.</p> <p>More stuff...</p> </documentation> </annotation>
bind
The bind element defines all of the signal-states that should be copied between the primary and secondary state machines. The bind element uses the "type" attribute to define if the signal-states should be copied as input from the primary to the secondary, or as output from the secondary to the primary.
Example:
<bind type="input"> <ref>Sensor A</ref> </bind>
command
The command element defines the signal-states that should be added or subtracted from the state machine's output signals.
Example:
<command name="Add"> <output state="ON" signal="Alarm" /> </command>
condition
The condition element is used by the transition and input-action elements to define the input condition required to execute the transition or the input-action. A condition may contain an expression, an input signal-state, TRUE, or FALSE.
Example:
<condition> <input state="HIGH" signal="Sensor A"/> </condition>
documentation
The documentation element is for human readable documentation. Content creators are encouraged to use the xml:lang attribute to specify the language. A more attribute may be added that contains a URI to more documentation. Big Red can generate helper classes based on the input signals and it will insert the documentation from the signal and signal-state elements into the Javadoc comments for the generated class. Big Red will ignore documentation elements that are not text-only. However, other schemas can be used within the documentation element like XHTML.
Example:
<documentation xml:lang="en"> <!-- this is a comment and will not appear in the docuementation --> <p>This <strong>sensor</strong> will be reused in the secondary state machine.</p> <p>More stuff...</p> </documentation>
execute
The execute element defines the name of a secondary state machine and all of the bindings necessary to copy input and output between the primary and secondary state machines. [Note: The secondary execution scheme has not been finalized.]
Example:
<execute state-machine="Secondary"> <bind type="input"> <ref>Sensor A</ref> </bind> </execute>
expression
The expression element defines a binary operation (AND or OR) between two expressions, inputs, and the Boolean values TRUE and FALSE. The element is used to build complex conditions for input actions and transitions.
Example:
<expression> <input signal="Sensor A" state="UNKNOWN" /> <and /> <input signal="Sensor B" state="X" /> </expression>
import
The import element causes another XML file to be loaded as if its content were entered directly. This will allow a state machine file to broken up into several pieces. The location of the file may be specified as a URL or a path for the local file-system. When using the file-system, an attempt will be made to open the file as specified, and then to open it relative to the primary state machine.
include
The include causes another state machine XML file to be loaded as a secondary state machine. The XML file may be specified by a file-name on the local file-system or a URL.
Example:
<include> <file>src/test/resources/global-vio-secondary.xml</file> </include>
<include> <url>http://www.some-domain.com/resources/global-vio-secondary.xml</url> </include>
input
The input element is used by the condition and expression elements to define the input signal-state to be tested.
<input signal="Sensor A" state="UNKNOWN" />
input-action
The input-action element defines the actions to be executed if a specific input condition is true. Input actions are attached to a specific state.
name
The name name element is used to specify the name of a signal and an action.
output
The output element is used by the command element to define which output signal-states should be modified.
primary
The primary element is used by the bind element to define the signal-state in the primary state machine that will be copied to/from the secondary state machine.
secondary
The secondary element is used by the bind element to define a signal-state in the secondary state machine that will be copied to/from the primary state machine.
signal
The signal element defines a new signal. The names of the signal must be unique within a state machine. The signal may be an input or output type.
signal-state
A signal-state defines an enumerated state for a signal. The names of the states must be unique within a signal.
state
The state element contains annotations, entry actions, exit actions, input actions, secondary state machines, and transitions. The state element defines a "name" attribute which must contain a name unique to the state machine being defined.
state-machine
The state-machine element is the top-level element for a state machine. The element contains annotations, a state machine title, initial-state and end-state, inclusions of other state machines, virtual IO declarations, action declarations, and state declarations.
transition
The transition element defines a transition from one state to another. Since the transition is attached to the starting state, only the ending state must be defined explicitly. A transition may contain any number of actions to execute if the transition is selected by the state machine, and it must define the condition necessary for the transition to occur.
