Modeling Executable StateMachines

Most of the work required to model an Executable StateMachine is standard UML based modeling of Classes and State models. There are a couple of conventions that must be observed to ensure a well formed code base. The only novel construct is the use of a stereotyped Artifact element to form the configuration of an Executable StateMachine instance or scenario. The Artifact is used to specify details such as:

The code language (JavaScript, C#, Java, C++ including C)
The Classes and StateMachines involved in the scenario
The instance specifications including run-state; note that this could include multiple instances of the same StateMachine, for example where a 'Player' Class is used twice in a Tennis Match simulation

Basic Modeling Tools and Objects for Executable StateMachines

These are the primary modeling elements used when building Executable StateMachines.

Object	Details
Classes and Class Diagrams	Classes define the object types that are relevant to the StateMachine(s) being modeled. For example, in a simple Tennis Match scenario you might define a Class for each of a Player, a Match, a Hit and an Umpire. Each will have its own StateMachine(s) and at runtime will be represented by object instances for each involved entity. See the UML modeling guide for more information on Classes and Class diagrams.
StateMachines	For each Class you define that will have dynamic behavior within a scenario, you will typically define one or more UML StateMachines. Each StateMachine will determine the legal state-based behavior appropriate for one aspect of the owning Class. For example, it is possible to have a StateMachine that represents a Player's emotional state, one that tracks his current fitness and energy levels, and one that represents his winning or losing state. All these StateMachines will be initialized and started when the StateMachine scenario begins execution.
Executable StateMachine Artifact	This stereotyped Artifact is the core element used to specify the participants, configuration and starting conditions for an Executable StateMachine. From the scenario point of view it is used to determine which Instances (of Classes) are involved, what events they might Trigger and send to each other, and what starting conditions they operate under. From the configuration aspect, the Artifact is used to set up the link to an analyzer script that will determine output directory, code language, compilation script and similar. Right-clicking on the Artifact will allow you to generate, build, compile and visualize the real time execution of your StateMachines.

Object

Details

Classes and Class Diagrams

Classes define the object types that are relevant to the StateMachine(s) being modeled. For example, in a simple Tennis Match scenario you might define a Class for each of a Player, a Match, a Hit and an Umpire. Each will have its own StateMachine(s) and at runtime will be represented by object instances for each involved entity. See the UML modeling guide for more information on Classes and Class diagrams.

StateMachines

For each Class you define that will have dynamic behavior within a scenario, you will typically define one or more UML StateMachines. Each StateMachine will determine the legal state-based behavior appropriate for one aspect of the owning Class. For example, it is possible to have a StateMachine that represents a Player's emotional state, one that tracks his current fitness and energy levels, and one that represents his winning or losing state. All these StateMachines will be initialized and started when the StateMachine scenario begins execution.

Executable StateMachine Artifact

This stereotyped Artifact is the core element used to specify the participants, configuration and starting conditions for an Executable StateMachine. From the scenario point of view it is used to determine which Instances (of Classes) are involved, what events they might Trigger and send to each other, and what starting conditions they operate under.

From the configuration aspect, the Artifact is used to set up the link to an analyzer script that will determine output directory, code language, compilation script and similar. Right-clicking on the Artifact will allow you to generate, build, compile and visualize the real time execution of your StateMachines.

StateMachine Constructs Supported

This table details the StateMachine constructs supported and any limitations or general constraints relevant to each type.

Construct	Description
StateMachines	Simple StateMachine: StateMachine has one region Orthogonal StateMachine: StateMachine contains multiple regions Top level region (owned by StateMachine) activation semantics: Default Activation: When the StateMachine starts executing. Entry Point Entry: Transitions from Entry Point to vertices in the contained regions. Note 1: In each Region of the StateMachine owning the Entry Point, there is at most a single Transition from the entry point to a Vertex within that Region Note 2: This StateMachine can be referenced by a Submachine State - connection point reference should be defined in the Submachine State as sources/targets of transitions; the Connection point reference represents a usage of an Entry/Exit Point defined in the StateMachine and referenced by the Submachine State Not Supported Protocol StateMachine StateMachine Redefinition
States	Simple State: has no internal Vertices or Transitions Composite State: contains exactly one Region Orthogonal State: contains multiple Regions Submachine State: refers to an entire StateMachine
Composite State Entry	Default Entry Explicit Entry Shallow History Entry Deep History Entry Entry Point Entry
Substates	Substates and Nested Substates Entry and Exit semantics, where the transition includes multiple nested levels of states, will obey correct execution of nested behaviors (such as OnEntry and OnExit).
Transitions support	External Transition Local Transition Internal Transition (draw a self Transition and change Transition kind to Internal) Completion Transition and Completion Events Transition Guards Compound Transitions Firing priorities and selection algorithm For further details, refer to the UML Specification.
Trigger and Events	An Executable StateMachine supports event handling for Signals only. To use Call, Timing or Change Event types you must define an outside mechanism to generate signals based on these events.
Signal	Attributes can be defined in Signals; the value of the attributes can be used as event arguments in Transition Guards and Effects. For example, this is the code set in the effect of a transition in C++: if(signal->signalEnum == ENUM_SIGNAL2) { int xVal = ((Signal2*)signal)->myVal; } Signal2 is generated as this code: class Signal2 : public Signal{ public: Signal2(){}; Signal2(std::vector<String>& lstArguments); int myVal; }; Note: Further details can be found by generating an Executable StateMachine and referring to the generated 'EventProxy' file.
Initial	An Initial Pseudostate represents a starting point for a Region. It is the source for at most one Transition; there can be at most one Initial Vertex in a Region.
Regions	Default Activation & Explicit Activation: Transitions terminate on the containing State: If an initial Pseudostate is defined in the Region: Default activation If no initial Pseudostate is defined, the Region will remain inactive and the containing State is treated as a Simple State Transition terminates on one of the Region's contained vertices: Explicit activation, resulting in the default activation of all of its orthogonal Regions, unless those Regions are also entered explicitly (multiple orthogonal Regions can be entered explicitly in parallel through Transitions originating from the same Fork Pseudostate) For example, if there are three Regions defined for a Orthogonal State, and RegionA and RegionB have an Initial Pseudostate, then RegionC is explicitly activated. Default Activation applies to RegionA and RegionB; the containing State will have three active Regions.
Choice	Guard Constraints on all outgoing Transitions are evaluated dynamically, when the compound transition traversal reaches this Pseudostate.
Junction	Static conditional branch: guard constraints are evaluated before any compound transition is executed.
Fork / Join	Non-threaded, each active Region moves one step alternately, based on a completion event pool mechanism.
EntryPoint / ExitPoint Nodes	Non-threaded for orthogonal State or orthogonal StateMachine; each active Region moves one step alternately, based on a completion event pool mechanism.
History Nodes	DeepHistory: represents the most recent active State configuration of its owning State ShallowHistory: represents the most recent active Substate of its containing State, but not the Substates of that Substate
Deferred Events	Draw a self Transition, and change the Transition kind to Internal. Type 'defer();' in the 'Effect' field for the transition.
Connection Point References	A Connection Point Reference represents a usage (as part of a Submachine State) of an Entry/Exit Point defined in the StateMachine referenced by the Submachine State. Connection Point References of a Submachine State can be used as sources and targets of Transitions. They represent entries into or exits out of the StateMachine referenced by the Submachine State.
State behaviors	State 'entry', 'doActivity' and 'exit' behaviors are defined as operations on a State. By default, you type the code that will be used for each behavior into the 'Code' panel of the Properties window for the Behavior operation. Note that you can change this to type the code into the 'Behavior' panel, by customizing the generation template. The 'doActivity' behavior generated will be run to completion before proceeding. The code is not concurrent with other entry behavior; the 'doActivity' behavior is implemented as 'execute in sequence after entry' behavior.

References to Behaviors within other Contexts/Classes

If the Submachine State references behavior elements outside the current context or Class, you must add an <<import>> connector from the current context Class to the container context Class. For example:

Submachine State S1 in Class1 refers to StateMachine ST2 in Class2

Therefore, we add an <<import>> connector from Class1 to Class2 in order for Executable StateMachine code generation to generate code correctly for Submachine State S1. (On Class 1, click on the Quick Linker arrow and drag to Class 2, then select 'Import' from the menu of connector types.)

Reusing Executable StateMachine Artifacts

You can create multiple models or versions of a component using a single executable Artifact. An Artifact representing a resistor, for example, could be re-used to create both a foil resistor and a wire wound resistor. This is likely to be the case for similar objects that, although represented by the same classifier, typically exhibit different run states. A property named 'resistorType' taking the value 'wire' rather than 'foil' might be all that is required from a modeling point of view. The same StateMachines can then be re-used to test behavioral changes that might result due to variance in run-state. This is the procedure:

Step	Action
Create or open Component diagram	Open a Component diagram to work on. This might be the diagram that contains your original Artifact.
Select the Executable StateMachine to copy	Now find the original Executable StateMachine Artifact in the Project Browser.
Create the New Component	Whilst holding the Ctrl key, drag the original Artifact on to your diagram. You will be prompted with two questions. The answer to the first is Object and to the second All. Rename the Artifact to differentiate it from the original and then proceed to alter its property values.

Step

Action

Create or open Component diagram

Open a Component diagram to work on. This might be the diagram that contains your original Artifact.

Select the Executable StateMachine to copy

Now find the original Executable StateMachine Artifact in the Project Browser.

Create the New Component

Whilst holding the Ctrl key, drag the original Artifact on to your diagram. You will be prompted with two questions.

The answer to the first is Object and to the second All. Rename the Artifact to differentiate it from the original and then proceed to alter its property values.