Messages
Last updated
Was this helpful?
Last updated
Was this helpful?
Messages are the basic action of sequence diagrams. They are portrayed by arrows going from a sender to a receiver.
Lifelines will not be declared in this section unless required for an explanation. This will keep our code blocks smaller and easier to read.
In PlantUML, you declare messages by drawing an arrow with the characters on your keyboard. Place the arrow between the sender and the receiver with the arrow pointing at the receiver.
Arrows can be drawn right to left or left to right. This is nice as it allows you to customize how you want to format your messages. You can always keep senders on one side of your messages like the top of our example. You can also let your arrows go back and forth while your senders stay in the same place on consecutive lines like the bottom of our example. There is also the unadvised option of not picking a method. Do what makes sense for you and your team.
The minimum requirements for a message are sender, line_type, head_type, and receiver. As we did with lifelines, we will keep all message properties except message_text in the below order throughout this book. Remember the order is sender to receiver, as shown above, not necessarily left to right. The message_text property is always furthest to the right.
sender - the entity sending the message, usually a participant's lifeline
line_type - determines if the message arrow has a solid or dashed line
arrow_color - sets the color of the message arrow
arrow_head - determines the shape of the arrowhead
receiver - the entity receiving the message at the pointy end of the arrow, usually a participant’s lifeline
message_text - the text that appears with the message arrow
Senders and receivers are usually the participants with lifelines discussed in the previous section. There are a few exceptions. Messages that come from or go to places outside the scope of the current diagram have gates as their sender or receiver at the edge of the diagram. Other messages may get lost, or we may not know where they originated. Per UML standards, these lost and found messages are sent or received from a circle. PlantUML has no standalone command for this, so we must combine gates with our circle. UML calls for a solid circle, but PlantUML only supports an open circle. At the time of this writing, PlantUML does not properly display the messages found originating from the right side gate.
Senders and receivers that are not lifelines with names must touch the arrow_head. See the list of senders and receivers below.
A message can have the same sender and receiver.
name - the name of a lifeline
[ - signifies a gate touching the left side of the sequence diagram can be a sender or receiver
] - signifies a gate touching the right side of the diagram can be a sender or receiver
o- used as the sender of a found message or the receiver of a lost message; this is a lower-case letter o
? - a special character used to shorten the length of a message arrow
"-" - creates a solid line
"--" - creates a dashed line
You can define arrow_color with a standard color name or hex code placed between the line_type and arrow_head. Enclose the color with square brackets. Note that the circle for lost and found messages will be the same color as the arrow.
-- > filled arrow_head right
-- >> open arrow_head right
-- \ top half of filled arrow_head right
-- / bottom half of filled arrow_head right
-- \\ top half of open arrow_head right
-- // bottom half of open arrow_head right
< -- filled arrow_head left
<< -- open arrow_head left
/ -- top half of filled arrow_head left
\ -- bottom half of filled arrow head left
// -- top half of open arrow_head left
\\ -- bottom half of open arrow_head left
-- X object deletion message
< -- > bidirectional arrows are possible with all arrow_heads
There are two basic line_types, solid and dashed. Solid lines are for basic messages. Dashed lines are for replies and lifeline creation messages. Creation messages are covered in the section of .
UML standards for sequence diagrams describe three options for arrow_heads. A filled arrow_head represents a synchronous message. An open arrow_head represents an asynchronous message. An X or cross represents an object deletion message. For more on object deletion messages see . PlantUML provides us with several more options for increased personalization. These will be attached to a reply line_type in the following list for easier visualization. Be mindful the backslashes in the example as they are still escape characters in the message_text.
Place message_text at the end of the message after a colon. You can format message_text with creole syntax for emphasis and markup language for color and emphasis. You can define colors with a standard color name or hex code. Use for manual line breaks. For automatic line breaks, see maxMessageSize in the section. See for a list of creole and markup options.
