10.3 Visualizing Domain Dynamics

As the number of communicating state machines increases, we need a way to visualize the big picture of the domain dynamics. We use interaction diagrams of two kinds, a collaboration diagram that describes the communications between state machine instances without explicit regard to time, and sequence diagrams that describe objects in specific states over time.

Experienced modelers sketch collaboration and sequence diagrams before formalizing state machines to help organize the dynamics in the domain. Once the state machines have been constructed, the collaboration diagrams can be regenerated from the state machines themselves. The result could be sufficiently horrifying to cause reconstruction of the state machines, or, of course, all could be well.

Similarly, various sequence diagrams can be generated from actual execution traces. By establishing a set of initial states and executing the models from the state machines, an execution trace can be produced. The graphic form of this trace is a sequence diagram. Again, the resulting sequence diagram may be more complex or less regular than desired, and this will cause iteration over the state machines.

This is as it should be: We plan our overall domain dynamics, build the individual state machines according to the plan, evaluate the domain dynamics, and modify them as necessary.

10.3.1 Collaboration Diagrams

The work of creating and processing an Order sends signals to and receives signals from the Credit Card Charge and Shipment state machines. A collaboration diagram shows signal communication across links between objects and external entities representing actors.

The collaboration diagram of Figure 10.7 shows overall collaboration in a domain as collaborations between arbitrary instances of classes, where the state machine for each object is represented by a box labeled with the name of an arbitrary instance of classes and their corresponding state machine instances.

Figure 10.7. Collaboration Diagram Showing Order, Charge, and Shipment

The UML syntax for an instance is:

<instance name > : <Class Name>

For example:

Sarzak : Dog

In this case, as in many others, we are concerned with an arbitrary and unspecified object, or, if you prefer, an anonymous object:

: Dog

UML allows a collaboration diagram to show synchronous method invocations in addition to signals. Because our concern here is communicating state machines, Executable UML suppresses method invocations.

UML uses collaboration diagrams in the context of a single scenario. We have found it valuable to show all the signals between objects, the better to visualize domain dynamics.

It is possible, therefore, to show communication between one instance of an class and another in a particular pattern of execution. The boxes are labeled to distinguish one instance from another.

Each external entity that can generate or receive signals is depicted by a box stereotyped «external entity». Alternatively, an actor symbol suffices.

A collaboration between objects and external entities is shown by one (or more) lines between the participants. A signal sent by one object or external entity and received by another is represented by an arrow^[1] from the sender to the receiver. The arrow is annotated with the signal label, name, and the signal parameters. Multiple signals may be associated with a single arrow.

^[1] UML 1.3 used a single-fleched arrow (sometimes called a half-arrow). It means the same thing.

By convention, we omit signals that are generated and received by the same state machine. These details can be seen on the state machine itself.

10.3.2 Concept of a Execution Trace

Definition: An execution trace is a sequence of procedures and signals that occurs in response to the arrival of a particular signal when the objects are in specific states and their attributes have specific values.

An execution trace may include activity outside the system: Somewhere along the trace, a signal may be sent to an actor causing the actor to execute some external activity. If the actor responds with a signal, it, as well as the external activity, is considered to be part of the execution trace.

As with use cases, it is helpful sometimes to distinguish between execution traces that are entirely under the control of the system (a single-system interaction), and those that can cross the system boundary (a boundary-crossing interaction).

If a procedure along the execution trace generates more than one signal, the execution trace splits so that two or more legs of the same execution trace are active at the same time.

The definition of the execution trace ("that occurs in response to the arrival of a particular signal when the system is in a particular state") excludes the possibility of one leg or another being executed. Because the system is in a known state, at execution time only one choice can be selected.

Each leg of the execution trace eventually terminates. This can happen in one of two ways:

• A state machine enters a state whose procedure sends no more signals. The leg then terminates in this state, and no subsequent activity occurs along the leg.

• A state machine enters a state whose procedure sends a signal to an actor but the actor does not respond. In this case, the activity terminates outside the system.

When a trace enters a state machine that manages contention, the trace may suspend waiting until the resource becomes free. You may choose to regard this as termination of the trace, and begin a new trace for when the resource becomes free.

10.3.3 Sequencing Signals on a Collaboration Diagram

Signals on a collaboration diagram may be numbered to show sequence, as shown in Figure 10.8. The "numbering" scheme forms a tree: 7.1. and 7.2 follow 6, and are concurrent, while 7.2.1 and 7.2.2 follow 7.2 concurrently.

Figure 10.8. Sequenced Collaboration Diagram

A sequence diagram provides a more graphic view, as discussed in the next section.

10.3.4 Sequence Diagram

A sequence diagram is a graphical representation of the succession of signals and procedure activations that participate in a particular execution trace.

Figure 10.9 shows a sequence diagram for a successful single-item ordering scenario.

Figure 10.9. Sequence Diagram for Single-Item Ordering Scenario

Each column, represented by a dotted line, is an object lifeline. It represents a single object over time. The label at the top of each object lifeline identifies each instance and its class. When only one instance of a class is used in a sequence diagram, we can omit the instance name.

Each object appears separately as the string of states it occupies as it progresses through the scenario; these activations are connected by the object's lifeline.

Definition: An activation is the execution of a single procedure in a state machine instance at some time.

Sources of external signals (actors, such as the customer, the credit card company, the shipping clerk, and the delivery company) are shown as their own columns on the diagram.

The horizontal lines represent signals from one object to another. Each line is labeled with the name of the signal. (To reduce clutter, we do not show lines for the invocation of data-accessor functions of other objects.)

The diagram is laid out along a relative time axis, with the procedures placed on the chart in the order (top to bottom, or vice versa) in which they occur.

Object creation is shown by the presence of the lifeline after the creation signal is received.

Object deletion is shown with a big X at the end of the lifeline, as shown in Figure 10.10.

Figure 10.10. Sequence Diagram Showing Object Creation and Deletion

10.3.5 Applicability

Sequence diagrams are most useful as a tool for understanding the interactions between specific objects in a particular context. They are useful to understand some specific scenarios, but not for every possible situation.

After the initial sketches to visualize domain dynamics, manually drawing these beasts and ensuring they're consistent is a pain; it's better to derive them from simulations.

Sequence diagrams are also useful to model a particular instance of a use case, with specific values for attributes, starting and ending in specific states. The sequence diagram thus models a particular test case. We take up this topic in Chapter 15: Domain Verification.

Similarly, manually drawing collaboration diagrams is useful to model the desired layering of the state machines, but the collaboration diagram should be generated once the state machines are complete enough to provide useful information.