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.
Among its features are:
- Automatic redrawing - The diagram changes as you type.
- Syntax check - errors in the textual descriptions are
highlighted and can thus easily be found.
- Automatic completion - Object names can be guessed from a prefix
(using the TAB key).
- Export - Diagrams can be exported in virtually any format,
whether vector or pixel based.
- Zoom - Diagrams can be viewed in any zoom factor.
- View-text-correspondence - When you enter a message, the diagram
view scrolls to where the corresponding arrow is to be seen. When
you click an arrow, the cursor moves to the line where the message
corresponding to the arrow is specified.
- Server mode - Diagram specifications generated by another tool
can be transmitted through a socket and displayed in real-time.
- Links - You can create links to other diagrams. This feature can
be used for providing easy access to a finer view onto something
from which a more coarse-grained diagram abstracts away.
- Pagination - Diagrams can be printed on multiple pages.
- Persistent preferences - Diagram preferences can be saved along
with the diagram's source code.
-
Breadth first search
-
Example illustrating levels and mnemonics
-
Ticket order
-
SSH 2 (by courtesy of Carlos Duarte)
-
Webserver
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 '\'.
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.
If <name> is prefixed with a '/', the lifeline will
be invisible until the instance is created by a 'new' message to
<name> (see below).
An object declaration can be followed by a sequence of
<flags> between square brackets. Four flags (a,p,r,x)
are supported:
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.
The label of the lifeline will not be underlined.
The object behaves like an actor (see below), but it is
represented by a box with a thick border, not by a figure.
(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.
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.
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.
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)
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.
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.
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.
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.
Diagrams can be annotated in three different ways.
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.
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.
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.
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.
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:
- (<num>). A line will be drawn from the note box
with the number <num> to the message arrow or to the
current vertical position of the lifeline.
- (<num>,<anum>). This can only be
the prefix of a message. The effect is the same as above, if
<num> is not empty. Additionally, there will be a
line drawn from the note box <anum> to the arrow
belonging to the answer of the message
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.
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:/".
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.
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.
Please also take a look at these supplementary help pages:
There are some types of preferences, which can all be adjusted in the
tabs of a single preferences dialog.
- Global preferences: These preferences determine the general
behaviour and look of the application. They are stored in the file
.sdedit.conf in a user directory ($HOME on Unix,
Application Data on Windows). In order to restore the default
preferences (which came shipped with the application), one can use the
"Restore defaults" button.
- Initial diagram preferences: These preferences are applied to a
diagram that is being newly created or that is loaded from a plain
(sd) file. They are also stored in .sdedit.conf. One can
use the current diagram's preferences as the initial preferences (via
the "Save as initial" button). Also, one can restore
the default initial preferences (which came shipped with the
application) via the "Restore defaults" button.
- Current diagram preferences: These preferences are applied only
to the diagram currently being displayed. They are saved along with
the diagram source when it is saved as an sdx file. When a diagram is
saved as an sd file, these preferences will be lost.
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.
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"
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.
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:
-
<start-command> -h
-
<start-command> -o /tmp/bfs.pdf -t pdf /tmp/examples/bfs.sd
-
<start-command> -o /tmp/ssh.ps -t ps -f A0 -r
Landscape --threaded=false /tmp/examples/ssh.sd
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.
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 first line is interpreted as the name of a new tab to be
opened.
- The remaining lines are entered into the text area of the new
tab.
- When a line consists of the word "end", the
socket will be closed. The line will not appear in the text area.
The server is started automatically if the "Autostart RT
diagram server" flag is set to 1 in the configuration dialog.
Thanks to Sebastian Loh for his relentless yet very constructive
criticism towards this application's user interface.
Copyright (c) 2006 - 2009 Markus Strauch. All rights reserved.
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.
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 .