Developing around PlantUML

In Integration Testing from the Trenches, I made heavy use of UML diagrams. So far, I’ve tried and used many UML editors. I’ve used:

  • The one that came with NetBeans - past tense, they removed it
  • Microsoft Visio
  • Modelio - this might be one of the best
  • others that I don’t remember

I came to the following conclusion: most of the time (read all the time), I just need to document an API or what I want designed, and there’s no need to be compliant to the latest UML specs. Loose is good enough.

True UML editors don’t accept loose, it’s UML after all. UML drawings tools are just that - drawing tools, with a little layer above. All come with these problems:

  • They consume quite a lot of resources
  • They have their own dedicated file format from which you can generate the image

I’m interested in the image, but want to keep the file there just in case I need an update.

PlantUML

Then I came upon PlantUML and I rejoiced. PlantUML defines a simple text syntax from which it generates UML diagrams images. So far, I’ve known 3 ways to generate PlantUML diagrams:

  • The online form
  • The Confluence plugin
  • Installing the stuff on one’s machine

I’ve used the former 2, with a tendency toward the first, as Confluence requires you to save to generate the image. This is good for the initial definition. However, it’s more than a little boring when one has to go through all ~60 diagrams to update them with a higher resolution.

Thus, I decided to develop a batch around PlantUML that will perform the following steps:

  • Read PlantUML description files from a folder
  • Generate images from them through the online form
  • Save the generated images in a folder

The batch run can be configured to apply settings common to all description files. This batch should not only be useful, it should also teach me stuff and be fun to code (note that sometimes, those goals are opposite).

Overall architecture

I’m a Spring fanboy but I wanted the foundations to be completely free on any dependencies.

Overall architecture
jplantuml-api

Defines the very basic API. It contains only an Exception and the root interface, which extends Java 8’s Function<I,O>. This way is not just hype, it let user classes compose functions together which is the highest possible composition potential I’ve seen so far in Java.

jplantuml-online

Uses the JSoup library to connect to the online server. Also implements reading from a text file and writing the result to an image file.

jplantuml-batch

Adapts everything into the Spring Batch model.

The power of Function

In Java 8, a Function<I,O> is an interface that transforms an input of type I to an output of type O via its apply() method. But, with the power of Java 8’s default methods, it also provides the compose() and andThen() method implementations.

Function

This enables chaining Function calls in a process pipeline. One can define a base JPLantUml implementation that applies a String to a byte array for a simple call, and a more complex one that does the same for a File (the description) and…​ a File (the resulting image). However, the latter just compose 3 functions:

  1. A file reader to read the description file content, from File to String
  2. The PlantUML call processor from String to byte[]
  3. A file writer to write the image file, from byte[] to File

And presto, we’ve got our functions composition. This fine-grained nature let us do some unit-testing of the reader and writer functions without requiring any complex mocking.

Outcome

The result of this code is this Github project. It lets you use the following command-line:

java -jar ch.frankel.jplantuml.batch.Application globalParams="skinparam dpi 150; hide empty members"

This will read all PlantUML files from /tmp/in, apply the above parameters and generate the resulting image files in /tmp/out. The in/out folders can be set using standard  Spring Batch properties overriding.

Nicolas Fränkel

Nicolas Fränkel

Developer Advocate with 15+ years experience consulting for many different customers, in a wide range of contexts (such as telecoms, banking, insurances, large retail and public sector). Usually working on Java/Java EE and Spring technologies, but with focused interests like Rich Internet Applications, Testing, CI/CD and DevOps. Also double as a trainer and triples as a book author.

Read More
Developing around PlantUML
Share this