Summary

Quick Sequence Diagram Editor is a tool for creating UML sequence diagrams from textual descriptions of objects and messages.
It supports threads, actors, constructors, destructors, notes and fragments.
The aim of the tool is to save you from lots of the stupid work that WYSIWYG applications require, by trading off not too much flexibility. It beats these applications by far when it comes to insert or remove objects and messages. This can be done by just inserting or removing a line of text, the tool will do all the rest.

Features

Among its features are:

Examples

  1. Breadth first search
  2. Example illustrating levels and mnemonics
  3. Ticket order
  4. SSH 2 (by courtesy of Carlos Duarte)
  5. Webserver

How to enter text

Use the text area at the bottom of the window to specify your objects and messages. The object section must be separated from the message section by an empty line.
Should there be a (syntax) error in your text, the first line where such an error occurs is highlighted. And there will be a description of the error at the bottom of the window.
'.' and ':' will not be interpreted as delimiters, if they are preceded by a '\'.

Objects

For each object you want to appear in your sequence diagram, type
<name>:<Type>[<flags>] "<label>"
      
or
/<name>:<Type>[<flags>] "<label>"
      
into the text area. This represents an instance of class <Type>, named <name> which will be shown as a lifeline. <name>. The [<flags>] and "<label>" parts are optional:
If you specify a quoted label, it will be used to label the object with, otherwise the object's label will be derived from the name and the type.

Invisible objects

If <name> is prefixed with a '/', the lifeline will be invisible until the instance is created by a 'new' message to <name> (see below).

Flags

An object declaration can be followed by a sequence of <flags> between square brackets. Four flags (a,p,r,x) are supported:

a-nonymous

The object is anonymous, so the name (which must still be there in order to be able to reference the lifeline) will not appear on the diagram, just a colon followed by the type. This flag is useless if a <label> is specified.

r-ole

The label of the lifeline will not be underlined.

p-rocess

The object behaves like an actor (see below), but it is represented by a box with a thick border, not by a figure.

e-external

(Only) a process can be declared to be external, which means that it represents an external entity with the ability to send "found" messages, but not appearing on the diagram. Messages originating from an external process are represented by arrows starting with filled circles.

x-auto-destruction

The object is destroyed when it has sent its last answer, denoted by a cross below its lifeline. One might interpret this as automatic destruction of non-persistent objects by a garbage collector.
There are other flags, relevant for multithreading .

Actors

If <Type> is 'Actor', the lifeline belongs to an actor. An actor is always active and sends asynchronous messages. It cannot send messages to itself. Also, it cannot receive answers (see below). In order to send an answer to an actor, one must use an explicit message.

Messages

The lines in the message section have the following format:
<caller>[<s>]:<answer>=<callee>[m].<message> [{<properties>}]
      
<caller> is the name of an object that has been declared in the object section. It is either the first one to send a message or has received a message before and not yet answered to it. Otherwise it is not active and cannot send a message.
[<s>] is optional and refines the specification of the caller object.
If <s> is a number, it denotes the 'level' of the caller: A caller may have received k messages to which it has yet to answer. Then <s> can range from 0 to k-1. Before <caller> sends the message, it will answer to the <s> most recent messages.
If <s> is not a number, it is a mnemonic. A mnemonic can be defined for a callee (by using the optional [<m>] part). If <s> is a mnemonic that has been defined for the object <caller> and <caller> is still active, <caller>[<s>] references this object.
<answer>= is optional and <answer> is simply a string representing the answer to the message. This string is used as a label of a dashed arrow from the <callee> to the <caller> lifeline. Note that there cannot be answers to messages sent by and to actors.
<callee>. is optional and <callee> denotes the object that receives the message represented by the string <message>, which is used as a label of an arrow from <caller> to <callee>. If no <callee> is specified, <message> is interpreted as an description of a simple action (not another invocation of a method/procedure) performed by the caller.
[<m>] is optional and <m> is a mnemonic containing at least one character that is not a digit. As long as the callee is active, it can be referenced as a caller by its name followed by [<m>].
<message> can consist of more than one line, separated by (a literal) \n.
<properties>, including the enclosing curly braces, is an optional string consisting of pairs of the format name=value, separated by commas. These will only be interpreted if "Use dynamic message properties" is checked in the "Message" section of the configuration. (See below)

