sequence.tex

% ========================================================================
% PlantUML : a free UML diagram generator
% ========================================================================
%
% (C) Copyright 2009, Arnaud Roques
%
% Project Info:  http://plantuml.sourceforge.net
% 
% This file is part of PlantUML.
%
% PlantUML is free software; you can redistribute it and/or modify it
% under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
%
% PlantUML distributed in the hope that it will be useful, but
% WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
% or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
% License for more details.
%
% You should have received a copy of the GNU General Public
% License along with this library; if not, write to the Free Software
% Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
% USA.
%
% [Java is a trademark or registered trademark of Sun Microsystems, Inc.
% in the United States and other countries.]
%
% Original Author:  Arnaud Roques
% 

\section{Sequence Diagram}

% ========================================================================
\subsection{Basic examples}

\begin{description}
\item
Every UML description must start by \texttt{@startuml} and must finish by \texttt{@enduml}.

\item
The sequence "\texttt{->}" is used to draw a message between two participants.

\item
Participants do not have to  be explicitly declared.

\item
To have a dotted arrow, you use "\texttt{-->}".

\item
It is also possible to use "\texttt{<-}" and "\texttt{<--}". That does not
change the drawing, but may improve readability.
\end{description}

Example:

\begin{lstlisting}
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml
\end{lstlisting}

\begin{center}
\includegraphics[width=70mm]{sequence.png}
\end{center}


% ========================================================================
\newpage \subsection{Declaring participant}

\begin{description}

\item It is possible to change participant order using the \texttt{participant} keyword.
\item It is also possible to use the \texttt{actor} keyword to use a stickman instead of a box for the participant.

\item You can rename a participant using the \texttt{as} keyword.

\item You can also change the background color of actor or participant, using html code or color name.

\item Everything that starts with simple quote \texttt{'} is a comment. 
\end{description}

\begin{lstlisting}
@startuml
actor Bob #red
' The only difference between actor and participant is the drawing
participant Alice
participant "I have a really\nlong name" as L #99FF99

Alice->Bob: Authentication Request
Bob->Alice: Authentication Response
Bob->L: Log transaction
@enduml
\end{lstlisting}

\begin{center}
\includegraphics[width=8cm]{sequence_001.png}
\end{center}


% ========================================================================
\newpage \subsection{Use non-letters in participants}

You can use quotes to define participants. And you can use the as keyword to give an alias to thoses participants.


\begin{lstlisting}
@startuml
Alice -> "Bob()" : Hello
"Bob()" -> "This is very\nlong" as Long
' You can also declare:
' "Bob()" -> Long as "This is very\nlong"
Long --> "Bob()" : ok
@enduml
\end{lstlisting}

\begin{center}
\includegraphics[width=45mm]{sequence_002.png}
\end{center}

% ========================================================================
\subsection{Message to Self}
\begin{description}
	\item A participant can send a message to itself.
	\item It is also possible to have multilines using \texttt{\textbackslash n}.
\end{description}

\begin{lstlisting}
@startuml

Alice->Alice: This is a signal to self.\nIt also demonstrates\nmultiline \ntext

@enduml
\end{lstlisting}

\begin{center}
\includegraphics[width=45mm]{sequence_003.png}
\end{center}


% ========================================================================
\newpage \subsection{Change arrow style}
You can change arrow style by several ways:
\begin{itemize}
	\item use \texttt{\textbackslash} or \texttt{/} instead of \texttt{<} or
	\texttt{>} to have only the bottom or top part of the arrow.
	\item repeat the arrow head (for example, \texttt{>>} or \texttt{//}) head to
	have a thin drawing.
	\item use \texttt{--} instead of \texttt{-} to have a dotted arrow
\end{itemize}

\begin{lstlisting}
@startuml
Bob -> Alice
Bob ->> Alice
Bob -\ Alice
Bob \\- Alice
Bob //-- Alice
@enduml
\end{lstlisting}

\begin{center}
\includegraphics[width=25mm]{sequence_004.png}
\end{center}


% ========================================================================
\newpage \subsection{Message sequence numbering}

The keyword \texttt{autonumber} is used to automatically add number to messages.

\begin{lstlisting}
@startuml
autonumber
Bob -> Alice : Authentication Request
Bob <- Alice : Authentication Response
@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=55mm]{sequence_005.png}
\end{center}


You can specify 
\begin{itemize}
  \item a startnumber with "\texttt{autonumber 'start'}" ,
  \item an increment with "\texttt{autonumber 'start' 'increment'}"
\end{itemize}


\begin{lstlisting}
@startuml

autonumber
Bob -> Alice : Authentication Request
Bob <- Alice : Authentication Response

autonumber 15
Bob -> Alice : Another authentication Request
Bob <- Alice : Another authentication Response

autonumber 40 10
Bob -> Alice : Yet another authentication Request
Bob <- Alice : Yet another authentication Response

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=8cm]{sequence_006.png}
\end{center}
\newpage
You can specify a format for your number by using between double-quote.
The formatting is done with the Java class \texttt{DecimalFormat} ('\texttt{0}' means digit,
'\texttt{\#}' means digit and zero if absent).

You can also use some html tags in the format.

\begin{lstlisting}
@startuml

autonumber "<b>[000]"
Bob -> Alice : Authentication Request
Bob <- Alice : Authentication Response

autonumber 15 "<b>(<u>##</u>)"
Bob -> Alice : Another authentication Request
Bob <- Alice : Another authentication Response

autonumber 40 10 "<font color=red><b>Message 0  "
Bob -> Alice : Yet another authentication Request
Bob <- Alice : Yet another authentication Response

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=8.5cm]{sequence_007.png}
\end{center}


