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.
- 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.
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:
- A file reader to read the description file content, from
FiletoString - The PlantUML call processor from
Stringtobyte[] - A file writer to write the image file, from
byte[]toFile
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.