Constructors

Messages that are named ' new ' or that start with ' new( ' are special messages. They can be sent only once to objects that were declared with a '/' before their names. On receiving a 'new' message, the object will be created and its lifeline will become visible.

Destructors

Messages that are named ' destroy ' or that start with ' destroy( ' are also special. They can only be sent to an object that is not active. After receiving the destroy-message, the object may become active for the last time and, for example, send some destroy messages to other objects. But after this last activity ended, the object is destroyed (denoted by a cross below its lifeline) and cannot be reclaimed.

Actor messages

Actors can only send and receive asynchronous messages that return immediately. An asynchronous message will be generated that is sent back to the actor when the activity that was started by his message is finished.
If an actor sends a message to an ordinary object, all activities will be finished before. An actor should typically send the first message of the diagram, but this is not necessary, sequences without even a single actor are still supported.

Broadcast messages

See multithreading .

Dynamic properties

Dynamic message properties will only be interpreted when "Use dynamic message properties" is checked in the "Messages" section of the configuration.
Currently, there is only one property supported: "colour". For instance, if you append "{colour=blue}" to the text of a message, the arrow representing this message will be blue.

Annotations

Diagrams can be annotated in three different ways.

Source text comments

First, you may insert lines starting with a '#' in the textual description. These lines serve as comments and will not be interpreted, unless they start with '#!', which indicates an active comment.

Title

A line of the form
#![<title>]
          
specifies a diagram title. If it is present, the diagram will be surrounded by a frame, with the title written at the top left corner of the frame.

Description

A sequence of lines of the form
#!>>
#!A paragraph
#!of text describing
#!what is going on.
#!<<
is interpreted as text that will be written above the diagram.

Fragments

Second, a sequence of messages can be declared to be a fragment of the diagram. A fragment is represented by a frame surrounding those messages. It has a type (for example: alt, cond, or opt), appearing in the top-left corner, and a text, appearing in square brackets at the top of the frame. The text typically represents a condition. For example:
[c:<type> <text>]
  foo:bar.message_1
  foo:bar.message_2
  ...
  foo:bar.message_n
[/c]
Fragments can be slightly abused: if you write [c <text>] (without the colon), all of the text will appear in the small box in the top left corner.
Fragments may contain sections. To open a new section, insert a line of the form
--some text
The effect is that a dashed line is drawn from the left to the right end of the current fragment frame, with "some text" being written below this line.

Notes

Third, there are notes. These appear in a box resembling a piece of paper that is arranged to the right of a lifeline. Notes are a part of the message section. The top of the box is where an arrow belonging to a message specified at the same position in the text would appear. The syntax is similar to a here-document delimited by an asterisk followed by a number (without the <<).
*<num> <name>
multi-
line
note
*<num>
<name> is the name of the lifeline such that the note is to the right of it. <num> is the unique number identifying the note. You can refer to this number anywhere in the code - even before the note - in order to associate the note to messages or lifelines. For this you add one of the following prefixes to a message or the name of a lifeline: Example:
*5 foo
  foo calls bar's wait method
*5
*6 foo
  foo is waiting for bar
*6
*7 foo
  bar is ready
*7

(5,7)foo:ready=bar.wait()
(6)foo
  bar:do something
(6)foo
bar:do something more
        
