State diagrams are handy when you want to show the changes to a single object's state during its lifecycle. State changes can be simple differences in member variables or more complex things such as polling for a response from an external source.
In BandSpy, the Performance class has a lifecycle that's worth documenting with a state diagram. When a new Performance object is created, it must contact the venue reservation system and await a confirmation. If the response from the venue system says the reservation is good, the performance must be permanently stored. If the reservation is not accepted, the Performance object should inform the System and then be destroyed. In Figure 2-13 a state diagram shows the various states for the object.
The solid circle shows the start of the object's lifecycle, and arrows indicate transitions from one state to another. After the new Performance is initialized and dispatches a message to the venue system, the awaiting confirmation state polls until it receives a message back from the venue system.
One new symbol in Figure 2-13 is a note indicating that the awaiting confirmation state should wait one minute to receive a reply from the venue system. A note can be used in any UML diagram where you want to add extra information such as this.