% ========================================================================
\newpage \subsection{Title}

The \texttt{title} keywords is used to put a title.
\begin{lstlisting}
@startuml

title Simple communication example

Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=6cm]{sequence_008.png}
\end{center}


% ========================================================================
\newpage \subsection{Splitting diagrams}

The \texttt{newpage} keyword is used to split a diagram into several images.
You can put a title for the new page just after the \texttt{newpage} keyword.
This is very handy to print long diagram on several pages.

\begin{lstlisting}
@startuml
Alice -> Bob : message 1
Alice -> Bob : message 2

newpage

Alice -> Bob : message 3
Alice -> Bob : message 4

newpage A title for the\nlast page

Alice -> Bob : message 5
Alice -> Bob : message 6
@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=35mm]{sequence_009.png}
\vskip 6mm
\includegraphics[width=35mm]{sequence_009_001.png}
\vskip 6mm
\includegraphics[width=35mm]{sequence_009_002.png}
\end{center}
		
		
% ========================================================================
\newpage \subsection{Grouping message}

It is possible to group messages together using the following keywords:

\begin{itemize}
  \item \texttt{alt/else}
  \item \texttt{opt}
  \item \texttt{loop}
  \item \texttt{par}
  \item \texttt{break}
  \item \texttt{critical}
  \item \texttt{group}, followed by a text to be displayed
\end{itemize}

It is possible a add a text that will be displayed into the header. The
\texttt{end} keyword is used to close the group. Note that it is possible to
nest groups.

\begin{lstlisting}
@startuml
Alice -> Bob: Authentication Request
alt successful case
    Bob -> Alice: Authentication Accepted
else some kind of failure
    Bob -> Alice: Authentication Failure
    group My own label
    	Alice -> Log : Log attack start
        loop 1000 times
            Alice -> Bob: DNS Attack
        end
    	Alice -> Log : Log attack end
    end
else Another type of failure
   Bob -> Alice: Please repeat
end
@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=78mm]{sequence_010.png}
\end{center}

% ========================================================================
\newpage \subsection{Notes on messages}

It is possible to put notes on message using :
\begin{itemize}
\item \texttt{note left} or
\item \texttt{note right} keywords just after the message.
\end{itemize}
You can have multilines note using the \texttt{end note} keyword.

\begin{lstlisting}
@startuml
Alice->Bob : hello
note left: this is a first note

Bob->Alice : ok
note right: this is another note

Bob->Bob : I am thinking
note left
	a note
	can also be defined
	on several lines
end note
@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=8cm]{sequence_011.png}
\end{center}

% ========================================================================
\newpage \subsection{Some other notes}

It is also possible to place notes relative to participant with:
\begin{itemize}
\item \texttt{note left of},
\item \texttt{note right of} or 
\item \texttt{note over} keywords.
\end{itemize}
It is possible to highlight a note by changing its background color.
You can also have multilines note using the \texttt{end note} keywords.

\begin{lstlisting}
@startuml
participant Alice
participant Bob
note left of Alice #aqua
	This is displayed 
	left of Alice. 
end note
 
note right of Alice: This is displayed right of Alice.

note over Alice: This is displayed over Alice.