If you use a "+" instead of a "*", the note box will consume as much vertical space as it needs and there will not be any message arrow or other note box beside it. When using "*", the note box will consume its own vertical space only if it is followed by a message arrow that is adjacent to one its both neighbour lifelines.
There are no direct associations between notes and objects. If one wishes to note something concerning an object or actor, she or he should specify a note belonging to the corresponding lifeline before any message has been specified.

Links

A single-lined note that starts with "link:" is interpreted as a link to another sequence diagram. The part of the line that follows is a URI (see RFC 3986 ) of an sd file. If the URI is relative, it is resolved against the location of the file of the current diagram. Example:
#BEGIN of file "a.sd"
a:A

*1 a
link:b.sd
*1 a
#END
          
#BEGIN of file "b.sd",
#located in the same directory as "a.sd"
b:B
#END
          
When the note in the "a.sd" diagram is clicked, "b.sd" will be opened.
There is a problem when the characters behind "link:" contain spaces. This is a bad URI syntax. Spaces must be replaced by "%20". Especially on Windows, where directory names with spaces are far from being exceptional - for instance "Program Files" - one may easily run into this problem when trying to specify absolute paths.
Those characters are interpreted as a URI for the sake of platform independence. This means that even on the Windows platform, "/" is to be used as a separator in a path to a file. Absolute path names should start with "file:/".

Automatic completion

When you have entered a (non-empty) prefix of a name of an object, you can press the TAB key (like in a UNIX shell) or Ctrl-Shift-Space (like in some IDEs) for completing the name automatically or for browsing through (via successive keystrokes) all object names with that prefix.
If there is whitespace or a delimiter (one of {'>', ':', '='}) to the left of the cursor, the TAB key will behave normally, so you can still use it for indentations.

Automatic redrawing

By default, a new diagram is generated from your text almost as soon as the text changes, even if this change in text would leave the diagram unchanged.
This is a suitable behaviour for a standalone PC that is reasonably well equipped. In some situtations, however, especially when Quick Sequence Diagram Editor acts as a remote X client, it can be a nuisance. So you may disable automatic redrawing in the preferences dialog. When it is disabled, only a syntax/semantic check is performed. To see a new diagram, you must click "Redraw" or type F5.
The time that passes between a change of text and a redrawing or a syntax/semantic check can also be adjusted in the configuration dialog (see "Redraw/syntax check delay"). It may be desirable to have two different delays (one for redrawing, one for the check), but this feature is not (yet?) implemented.

Supplementary help pages

Please also take a look at these supplementary help pages:

Preferences

There are some types of preferences, which can all be adjusted in the tabs of a single preferences dialog.

Filtering

The contents of the text area can be replaced by the output of a command that you have entered after clicking the filter icon. If no text is selected, the whole of the text is used as the command's input and replaced by its output, otherwise the replacement is applied to the selection only.
The field where the command is entered can be left by clicking the ESC key. This may also terminate a command that has been entered and has not yet finished. There is a history of commands you have already entered in this session, through which you can browse using the cursor up and cursor down key.
This feature can be used by people who are too lazy to use the file dialog in order to load a file. For example: cat ~/my_diagram.sd. It can also be used for replacing patterns: sed s/foo/bar/g. Or to remove lines that contain comments: grep -v # ... Of course cat, sed and grep must be available on the system then.

HTML map files

If an image of a sequence diagram is used on a website, if might be useful to be able to navigate to a certain target if a head of a lifeline is clicked. For this purpose, a HTML map file can be generated for the diagram that is currently being displayed (see the Extras menu).
The map file contains just a <map> tag, comprising <area> tags for each object of the diagram. The <area> tag's href attribute equals the name of the object, or, if the declaration of the object is followed by '#!href="<url>"' , an URL of your choice. Example:
object:Class #!href="../foo.html#bar"
      

Javadoc taglet

