Getting to Know Sequence Diagrams


by John Zukowski

In last month's column on Generating UML From the NetBeans IDE, you generated a sequence diagram for the newContactActionPerformed() method of the ContactList class of the ABook project. This month's column explains what the diagram shows.

First, here's the diagram again:

Sequence Diagram Figure 1. Sequence Diagram
Click here for a larger image

And here is the source code behind the method:

    private void newContactActionPerformed(ActionEvent evt) {
        contactEditor.clear();
        contactEditor.setEditable(true);
        EventQueue.invokeLater(new Runnable() {
            public void run() {
                contactEditor.setVisible(true);
            }
        });
    }

Going back to the original system design, this sequence diagram maps to what would have been the New Contact use case. It essentially says to clear and show the contact editor, with a slight nuance of automatic documentation of anonymous inner classes. Normally, those would not go in the original design, but because the diagram was reverse engineered, you get the invokeLater in there.

Although this is a simple diagram, it includes all the different pieces to provide an explanation. Overall, the diagram represents the sequence of messages that the ContactList class must execute to perform the New Contact operation.

Along the top of the diagram, you see the set of objects that are necessary to perform the task.

Sequence Figure 2. Sequence
Click here for a larger image

Each of these boxes represents an object or process involved. The doubling of EventQueue in the list seems to be an error in the automatic generation. Because there are no boxes on the vertical line below the first EventQueue, the whole line should not be included. The ActionEvent is also without any boxes on its vertical line, so it too could be removed. However, because of the need for it as an argument to the actionPerformed() method, it appears here for completeness.

Normally, you see only the type of object involved in the box at the top, as in : EventQueue, shown in the last box. However, you can also name the object by including a name before the colon, as in evt: ActionEvent. The name helps in explaining the diagram to another user.

The horizontal arrows in the sequence diagram represent the messages exchanged between the involved objects. They are shown in a time sequence, so an arrow higher up the sequence diagram would happen earlier in the execution of events of the use case.

Sequence Message Figure 3. Sequence Message

So for this set of two messages, clear happens before set editable.

Had this been an original sequence diagram, and not one that was reverse engineered, the first message would have more likely been the word clear alone and not shown like a method name. And the second would have been something like make editable.

Although all the messages of this sequence diagram start at the object on the far left and immediately return, it is not uncommon for a sequence diagram to include messages between other objects.

The invokeLater message partially shows another involved object, but Runnable doesn't quite get the diagram right.It shows the anonymous class usage as an int Unnamed argument of invokeLater. Because Runnable is not involved with messaging of the original object on the far left, it does not have to be shown at the very top. Instead, try limiting its visibility to the usage area. The auto generator also hides the setVisible call.

    contactEditor.setVisible(true); 

But because the call is inside the invokeLater call due to the Swing threading requirements, the diagram is technically correct, though not as one would do from the original use case.

There really is not much to a sequence diagram: just the objects involved and a timed sequence of the messages sent between them. Auto generation isn't always perfect, but when you're trying to get a handle on a large-scale project without sufficient documentation, it certainly provides a good starting point from which to understand the system.

For some pointers on creating your own diagrams, see an Introduction to UML 2 Sequence Diagrams by Scott Ambler.

Comments:

Post a Comment:
Comments are closed for this entry.
About

Java Technology Fundamentals are now covered as part of the Core Java Technology Tech Tips. Please go there for more tech tips.

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today