note over Alice, Bob #FFAAAA: This is displayed\n over Bob and Alice.

note over Bob, Alice
	This is yet another
	example of
	a long note.
end note
@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=8cm]{sequence_012.png}
\end{center}

% ========================================================================
\newpage \subsection{Formatting using HTML}

It is also possible to use few html tags like :
\begin{itemize}
\item \texttt{$<$b$>$} for bold text
\item \texttt{$<$u$>$} or \texttt{$<$u:\#AAAAAA$>$} or
\texttt{$<$u:colorName$>$} for underline
\item \texttt{$<$i$>$} for italic
\item \texttt{$<$s$>$} or \texttt{$<$s:\#AAAAAA$>$} or
\texttt{$<$s:colorName$>$} for strike text
\item \texttt{$<$w$>$} or \texttt{$<$w:\#AAAAAA$>$} or
\texttt{$<$w:colorName$>$} for wave underline text
\item \texttt{$<$color:\#AAAAAA$>$} or \texttt{$<$color:colorName$>$}
\item \texttt{$<$back:\#AAAAAA$>$} or \texttt{$<$back:colorName$>$} for
background color
\item \texttt{$<$size:nn$>$} to change font size
\item \texttt{$<$img:file$>$} : the file
must be accessible by the filesystem
\end{itemize}

\begin{lstlisting}
@startuml
participant Alice
participant "The <back:cadetblue>Famous</b> Bob" as Bob

Alice -> Bob : A <i>well formated</i> message
note right of Alice 
	This is <b><size:18>displayed</size></back> 
	<u>left of</u> Alice. 
end note
note left of Bob 
	<u:red>This</u> is <color:#118888>displayed</color> 
	<b><color:purple>left of</color> <s:red>Alice</s> Bob</b>. 
end note
note over Alice, Bob
	<w:#FF33FF>This is hosted by</w> <img:sourceforge.jpg>
end note
 
@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=65mm]{sequence_013.png}
\end{center}

		

% ========================================================================
\newpage \subsection{Divider}

If you want, you can split a diagram using "\texttt{==}" separator to divide your diagram into logical steps.

\begin{lstlisting}
@startuml

== Initialisation ==

Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

== Repetition ==

Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=70mm]{sequence_014.png}
\end{center}


% ========================================================================
\newpage \subsection{Lifeline Activation and Destruction}

\begin{description}
\item The \texttt{activate} and \texttt{deactivate} are used to denote
participant activation.
\item Once a participant is activated, its lifeline appears.
\item The \texttt{activate} and \texttt{deactivate} apply on the previous
message.
\item The \texttt{destroy} denote the end of the lifeline of a participant.
\end{description}

\begin{lstlisting}
@startuml
participant User

User -> A: DoWork
activate A

A -> B: << createRequest >>
activate B

B -> C: DoWork
activate C
C --> B: WorkDone
destroy C

B --> A: RequestCreated
deactivate B

A -> User: Done
deactivate A

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=8cm]{sequence_015.png}
\end{center}

\newpage
Nested lifeline can be used, and it is possible to add a color on the lifeline.

\begin{lstlisting}
@startuml
participant User

User -> A: DoWork
activate A #FFBBBB

A -> A: Internal call
activate A #DarkSalmon

A -> B: << createRequest >>
activate B

B --> A: RequestCreated
deactivate B
deactivate A
A -> User: Done
deactivate A

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=70mm]{sequence_016.png}
\end{center}

% ========================================================================
\newpage \subsection{Participant creation}

You can use the \texttt{create} keyword just before the first reception
of a message to emphasize the fact that this message is actually \textit{creating}
this new object.

\begin{lstlisting}
@startuml
Bob -> Alice : hello

create Other
Alice -> Other : new

create String
Alice -> String
note right : You can also put notes!

Alice --> Bob : ok

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=110mm]{sequence_017.png}
\end{center}



% ========================================================================
\newpage \subsection{Incoming and outgoing messages}

\begin{description}
\item You can use incoming or outgoing arrows if you want to focus on a part of the diagram.
\item Use square brackets to denotate the left "\texttt{[}" or the
right "\texttt{]}" side of the diagram.
\end{description}

\begin{lstlisting}
@startuml
[-> A: DoWork

activate A

A -> A: Internal call
activate A

A ->] : << createRequest >>

A<--] : RequestCreated
deactivate A
[<- A: Done
deactivate A
@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=60mm]{sequence_018.png}
\end{center}