Quick Sequence Diagram Editor helps you to add sequence diagrams to your Java documentation (javadoc). Pass these two parameters to the javadoc tool:
-tagletpath <CLASSPATH> -taglet net.sf.sdedit.taglet.SequenceTaglet
<CLASSPATH> is the location of the Quick Sequence Editor class files, that can be the jar file or the bin directory. If you are using the exe file, there is no such location, sorry.
Now javadoc will interpret the contents of @sequence.diagram tags as textual descriptions of sequence diagrams. It will create PNG images from them and they will be shown on the HTML pages generated by the standard doclet. The images are stored in a directory that is a child of the javadoc target directory.
When @sequence.diagram is followed by a quoted string, this string will be used as a headline for the sequence diagram. @sequence.diagram can appear in a package description and anywhere in a class definition.
Example:
/**
  This is the description of the EnigmaDecoder.
  ...
 
  @author Alan Turing
  @sequence.diagram "Instantiation of the EnigmaDecoder"
  a:A
  /decoder:EnigmaDecoder
 
  a:decoder.new
  @deprecated
    */
Beware of code-formatters that join lines in javadoc comments. This might result in syntactically wrong sequence diagram descriptions.

Command line

sdedit can be started from within a shell. Let <start-command> be the start command, e. g. java -jar sdedit-3.0.jar, sdedit-3.0.exe, sdedit.bat, or ./sdedit.sh. Users of the zip distributions who are familiar with Java might start sdedit typing something like java -classpath bin:lib/.... Note that ant run or ant start will not work as a <start-command>.
The point of running sdedit from within a shell is to automatically create images from diagram files.
In order to do this, specify the name of the output file to be created using the -o option. The type of the file to be created (pdf, ps, svg, png, ...) is to be named as the value of the -t option. The paper format (one of {A0, ..., A7}) and orientation (one of {Portrait,Landscape}) can be configured using the -f and -r option, respectively. Appending -h as an option shows a list of long options that can be used for configuring the diagram.
Examples:
If options are used, exactly one input file must be defined. When no option is used, arbitrarily many input files can be specified, which will be loaded into separate tabs then.

RT diagram server

Diagram specifications can be transmitted through a TCP socket and displayed in real time, i. e. as soon as a new line is transmitted, the diagram will be updated.
To use this function, select "Start/stop RT server" in the Extras menu and enter a port number. A process that connects to the port will have to follow a very simple uni-directional protocol: The server is started automatically if the "Autostart RT diagram server" flag is set to 1 in the configuration dialog.

Author

Markus Strauch < markus-strauch@arcor.de >

Acknowledgement

Thanks to Sebastian Loh for his relentless yet very constructive criticism towards this application's user interface.

Copyright

Copyright (c) 2006 - 2009 Markus Strauch. All rights reserved.

License

This program is released under the terms of the BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Third party licenses

The icons for decorating this program's buttons are taken from Crystal SVG - see http://www.everaldo.com They are released under the terms of the LGPL - see http://www.fsf.org/licensing/licenses/lgpl.html
The icon identifying this application's window is taken from ArgoUML, copyright by Tigris - see http://argouml.tigris.org - and released under the terms of the BSD license (see above).
The following software may be included in this product: FREEHEP - Copyright 2000-2005 by CERN, Geneva, Switzerland; SLAC, Stanford, California, U.S.A.; University of California Santa Cruz, U.S.A. The use of this software is governed by the terms of the LGPL. - see http://www.fsf.org/licensing/licenses/lgpl.html
The following software may be included in this product: Base64Coder - A Base64 Encoder/Decoder. Copyright 2003: Christian d'Heureuse, Inventec Informatik AG, Switzerland. Home page: source-code.biz . Base64Coder is "Open Source" software and released under the terms of the LPGL. - see http://www.fsf.org/licensing/licenses/lgpl.html
The following software may be included in this product: Apache Commons CLI. Copyright 2001-2007 The Apache Software Foundation. It includes software developed by The Apache Software Foundation (http://www.apache.org/). The use of this software is governed by the terms of the Apache license - see http://www.apache.org/licenses .