Building Protocol State Machines

UML2 When you want to show the sequence of events an object reacts to—and the resulting behavior—you use the UML notation that creates behavioral state diagrams (also known as machines): Such state diagrams have event/action pairs, entry actions, exit actions, and do activities. Most of your state diagrams use these features; in effect, they are behavioral state machines.

Sometimes, however, you just want to show a specified sequence of events that your object responds to—and when it can respond—without having to show its behavior. Such a specified sequence is called an event protocol. In UML 2, you can show event protocols by diagramming protocol state machines. These differ from behavioral state machines and have special uses.

Normally we recommend using regular state diagrams to show internal sequences of behavior for all objects of a class. Sometimes, however, you want to show a complex protocol (set of rules governing communication) when using an interface for a class. For example, when you are designing classes that access a database for your application you need to use common operations like open, close and query a database. But, these operations must be called in the right order. You cannot query the database before you open it.

One solution to designing a simple database access class is to develop a DatabaseAccessor class with a DBaccess interface as shown in Figure 18-11. But, the DBaccess interface has a complex protocol that governs its use because of the rules governing communication between any other object and the DatabaseAccessor class implementing the DBaccess interface. To use the interface properly, you have to open the database and then set up a query. You can put these rules in a state diagram to indicate the protocol that must be followed when using the interface.

Figure 18-11: Class diagram with DBaccess interface.

Regular state diagrams don’t help you with interfaces because interfaces don’t describe behavior implementation they just declare what operations the class must perform. It’s up to the class to specify the implementation of an interface. On the other hand a protocol state machine enables you to declare what operations can happen and the order they can happen without having to say anything about behavior implementation.

Figure 18-11 shows the DBaccess interface attached to the DatabaseAccessor class; the DatabaseAccessor class must conform to the operation sequence (that is, the protocol) of the DBaccess interface: The open, close, query, fetch, cancel, create, and kill operations must be implemented in the order specified by the DBaccess interface’s protocol (shown in Figure 18-12).

Figure 18-12: DBaccessor protocol state machine.

You draw a protocol state machine in much the same way you draw any other state machine. Remember, however, to follow a few special rules:

States can have names but can’t show entry actions, exit actions, internal actions, or do activities.
Transitions show operations but not actions or send events (as regular state diagrams can).
Transitions can have preconditions and postconditions shown in square brackets [], as in the following example:
```
 [queryStatement <> null] query / [comArea set] 
```
- A precondition states what must be true before the object can transition from one state to another. In this example, when an object that conforms to the DBaccessor interface receives the query operation, the queryStatement attribute is checked to see whether it’s null. If the object is in the Opened state, and the queryStatement isn’t null then the object transitions to the Queried state.
- A postcondition states what must be true once the object completes its transition and is now in a new state. In this example, when an object that conforms to the DBaccessor interface makes a successful transition to the Queried state, that means the postcondition must now be true—the comArea is set.

Avoiding data-flow diagrams

Many developers are used to thinking of the flow of data moving from function to function—so when they try to draw a state diagram, what they get is actually a good old-fashioned data-flow diagram: They draw lines between states that show data flowing from one to another. But a state is not some function that executes—and a data-flow diagram is not a state diagram. A data-flow diagram in disguise doesn’t help you think of the life cycle of your objects.

To avoid this misuse of state diagrams, you have to be aware of two kinds of states:

Do-forever state: Left to itself, this type of state performs its activity forever. It only stops doing its behavior when an event interrupts it, causing a transition to another state. The WaitForCustomer state, for example, is willing to wait forever. Only when it receives the customer event will the object make a transition to the ObtainingTransactions state.
Do-until states: This type of state performs its activity until the activity is complete; then it makes an automatic transition to another state. You can easily find do-until states by finding transitions that have no event on the line-with-an-arrow that links pairs of states. The GenerateOverDueNotice state, for example, simply generates a notice and then automatically makes the transition to a final state. The GenerateOverDue-Notice does not have to wait for an event to cause a transition.

You can check your state diagram to see what you’re building. The key is the proper checking of how many do-forever and do-until states exist in your diagram:

Count the number of do-forever states.

These are the real stuff of state diagrams.
Count the number of do-until states.

Look for those automatic transitions without event names; they’re a dead giveaway.
Evaluate whether the diagram you’re building is really a state diagram.

If the majority of states in your state diagram (around 70% or more) are do-until states, you probably have a data-flow diagram. On the other hand, if the majority of states in your diagram are do-forever states, then you have a solid, flow-of- control state diagram.

When you find your state diagram is really a data-flow-type diagram, then consider using an activity diagram instead.

You draw your protocol state machine as a group of substates within one large frame, like the frames for sequence diagrams we show you in Chapter 12.
You must name the protocol state machine as such; place the keyword protocol in curly brackets {} next to the name.

The diagram in Figure 18-12 shows a protocol state machine for the DBaccessor interface. Any class conforming to the DBaccess interface must implement the protocol state machine. You can show the implementation of the protocol state machine as a regular state machine with all the actions and activity behaviors thrown in. That way it’s clear to other developers how you will implement the protocol for a specific class in your design.

Warning State diagrams aren’t meant to show the flow of data from one process step to another. Instead, they’re supposed to show where the flow of control goes when some behavior happens. Don’t let your state diagram mutate into a data-flow diagram. We’ve included a handy sidebar to help you hold the line.