% ========================================================================
\newpage \subsection{Stereotypes and Spots}

It is possible to add stereotypes to participants using "\texttt{<<}" and
"\texttt{>>}". In the stereotype, you can add a spotted character in a colored
circle using the syntax "\texttt{(X,color)}".

\begin{lstlisting}
@startuml

participant "Famous Bob" as Bob << Generated >>
participant Alice << (C,#ADD1B2) Testable >> #EEEEEE

Bob->Alice: First message

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=60mm]{sequence_019.png}
\end{center}
		

\begin{lstlisting}
@startuml

participant Bob << (C,#ADD1B2) >>
participant Alice << (C,#ADD1B2) >>

Bob->Alice: First message

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=45mm]{sequence_020.png}
\end{center}

		
% ========================================================================
\newpage \subsection{More information on titles}

You can use some HTML tags in the title.
\begin{lstlisting}
@startuml

title <u>Simple</u> communication example

Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=60mm]{sequence_021.png}
\end{center}

You can add newline using \texttt{\textbackslash n} in the title description.
\begin{lstlisting}
@startuml

title <u>Simple</u> communication example\non several lines

Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=60mm]{sequence_022.png}
\end{center}

\newpage
You can also define title on several lines using \texttt{title} and
\texttt{end title} keywords.
\begin{lstlisting}
@startuml

title
 <u>Simple</u> communication example
 on <i>several</i> lines and using <font color=red>html</font>
 This is hosted by <img src=sourceforge.jpg>
end title

Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=65mm]{sequence_023.png}
\end{center}

% ========================================================================
\newpage \subsection{Participants englober}

\begin{description}
\item
It is possible to draw a box arround some participants, using \texttt{box} and
\texttt{end box} commands.
\item
\item You can add an optional title or a optional
background color, after the \texttt{box} keyword.
\end{description}

\begin{lstlisting}
@startuml
box "Internal Service" #LightBlue
	participant Bob
	participant Alice
end box
participant Other

Bob -> Alice : hello
Alice -> Other : hello
@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=50mm]{sequence_024.png}
\end{center}

% ========================================================================
\newpage \subsection{Removing Footer}

You can use the \texttt{hide footbox} keywords to remove the footer of the
diagram.
\begin{lstlisting}
@startuml

hide footbox
title Footer removed

Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=55mm]{sequence_025.png}
\end{center}


% ========================================================================
\newpage \subsection{Skinparam}

You can use the \texttt{skinparam} command to change colors and fonts for the drawing.
You can use this command :

\begin{itemize}
\item In the diagram definition, like any other commands,
\item In an included file,
\item In a configuration file, provided in the command line or the ANT task.
\end{itemize}

\begin{lstlisting}
@startuml
skinparam backgroundColor #EEEBDC

skinparam sequence {
	ArrowColor DeepSkyBlue
	ActorBorderColor DeepSkyBlue
	LifeLineBorderColor blue
	LifeLineBackgroundColor #A9DCDF
	
	ParticipantBorderColor DeepSkyBlue
	ParticipantBackgroundColor DodgerBlue
	ParticipantFontName Impact
	ParticipantFontSize 17
	ParticipantFontColor #A9DCDF
	
	ActorBackgroundColor aqua
	ActorFontColor DeepSkyBlue
	ActorFontSize 17
	ActorFontName Aapex
}

actor User
participant "First Class" as A
participant "Second Class" as B
participant "Last Class" as C
User -> A: DoWork
activate A
A -> B: Create Request
activate B
B -> C: DoWork
activate C
C --> B: WorkDone
destroy C
B --> A: Request Created
deactivate B
A --> User: Done
deactivate A
@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=69mm]{sequence_026.png}
\end{center}

% ========================================================================
\newpage \subsection{Skin}

Use the keyword \texttt{skin} to change the look of the generated diagram.
There are only two skins available today (\textit{Rose}, which is the default, and \textit{BlueModern}),
but it is possible to write your own skin.

\begin{lstlisting}
@startuml
skin BlueModern

actor User
participant "First Class" as A
participant "Second Class" as B
participant "Last Class" as C

User -> A: DoWork
activate A

A -> B: << createRequest >>
activate B

B -> C: DoWork
activate C
C --> B: WorkDone
destroy C

B --> A: Request <u>Created</u>
deactivate B

A --> User: Done
deactivate A

@enduml
\end{lstlisting}
\begin{center}
\includegraphics[width=90mm]{sequence_027.png}
\end{center}