Generating UML and Sequence Diagrams
by Phil Crow |

Using UML::Sequence

Now that you understand how to read a sequence diagram, I can show you how to make them without mouse-driven drawing tools.

Making diagrams with UML::Sequence is a three-step process:

1. Create a program or a text file.
2. Use genericseq.pl to create an XML description of the diagram.
3. Use a rendering script to turn the XML into an image file.

If the image is in the wrong format for your purposes, you might need an extra step to convert to another format.

Running Perl Programs

Here is how I generated Figure 1 above by running the driver program. If your program is in Perl, you can use this approach (see the next subsection for Java programs).

First, create a file listing the subs you want to see in the diagram:

    DiePair::new

    DiePair::roll

    Die::new

    Die::roll

I called this file roller.methods to correspond to the script's name, roller. When you make your method list, remember that sequence diagrams are visual space hogs, so pick a short list of the most important methods.

Then, run the program through the genericseq.pl script:

$ genericseq.pl UML::Sequence::PerlSeq roller.methods roller > roller.xml

UML::Sequence::PerlSeq uses the Perl debugger's hooks to profile the code as it runs, watching for the methods listed in roller.methods. The result is an XML file describing the calls that actually happened during this run.

To turn this into a picture, use one of the image scripts:

$ seq2svg.pl roller.xml > roller.svg

Obviously, seq2svg.pl makes SVG images. If you have no way to view those, get Firefox 1.5, use a tool like the batik rasterizer, or use seq2rast.pl, which makes PNG images directly using the GD module.

If you want diagrams like Figure 2, use UML::Sequence::PerlOOSeq in place of UML::Sequence::PerlSeq when you run genericseq.pl.

Running Java Programs

I wrote UML::Sequence while working as a Java programmer, so I made it work on Java (at least sometimes it works). The process is similar to the above. First, make a methods file:

    ALL

    Roller

    DiePair

    Die

Here I use ALL to mean all methods from the following classes. You can also list full signatures (but they have to be full, valid, and expressed in the internal signature format as if generated by javap).

Then run genericseq.pl with UML::Sequence::JavaSeq in place of UML::Sequence::PerlSeq. Of course, this requires you to have a Java development environment on your machine. In particular, it must be able to find tools.jar, which provides the debugger hooks necessary to watch the calls.

Produce the image from the resulting XML file as shown earlier for Perl programs.

Text File Input

While I pat myself on the back every time I make a sequence diagram of a running program, that's not always (or even usually) practical. For instance, you might want to show the boss what you have planned for code you haven't written yet. Alternately, you might have a program that is so complex that no amount of tweaking the methods file will restrict the diagram enough to make it useful.

In these cases, there is a small text language you can use to specify the diagram. It is based on indentation and uses dot notation for method names. Here is a sample:

At Home.Wash Car

    Garage.retrieve bucket

    Kitchen.prepare bucket

        Kitchen.pour soap in bucket

        Kitchen.fill bucket

    Garage.get sponge

    Garage.open door

    Driveway.apply soapy water

    Driveway.rinse

    Driveway.empty bucket

    Garage.close door

    Garage.replace sponge

    Garage.replace bucket

Each line will become an arrow in the final diagram (except the first line). Indentation indicates the call depth. The "class" name comes before the dot and the "method" name after it.

There is no need for a methods file in this case, because presumably you didn't bother to type things you didn't care about. You may go directly to running genericseq.pl:

$ genericseq.pl UML::Sequence::SimpleSeq inputfile > wash.xml

Once you have the XML file, render it as before.

Getting Fancy

As I mentioned earlier, Dean Arnold recently added lots of cool features to amaze and impress your bosses and/or clients. In particular, he expanded the legal syntax for text outlines. Here is his sample of car washing with the new features:

AtHome.Wash Car

        /* the bucket is in the garage */

    Garage.retrieve bucket

    Kitchen.prepare bucket

        Kitchen.pour soap in bucket

        Kitchen.fill bucket

    Garage.get sponge

    Garage.checkDoor

            -> clickDoorOpener

        [ ifDoorClosed ] Garage.open door

    * Driveway.apply soapy water

    ! Driveway.rinse

    Driveway.empty bucket

    Garage.close door

    Garage.replace sponge

    Garage.replace bucket

There are several new features here:

• You can include UML annotations by using C-style comments, as shown on the second line of the example. Each annotation attaches to the following line as a footnote (or tooltip, if you install a third-party open source library).
• There is a -> in front of clickDoorOpener. This becomes an asynchronous message arrow. When -> comes between a method and additional text, it indicates that a regular method is returning the value on the righthand side of the arrow. The return appears as a dashed arrow from the called activation back to the caller.
• ifDoorClosed is in brackets, which mark a conditional in UML. These appear in the diagram in front of the method name.
• There is a star in front of Driveway.apply, which indicates a loop construct in UML. (UML people call this iteration.)
• There is an exclamation point in front of Driveway.rinse, indicating urgency.

In addition to these changes to the outline syntax, both seq2svg.pl and seq2rast.pl now support options to control appearance (including colors) and to generate HTML imagemaps for raster versions of the diagrams. The imagemaps hyperlink diagram elements--columns header and method call names--to supporting documents. For example, clicking on the Garage header will open Garage.html, while clicking on checkDoor will also open Garage.html, but at the #checkDoor anchor.

Summary

UML Sequence diagrams are a great way to see how function or method calls (or network messages) flow through a multi-module application, whether it is object-oriented or not. Using UML::Sequence and its helper scripts, you can make those diagrams without having to point and click in a drawing program.

References

The imagemapped HTML version of car washing is viewable online.

To read more about UML diagrams, check out the aptly named UML Distilled, by Martin Fowler, available from your favorite bookseller.

I recommend Walter Zorn's JavaScript, DHTML tooltips package to display embedded annotations.

Batik is an Apache project for managing and viewing SVG.

Prev  [1] [2]