A simple state model example - modelint/flatland-model-diagram-editor GitHub Wiki
File structure
The file structure is as follows:
- metadata (optional) – Title, author, version, etc
- domain – The associated class or relationship is part of this subject matter domain
- state models - Each state model is either a lifecycle or an assigner, complete with events, states and transitions
Executable UML note: For Flatland's purposes there is no need to specify the subsystem at this point. Other tools that process the models may need this information and can obtain it by folding one or more state models together with their corresponding class model at some point. For such tools, the domain establishes which model files belong together (in the same domain).
Let’s take a look at these in a simple example.
A simple state model example
Here we take the Duty Station state machine from the Air Traffic Control case study found in the book Models to Code:
images/model-markup-guide/state-model/10-duty-station-example.png
We aren’t going to encode any layout, style or notational information in the model markup file. This layout is just to give you a visual reference from which we’ll extract the and script the semantic model content.
Metadata
Please refer to the Executable UML class model section to read about the metadata section and comments since we use the same grammar and structure in state model files. Here we'll just show the metadata section of our duty state state model:
metadata /// Hello world example for a state model
Title : Air Traffic Controller State Model
Author : Leon Starr
Document ID : mtc.atc.td.6
Modification date : May 22, 2021
Version : 3.2.0
Organization : Model Integration, LLC
Copyright notice > MIT
Organization logo > mint_logo
Domain
The domain keyword is required. It follows the optional metadata section, if you’ve provided one, otherwise it is at the top of the file.
domain Air Traffic Control
You need to supply a domain name such as Air Traffic Control in our case.
Type of state machine: class or relationship
In Executable UML we have only two kinds of state machines: lifecycle and assigner. A lifecycle state machine represents the lifecycle of a class. Every instance of a class follows the behavioral pattern defined by that class's lifecycle state machine. An assigner state machine is associated with a binary association and manages competition on that association.
Therefore, each state machine must be associated with either a class or a relationship name. In our Duty Station example, we have a lifecycle state machine, so we designate the associated class:
class Air Traffic Controller
(Were it an assigner, we would use the relationship keyword with a relationship name such as R57)
Event specifications
Next we specify each event defined on the state machine. Here are the events for our example:
Note: The signatures are no longer shown next to eent names. They now appear as state signatures next to any state name that requires one or more parameters. Will update the example later, but take a look at the Elevator Case Study *.xsm files for up to date examples.
events
Cannot go on duty
Off duty
Ready for duty( Station: Station ID )
Log in( Station: Station Number )
Logged in
Handoff( Zone: Czone Name, Controller: Employee ID )
Handoff complete
Ready for a break
Must hand off zones
Log out
Rejected handoff
Cannot handoff
--
Each event consists of a name and an optional set of parameter, data type pairs in parentheses. The event section must be terminated by a double hyphen -- indented at the same level as the event keyword.
States
From here on down to the remainder of the file are one or more state sections. Each state section defines a required state name, required activity and optional transitions. Here is the specification for the OFF DUTY state:
state OFF DUTY
activity
// Not controlling traffic
transitions
Ready for duty > Verify adequate break
--
The first line specifies the state name.
The activity keyword is followed by all actions within the state. The activity section is required, but need not enclose any actions or comments. Note that the comment in this example is marked by a double and not a triple slash. That is because the comment is meant to appear as text inside the state and is not a comment about the model file itself.
The optional transitions keyword terminates the activity. If absent, the activity is terminated by the end of file or any unindented keyword such as state, so you don't terminate an activity with the -- symbol used elsewhere.
In Executable UML there are three possible responses to each event in a given state: transition, ignore and can't happen. In the example above, a single transition is defined for an occurrence of the Ready for duty event leading to the Verify adequate break state. The > symbol designates a transition response. If we want to ignore an event, we just name the event and omit the > part. And any event defined in the event section, but not mentioned is considered to be a can't happen response.
Here are the remaining states defined for our example. Not that one of them has been temporarily commented out. You can comment out portions of a model file while developing the model or testing diagram output.
state Verifying adequate break
activity
the shift spec .= Shift Specification(1) // selects singleton
( _now - self.Last shift ended < the shift spec.Min break ) ?
Log in( in.Station ) -> me : Cannot go on duty -> me
transitions
Log in > Logging in
Cannot go on duty > OFF DUTY
--
state Logging in
activity
>> On Duty Controller
my station = Duty Station( Number: in.Station )
&R3 my station // link station
Time logged in = _now.HMS
Logged in -> me
In use -> my station
transitions
Logged in > ON DUTY
--
state ON DUTY
activity
// Controlling traffic
transitions
Handoff > Handing off control zone
Ready for a break > Verifying full handoff
--
state Handing off control zone
activity
new controller .= On Duty Controller( ID: in.Controller )
hoff zone .= /R2/Control Zone( Name: in.Zone )
(hoff zone and new controller and new controller.ID != ID)? {}
new controller &R2 hoff zone
Handoff complete -> me
} : Handoff rejected -> me
transitions
///Handoff rejected > Failed handoff
Handoff complete > ON DUTY
--
///state Failed handoff
///activity
/// UI.Cannot handoff( atc: ID, Zone: in.zone )
/// Cannot handoff -> ON DUTY
///--
state Verifying full handoff
activity
/R1/On Duty Controller/R2/Control Zone? {
Must handoff zones -> me
Warning( "Control Zones Active", ID ) => UI
} : Log out -> me
transitions
Log out > Logging out
Must hand off zones > ON DUTY
--
state Logging out
activity
User leaving -> /R3/Duty Station
>> Off Duty Controller
Last shift ended = _now.HMS
Off duty -> me
transitions
Off duty > OFF DUTY