View source for Documentation:State Diagrams

You can use a State Diagram in MDriven Designer to define the allowed lifecycle states and state changes for instances of a class, such as a House moving from Plan to Construction.
== What a State Diagram models ==
A '''State Diagram''' (also called a state machine diagram) describes the states an object can be in and the transitions that move it between those states. Use it when a class has a lifecycle with meaningful phases, rules, or actions.

For example, a <code>House</code> can move through these states:

* <code>Plan</code>
* <code>Construction</code>
* <code>Maintenance</code>
* <code>Demolition</code>

The State Diagram belongs to a class through its '''State''' attribute. The State attribute is marked with an '''S''' icon when the state-diagram symbol is available.

State Diagrams are one of the diagram types available in MDriven Designer. For the role of class and process diagrams, see [[Documentation:MDriven designer overview Part 1]] and [[Documentation:Class diagrams]].
== Create and open a StateMachine ==
# In MDriven Designer, add a '''StateMachine''' for the class whose lifecycle you want to model.
# MDriven Designer opens the new StateMachine when it is created.
# Return to the class diagram using the back navigation. The class now has a <code>State</code> attribute that is a state attribute.
# Open the diagram again by selecting '''Show state diagram''' for the State attribute, or by opening the StateMachine from the repository tree.

For example, adding a StateMachine to <code>House</code> creates the state attribute <code>House.State</code>. In the State Diagram, the Property Inspector identifies the state attribute as <code>State</code> in <code>House.State</code>. You can change the state attribute name, category, and color used for new states in the Property Inspector.
== Build a lifecycle ==
Create states that reflect the business situation of the object, then connect them with transitions.

For a House lifecycle, define the following progression:

{| class="wikitable"
! State
! Meaning
! Example transition into the state
|-
| <code>Plan</code>
| The House is planned but construction has not started.
| The initial state reaches <code>Plan</code> when no guard prevents it.
|-
| <code>Construction</code>
| The House is being built.
| <code>StartConstruction</code>
|-
| <code>Maintenance</code>
| The House is in use and maintained.
| <code>ConstructionDone</code>
|-
| <code>Demolition</code>
| The House has reached its demolition phase.
| <code>Demolish</code>
|}

# Add the states to the State Diagram.
# Create a transition from the initial state to <code>Plan</code>.
# Create a transition from <code>Plan</code> to <code>Construction</code> and give it the trigger <code>StartConstruction</code>.
# Create a transition from <code>Construction</code> to <code>Maintenance</code> with the trigger <code>ConstructionDone</code>.
# Create a transition to <code>Demolition</code> with the trigger <code>Demolish</code>.

A '''trigger''' is the named event that takes an object from one state to another. Reuse a trigger name when it represents the same event. For example, a car can use <code>InitiateSale</code> both when it first enters an ownership transaction and when a later owner starts a new transaction.
== Add nested steps with regions ==
Use a '''region''' when one state contains its own internal lifecycle. A region lets you show sub-states without expanding the top-level lifecycle into many separate states.

For example, <code>Construction</code> can contain a region with these sub-states:

# Add a region to <code>Construction</code>.
# Set <code>GroundWork</code> as the region's initial sub-state.
# Add <code>Building</code>.
# Add a transition from <code>GroundWork</code> to <code>Building</code> with the trigger <code>StartBuilding</code>.
# Keep the top-level transition <code>ConstructionDone</code> to move the House from <code>Construction</code> to <code>Maintenance</code>.

When a House enters <code>Construction</code>, it enters the region at <code>GroundWork</code>. The internal trigger <code>StartBuilding</code> then moves it to <code>Building</code>.
== Control transitions with guards ==
A '''guard''' is a domain rule that must be fulfilled before a transition can occur. Add guards when an event alone is not enough to permit a state change.

For example, an ownership transaction can be prevented from closing until the buyer is known. Model the transition to the closed state with a guard that verifies the required information. This makes the rule visible in the lifecycle rather than leaving it implicit.

Use [[Documentation:Learn OCL|OCL]] for expressions that evaluate domain rules and actions in the model.
== Run an action when a state is entered ==
An '''entry action''' is an action performed whenever an object enters a state. Use it for required side effects of entering that state.

For example, when a <code>Car</code> enters <code>InOwnershipTransaction</code>, create and attach a transfer document, then set its seller from the current owner:

<syntaxhighlight lang="ocl">
let doc = CarTransferOwnershipDocument.create in
  self.CarTransferOwnershipDocuments.add(doc);
  doc.Seller = self.CarOwner
</syntaxhighlight>

In this example, <code>self</code> is the Car entering the state. The entry action creates a <code>CarTransferOwnershipDocument</code>, adds it to the Car's transfer-document association, and records the current owner as seller. The buyer can be supplied later; a guard can prevent the sale from closing before that information exists.

Keep entry actions focused on effects that must happen every time the state is entered. Put the condition for whether a transition is allowed in a guard.
== Show the State attribute icon ==
If the class diagram does not show the State attribute as a state attribute, ensure that the default TagExtensions are available.

# Open the TagExtensions dialog from the functions area.
# Ensure these default TagExtensions are present:
#* <code>statediagramsymbol</code>
#* <code>triggermethod</code>
#* <code>constraintclass</code>
# Return to the class diagram and inspect the State attribute. The state-diagram marker is shown as an <code>S</code> icon.

The TagExtensions use WPF XAML definitions. This makes it possible to define another symbol by providing the XAML for the symbol you want to display. Use custom symbols consistently so that diagrams remain understandable to other modelers.
== Design guidance ==
* Name states after stable business situations, such as <code>Maintenance</code>, rather than after a UI operation.
* Name triggers after the event that causes the change, such as <code>StartConstruction</code> or <code>Demolish</code>.
* Use a region when a state has meaningful internal phases, such as <code>GroundWork</code> and <code>Building</code> within <code>Construction</code>.
* Use guards for rules that must hold before leaving or entering a state.
* Use entry actions for side effects that must occur when a state is entered.
* Keep the State Diagram focused on one lifecycle. You can use diagrams as navigation and documentation aids without duplicating model elements; see [[Documentation:Diagrams in Diagrams]].
== Restored from the previous version ==

=== Associations ===

All the classes, that you add also turn into types, but the model type isn't used as an attribute type. It's instead called an [http://wiki.mdriven.net/index.php/Part_8_Link_Objects_association_classes Association.] These can be created just by picking the Association mode tool and dragging between two classes. Noteworthy is that though the class is in the package, it's not really on the diagram, as the last one is just a way to show that class. If we were to switch the diagram back to the other one, you can see that since this shows the same class, it also shows the same attributes as we added many. After adding even more attributes, it will also be visible on the other diagram.

== See also ==
* [[Documentation:OCL Editor, system prototyper and ViewModel]]
* [[Documentation:State value as a string]]
* [[Documentation:Class diagrams]]
* [[Documentation:Diagrams in Diagrams]]
* [[Documentation:Autodiagram]]

[[Category:Diagrams and Documentation]]
[[Category:Intermediate-Friendly]]
[[Category:Priority 50]]
[[Category:State diagrams: modeling lifecycle]]