Picture This

Sooner or later, almost everybody needs to draw a diagram, whether to manage large amounts of information or organize group activities. For software developers and administrators (as well as business managers), diagrams based on the Unified Modeling Language (UML) make it easy to visualize complex systems, from software platforms to quality control departments, to see how they function.

UML stores drawings as plain text files, with a relatively intuitive syntax. If you are familiar with mind maps, you can often guess how to manually draw a diagram described by a UML file just by looking at it – even if you don't know UML! Because it is text-based, UML is extremely simple to generate with any software. You can produce hundreds of similar diagrams, with different parameters, by passing code generated on the fly by a simple shell script (or any other program) to a UML interpreter.

Additionally, UML is useful for efficiency, consistency, and version control. In a large project, UML interpreters can automatically find all the diagram descriptions in all of the project's files and generate the corresponding images in one fell swoop. The UML statements for a software algorithm or protocol's visual representation can be written as comments right above the code it visualizes in the software source file. Thanks to this integration, version control systems can store and track changes between different versions of many diagrams, just as they do with software code. The same feature makes it easy to quickly check if a diagram is consistent with the code it represents. All of this makes UML really reusable.

PlantUML [1], an open source UML diagram tool, lets you quickly create many different types of UML diagrams from text-based descriptions. In addition, you can also generate several diagram types not included in the UML standard (Gantt, mind map, WBS). While some types of PlantUML diagrams, like timing and interface mock-ups, may only be interesting to software and hardware designers, the diagram styles shown here can benefit all users.

PlantUML is perfect for beginners and intermediate users. It runs everywhere Java runs, and it is easily included in scripts. While it offers a very basic graphical interface, I prefer to write diagrams in my favorite text editor and then launch PlantUML from the command line.

Installation

The fastest way to use PlantUML is via the official web server [2], but you also can easily install it on your computer. The only prerequisite is a working java command, which is the core part of any Java Runtime Environment (JRE). For testing some diagram types, you may also need the Graphviz utility, but that is available as a binary package for most Linux distributions. On Linux, you can check if you have a working JRE by typing the following at the prompt:

#> java -version

On Ubuntu, if JRE is not installed, you will get a notification that "the program 'java' can be found in the following packages":

* default-jre
... other Java packages...

In that case, just install the default JRE with:

#> sudo apt install default-jre

After installation (which consumed about 100MB of disk space on my computer), you can just download the Java container file, plantuml.jar, from the website and save it in a folder of your choice.

Getting Started

To create a diagram from instructions saved into a plain text file called myumldiagram.puml (.puml is PlantUML's default file extension), enter the following at the prompt or in a shell script:

java -jar /path/to/plantuml.jar myumldiagram.puml

This command produces a PNG version of the diagram with the same name as the source file (in this case myumldiagram.png) in the same folder. Other supported output formats are SVG and LaTeX. You can assign a different name and location to a diagram if desired. With the -pipe option, PlantUML reads from standard input and "prints" the diagram on the standard output, which you can redirect wherever you want:

cat somefile.puml | java -jar plantuml.jar-pipe > /path/to/somefile.png

It is possible to process multiple UML source files with one call. If you give PlantUML a folder instead of a file, all the text files in that folder will be processed. Alternatively, you can use shell wildcards to only parse files with certain names or extensions:

java -jar /path/to/plantuml.jar "source/*/*.c"

To put all the generated images into a common folder, pass its absolute path to PlantUML with the -o switch.

Even the simple examples shown in this article can take two to three seconds to run. If you plan to simultaneously process many UML files, take advantage of the -failfast2 and -failfast options. -failfast2 checks if there are any errors in any of the files passed to the program and stops it without generating a diagram. -failfast parses the code, but stops as soon as it finds one error. You must decide which option best fits your needs.

By default, PlantUML saves each diagram's full UML code inside the PNG file's metadata section, making it very easy to retrieve. The following command

java -jar /path/to/plantuml.jar -metadata statediagram.png >statediagram.puml

will save all the UML statements that generated statediagram.png into a text file with the same base name, which allows quick changes to complex diagrams even if you did not write the code or have their UML description! A similar option, -checkmetadata, regenerates a diagram only if the source code it contains does not match the corresponding .puml file.

While the command-line switches mentioned here will be enough for most of your diagramming needs, you can learn about PlantUML's other command-line options in the documentation [3] or launch PlantUML with the -help switch. You can also use the -language switch to list all the UML keywords supported by PlantUML.

Sequence Diagrams

Sequence diagrams are frequently used in software and telecom documentation to describe exchanges between programs or communication protocols. However, as Listing 1 shows, they can describe any type of structured transaction (Figure 1). Listing 1 shows the UML source code for Figure 1.

01 @startuml
02 Alice -> Bob  : Hello, is the store open?
03 Bob   -> Alice: Yes, it is. What do you want to buy?
04 Alice -> Bob  : I want to buy some jeans
05 Alice <- Bob  : Please tell me the color
06 Alice -> Bob  : Black
07 Alice <- Bob  : Now please tell me the size
08 Alice -> Bob  : 42
09 @enduml

Figure 1: With a sequence diagram, you can show any structured transaction.

You can see UML's intuitiveness in Listing 1: Diagrams (with the exceptions discussed below) are enclosed between @startuml and @enduml statements; each line defines one element (in Figure 1, one transaction step). The direction of each step (i.e., if Alice is speaking to Bob, or vice versa) is given by the name order (line 2) or the arrow orientation (line 7). You can also draw sequencing exchanges among more than two entities.