Cool Tool: “Quick Sequence Diagram Editor”

UML is painful and tedious. Or I meant to say that creating UML diagrams is painful and tedious. Mostly because the tools are graphical and require some level of ability to layout a 2-d graphic that borders on the artistic. (I always thought UML looked like some strange Cubist’s concoction.) I don’t know about you but I am no graphic designer, sure I’ve got a few UI’s under my belt but by no means would I put a title with the word “graphics” or “ui specialist” in it on my resume. So why do all the tools seem to require that their users be artistic wizards to model their software? I don’t know, but I do know at least one decent chap who didn’t agree with that viewpoint, at least for Sequence Diagrams.

“Quick Sequence Diagram Editor” is an open-source Java-based UML Sequence Design tool that uses a DSL (oooooo!) to generate UML diagrams that can be exported to a variety of formats. What I like best about this tool is not just that I can concentrate on describing the application in a way I am comfortable with (I am a programmer!) but that it also generates the diagram in a preview window as you type. Once you get used to the language it feels very natural to describe the flow without getting bogged down into the messy details of layout.

You can download the tool for free from SourceForge.net (http://sdedit.sf.net). As of the time of writing this the latest version was 3.0.5 and since it’s a self-contained executable there’s nothing to install. Just download and run! The only prerequisite is that you have a recent JVM installed on your workstation.

To show how simple the tool is and how terse the language is I’ll replicate a simple sequence diagram from Agile Modeling by Scott Ambler. _{Visit Mr. Ambler’s website, and read his regular contributions on Agile development in each(?) issue of Dr. Dobbs. (You do subscribe to Dr. Dobb’s don’t you?)}

I’ve taken one of the simplest examples that is a copy of a barely-legible hand-drawn sequence diagram and reproduced it in the Sequence Diagram Editor tool. This is taken from the UML 2 Sequence Diagrams article on Mr. Ambler’s site.

Archive note: The original sequence diagram image from the WordPress export is unavailable in this archive.

That is much more legible now. And, the code is pretty straight forward, although if you’ve checked out the linked source article you’ll see that the diagram isn’t ‘exact’. This is where any computer tool will always have difficulty, tradeoffs must be made and declarations must be explicit. I won’t call them limitations but instead realities of how the tool implements the UML Sequence Diagram specification. Like anything else written by hand you can fudge the rules a little bit and get away with some things just because we can figure out what you meant pretty easily. But as programmers we all know that what looked fine when it was sketched on the whiteboard isn’t exactly how it gets implemented.

Some of the changes that had to be made, is that Actor types in SDE can only send and receive one-way messages. Another is that one-way messages on Processes start new lifelines on the receiving process. Other than that I think it’s pretty darn close for a 5 minute exercise. Now let’s break down what we’re looking at codewise.

Here we’re declaring the Actors and Processes that will participate in the SD. The syntax is like NAME:TYPE[attributes]. When we get to the body it will become more apparent. So we have two Actors, these will be represented as stick-figures with their names displayed beneath them. Then we have a single Process that is a System. The [a] attribute means that the Process will be treated as anonymous, the name will not be displayed in the diagram because it is irrelevant.

Applicant:Actor
Registrar:Actor
S:System[a]

Now we’re specifying the interactions between the Actors and Processes. The syntax is like CALLER:CALLEE.action. The callee is optional if the action is reflexive; the caller and callee are the same. Although there can be more done to specify responses and allot of other neat stuff this is enough to be productive.

As you can probably see, the code isn’t directly mapping to methods, just describing interactions. So when you see Registrar:requests forms all we are saying is the Registrar Actor needs to perform some action and return immediately. But we aren’t bogged down in the syntax of the whatever language we’ll actually be developing in. Also, when we see S:Registrar.receipt, we are telling the S Process to invoke some action on the Registrar and return immediately.

Applicant:Registrar.application form
Registrar:requests forms
Registrar:S.create student
S:Displays UI 89-create statement
Registrar:S.input name, address & phone number
S:check to see if student exists
S:verify person is on eligible applicant list
S:add applicant to DB
S:calculate enrollment fees
S:display UI 15-fee summary
Registrar:Applicant.help student to enroll in semesters
Registrar:Applicant.request fees
Applicant:Registrar.payment
Registrar:S.payment
S:Registrar.receipt
Registrar:Applicant.receipt

The developer of SDE, Markus Strauch, was also kind enough to store the diagram descriptions as XML files only with a SDX suffix. So they are easy to version inside your source control repository or edit outside of the SDE editor. I even configured my system to open the SDE tool automatically when I double-click on an SDX file.

I hope that was enough to whet your interest in the Sequence Diagram Editor tool and to make Sequence Diagram generation a little less foreboding.