Creating an @plantuml Javadoc Custom Taglet

I love PlantUML, easily create UML diagrams using a description instead of having to draw them myself.

One thing I didn't like was the need to have to install the library GraphViz¹ everywhere, where I wanted to use PlantUML.

But imagine my surprise when I found out, that I don't need to any more.

The java library Smetana², which apparently functions as a drop in replacement for GraphViz should work exactly the same. And it's already integrated in PlantUML!

Can things get any better?

So, once more, let me integrate it into my javadoc build workflow of my sample Java Project using maven.

I had the idea to create a Java Doclet for generating my javadoc, but I quickly realised I should be making a PlantUML Taglet instead. It's already been done, see [3], but I wanted something a little different. But I did get some good ideas from that site.

I wanted to inline the imagedata in the src attribute of the image tag, that seems nicer than separate png files.

I also wanted to use the Smetana by default.

I managed it and uploaded it on the github⁴.

Maven integration

Adding the custom taglet to your pom.xml in the javadoc plugin should be enough. You do need to have my custom Taglet installed in your maven .m2/repository directory though.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.6.0</version>
  <configuration>
    <taglet>org.taglet.plantuml.PlantumlTaglet</taglet>
    <!-- <tagletpath>/path/to/taglet.jar</tagletpath> -->
    <tagletArtifact>
      <groupId>org.taglet.plantuml</groupId>
      <artifactId>plantumltaglet</artifactId>
      <version>1.0</version>
    </tagletArtifact>
  </configuration>
</plugin>

The following is sufficient to run javadoc and generate the diagrams:

mvn javadoc:javadoc

Eating your own dogfood

It also serves as a good example of eating your own dog food⁵.

That's right!

I added PlantUML diagrams to the javadocs of my new PlantUML Taglet, and generated the javadoc+diagrams using my PlantUML Taglet!

/**
 * Created PlantUML Diagrams based on a plantuml description.
 * @plantuml
 * PlantumlImageDataFactory : +getImageData(plantuml: String): String
 */
public class PlantumlImageDataFactory {

Worked like a charm!

It will look like this:

The image will be as raw data in the html source code, like so:

<section class="class-description" id="class-description">
<dl class="notes">
<dt>All Implemented Interfaces:</dt>
<dd><code><a href="https://docs.oracle.com/en/java/javase/17/docs/api/jdk.javadoc/jdk/javadoc/doclet/Taglet.html" title="class or interface in jdk.javadoc.doclet" class="external-link">Taglet</a></code></dd>
</dl>
<hr>
<div class="type-signature"><span class="modifiers">public class </span><span class="element-name type-name-label">PlantumlTaglet</span>
<span class="extends-implements">extends <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a>
implements <a href="https://docs.oracle.com/en/java/javase/17/docs/api/jdk.javadoc/jdk/javadoc/doclet/Taglet.html" title="class or interface in jdk.javadoc.doclet" class="external-link">Taglet</a></span></div>
<div class="block">A Taglet made by me to convert appropriate Plantuml codes into generated diagrams. Uses layout smetana instead
 of GraphViz.</div>
<dl class="notes">
<dt>See Also:</dt>
<dd>
<ul class="tag-list">
<li><a href="https://mnlipp.github.io/jdrupes-taglets/plantuml-taglet/javadoc/index.html">PlantUML Taglet</a></li>
</ul>
</dd>
<p><img alt="umldiagram" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAhMAAAC2CAIAAADsj5gHAAAAKnRFWHRjb3B5bGVmdABHZW5lcmF0ZWQgYnkgaHR0cHM6Ly9wbGFudHVtbC5jb212z..." /></p></dl>
</section>

References

[1] PlantUML - GraphViz-Dot

https://plantuml.com/graphviz-dot

[2] PlantUML - Porting GraphViz to Java

https://plantuml.com/smetana02

[3] PlantUML Taglet

https://mnlipp.github.io/jdrupes-taglets/plantuml-taglet/javadoc/index.html

[4] Github.com - PlantUML Taglet

https://github.com/maartenl/plantumltaglet

[5] Wikipedia - Eating your own dog food

https://en.wikipedia.org/wiki/Eating_your_own_dog_food

Entity-Relationship Diagrams

I tend to forget what the arrows mean in an entity-relationship diagram.

Example

In the diagram above, there's strong limitations on the values possible in the GuildMember table. Unfortunately, these cannot be expressed in Foreign Key Relationships.

For example:

• a Person can hold only one rank in a Guild.
• a Person can only be a GuildMember in a Guild once.

The way to fascilitate this, is to put a unique index on GuildMember regarding the columns GUILDNR and PERSONNR.

References

PlantUML - Entity Relationship Diagram

https://plantuml.com/ie-diagram

LucidChart - Wat is een Entity Relationship Diagram?

https://www.lucidchart.com/pages/nl/wat-is-een-entity-relationship-diagram

UML Class Diagrams - Common Conventions

I just felt like writing this stuff down for once.

Java keyword	UML	PlantUML syntax
public	+	+/green circle
protected	#	#/yellow diamond
package-private	~	~/blue triangle
private	-	-/red square
abstract	italic	{abstract}/italic
static	underlined	{static}/underlined
public final static	constants are in ALL_CAPS
final definition	{leaf}
final value	{readOnly}

References

The Oxford Math Center - UML, Abstract Classes and Methods, and Interfaces

http://www.oxfordmathcenter.com/drupal7/node/35

UML 2.5.1. specification

https://www.omg.org/spec/UML/2.5.1/

StackOverflow - How do I add a final variable to a class diagram?

https://stackoverflow.com/questions/16252399/how-do-i-add-a-final-variable-to-class-diagram

PlantUML - Class Diagram

http://plantuml.com/class-diagram

Modelling Java Annotations in UML

I was wondering how to put Java Annotations in an UML schema.

Turns out there is no support for it, but some smart people gave it a try anyway and wrote it down in a paper¹. Of course they are using the already existing possibilities of UML, so the UML does not exactly match up with the idea of Annotations.

Annotations can be applied to declarations: declarations of classes, fields, methods, and other program elements. Since Java 8, also annotations are supported anywhere a type is used².

However, some people³ do have a valid point when they say that modelling Annotations might be a severe case of micromodelling.

PlantUML

It's not a secret that I am a fan of plantuml⁴, and all the pretty pictures on this page are dynamically created by the PlantUML Online Server⁵ that they have running. Which also means, if the pictures are not visible, the server is down.

I wanted to see how far I could take PlantUML in processing the ideas in the paper.

1. Attributes as UML Stereotypes

@startuml
class  Mail <<@FunctionalInterface>> <<@Table(name = "mm_mailtable")>> {
  -@Id id: Long
  -@NotNull @Column subject: String
  +getId(): Long
  +setId(id: Long)
}
@enduml

2. Attributes as extra class subbox

@startuml
class Mail {
  @Entity
  @Table(name = "mm_mailtable")
  --
  -@NotNull @Column subject: String
  --
  +getId(): Long
  +setId(id: Long)
}
@enduml

3. Attributes as UML Template Parameter

@startuml
class Mail <@Entity \n @Table(name = "mm_mailtable")> {
  -@Id id: Long
  -@NotNull @Column subject: String
  --
  +getId(): Long
  +setId(id: Long)
}
@enduml

4. Attributes as separate Class

@startuml
class Mail {
  -@Id id: Long
  -@NotNull @Column subject: String
  --
  +getId(): Long
  +setId(id: Long)
}
class "@Entity \n @Table(name = "mm_mailtable")" as Entity
Entity - Mail : <<annotated>>
@enduml

5. Attributes as Comment boxes

@startuml
class Mail {
  -@Id id: Long
  -@NotNull @Column subject: String
  --
  +getId(): Long
  +setId(id: Long)
}
note right
@Entity
@Table(name = "mm_mailtable")
end note
@enduml

Conclusion

My personal opinion is that UML Stereotypes folllows the Java class most narrowly, so I like that. But I think the "Annotations as a separate class" follows UML conventions quite good.

The paper contains a nice table where they are considering the pros and cons of all the methods described above.

As there seems no standard defined in UML, if you need to model Annotations at all (and that's a big if), pick the one you like.

References

[1] Representing Explicit Attributes in UML

http://dawis2.icb.uni-due.de/events/AOM_MODELS2005/Cepa.pdf

[2] Oracle Tutorial - Annotations

https://docs.oracle.com/javase/tutorial/java/annotations/basics.html

[3] CodeRanch - UML / Class Diagram Syntax for Java Annotations

https://coderanch.com/t/100641/UML-Class-Diagram-Syntax-Java

[4] Plantuml

http://plantuml.com/

[5] Plantuml Online Server

http://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000

GitHUb - Mail.java

https://github.com/maartenl/Land-of-Karchan/blob/master/karchangame/src/main/java/mmud/database/entities/game/Mail.java

UML - What do those Arrows Mean?

In PlantUML:

@startuml
abstract class Animal
interface Behaviour
interface Prey
Animal <|-- Lion : inheritance
Behaviour <|.. Animal : realization/implementation
Lion -left-* Pride : composition
interface Grouping
Grouping <|.. Pride
Prey -left-O Lion : aggregation
Water <-down- Lion : uni-directional
Habitat -up- Lion : bi-directional
@enduml

implementation/realization

a dotted line with a closed, unfilled arrow means realization (or implementation). The arrow points to the interface.

inheritance

Inheritance is indicated by a solid line with a closed, unfilled arrowhead pointing at the super class

aggregation

a solid line with an unfilled diamond at the class which uses the other class

composition

a solid line with an filled diamond at the class which contains the other class

bi-directional association

A bi-directional association is indicated by a solid line between the two classes. In the example, the Lion lives in his Habitat, but the Habitat benefits in some way from the Lion as well.

uni-directional association

A uni-directional association is indicated by a solid line between the two classes. The class that knows nothing of the other class, has an open arrowhead pointing to it. A Lion uses Water, but not the other way around.

References

[1] Wikipedia - Class diagram

http://en.wikipedia.org/wiki/Class_diagram

[2] IBM Developer Works - UML basics The class diagram

https://www.ibm.com/developerworks/rational/library/content/RationalEdge/sep04/bell/

What's the difference between Aggregation and Composition?

http://randomthoughtsonjavaprogramming.blogspot.nl/2013/11/whats-difference-between-aggregation.html

Gliffy vs Plantuml

At work we have used Trac³, especially it's wiki, as well as PlantUML², which fitted seamlessly inside Trac.

Recently we have moved over to Confluence³ and a different diagram tool called Gliffy (which company makes an excellent plugin for adding Gliffy to Confluence)¹.

After working with both PlantUML as well as Gliffy, I thought I'd write down some points in favour of both.

PlantUML

UML Images are generated by interpreting a simple and intuitive language.

Gliffy

a Web-based drawing tool for diagrams

PlantUML

Pro	Con	Comments
Layout is handled by the tool itself	Influence of user on layout is limited	makes it easy to create diagrams quickly
	software with required libraries without UI
possible integration via commandline, for example batch jobs, software buildscripts to generate documentation automatically (javadoc for example)	difficult integration with Confluence
a simple and intuitive language makes it easy to create diagrams quickly	it is a markup language, and therefore more suited to software developers
strong focus on UML	limited number of diagram components, strong focus on UML
very easy to change existing diagrams, even very complex ones

Gliffy

Pro	Con	Comments
Layout can be adapted in every little detail	You get stuck having to draw instead of simply create diagrams	makes it difficult to create or change diagrams quickly
Web tool - no obvious software needs to be installed (only on the server)	Responsiveness is not great in a web browser
excellent integration with Confluence by means of a plugin
even managers might be able to use it	which is a really really bad idea.
lots and lots of diagram components, including UML
	very difficult to change existing diagrams, sometimes things need to be redrawn5

Conclusion

If you wish to draw UML diagrams quickly, and integrate them into your build process, PlantUML is the way to go.

If you need all the flexibility you can get and you don't mind having to draw and layout things yourself, Gliffy is the way to go.

References

[1] Gliffy

https://www.gliffy.com/

[2] PlantUML

http://plantuml.sourceforge.net/

[3] Confluence

https://www.atlassian.com/software/confluence

[4] TRAC - Integrated SCM and Project Management

http://trac.edgewall.org/wiki/TracWiki

[5] impossible to change the type of a component in Gliffy

work around is to delete the entire component, and create a new component of the correct type

1Z0-807 Java EE 6 Enterprise Architect Certified Master Exam

follow-up of [2]

Pfew! Made it! Woohoo! I had answered 73% of questions correctly, and I needed 71%. I should've studied more.

It is Multiple-Choice, and some of the wrong possible answers are really quite close to correct.

Then again, who has to answer a Architectural Question in their business careers in less than 2.5 minutes on average, really?

On to the next step, the Assignment!!

The exam

Most of the exam questions were regarding business use cases.

The exam questions can be broadly separated into three distinct categories:

use cases

of imaginary companies seeking to change/re-evaluate (a part of) their current outdated infrastructure in some fashion

questions on design patterns

when to use them, what their characteristics are, etc. ^*)

questions on JEE technologies

when would you apply which technologies, given some Non-Functional Requirements (NFR)

*) Seems the books "Core J2EE Patterns", "Real World Java EE Patterns: Rethinking Best Practices" and "Design Patterns: Elements of Reusable Object-Oriented Software" really did help, and were fascinating reads in and of themselves.

References

[1] 1Z0-807 Java EE 6 Enterprise Architect Certified Master Exam

http://education.oracle.com/pls/web_prod-plq-dad/db_pages.getpage?page_id=5001&get_params=p_exam_id:1Z0-807

[2] Architect Enterprise Applications with Java EE - Course

http://randomthoughtsonjavaprogramming.blogspot.nl/2013/09/architect-enterprise-applications-with.html

Red Soup

Recently had a real life experience that I could map to Software Design.

Occasionally, I or one of my colleagues gets beverages for everyone. The scheduling is: the one who wants to have a beverage gets some for the rest as well and queries their preference beforehand.

In this case, the job landed on one of my colleagues.

The conversation went something like:
Guy1: What would you like?
Me: I'd like some Red Soup.
Guy1: What kind of Red Soup?
Me: Red Soup! You're the Factory, figure it out.
Me: Convention Over Configuration!
Guy2: Should he draw you an UML diagram? As long as it implements or extends RedSoup.
Guy1: With Cream?
Me: That's an implementation detail. Not interested! Red Soup! Go!

It left me in stitches, I'm geeky like that.

(added an overview of the different arrows in UML. I always get confused.)

Architect Enterprise Applications with Java EE - Course

I had the opportunity to attend the Oracle course on "Architect Enterprise Applications with Java EE"^[1] from Monday 09/09/2013 to Friday 13/09/2013. (after forking over a big sack of money)

The Course does have a number of Lab exercises, mostly based on UML or open questions (that created several discussions, which I enjoyed immensely). UML diagrams were drawn using UMLet^[3].

I took the course as I wish to prepare for the 'Oracle Certified Master, Java EE 6 Enterprise Architect' certification.

This is the first step in the Certification Process ^[2].

I did receive some very interesting Course material along with it. However, it's been licensed to me specifically. (I could let you read it, but then I would have to kill you. Oracle licensing rules say so.)

References

[1] Architect Enterprise Applications with Java EE

http://education.oracle.com/pls/web_prod-plq-dad/ou_product_category.getAllProductsPage

[2] Oracle Certified Master, Java EE 6 Enterprise Architect

http://education.oracle.com/pls/web_prod-plq-dad/db_pages.getpage?page_id=458&get_params=p_track_id:OCMJEE6EA

[3] UMLet

http://www.umlet.com/

PlantUML and NetBeans

If you're looking to integrate PlantUML with Netbeans with Maven, check out my blogpost here.

Introduction

One of the problems with software designers is that they do not enjoy writing Documentation. I do, but then again, I'm weird.

Now Documentation in the area of Java can be split up into two categories:

• Javadoc comments, that reside in the Java source code, right where it matters
• Specs, design documents, etc. which are made when the system is first designed and are then stored on a network drive or (if you're lucky) a version control system. They are never updated, become outdated, and forgotten but are sometimes used to provide new junior designers with a wrong idea of the architecture.

So, ideally, you'd wish to have all the specs on hand in the same fashion as your javadoc, with the hope that any change in the code by dilligent designers is also propagated in the javadoc.⁶

This is where I find PlantUML¹ to be extremely handy.

Installing PlantUML in Netbeans

The following task addition lifted straight from the pages of PlantUML and added to build.xml in the netbeans project.

<!-- task definition -->
<taskdef name="plantuml"
  classname="net.sourceforge.plantuml.ant.PlantUmlTask"
  classpath="plantuml.jar" />

<!-- process ./src files -->
<target depends="javadoc-build" name="build-uml">
    <mkdir dir="${dist.javadoc.dir}/images"/>
    <!-- there is an issue where relative paths do not work -->
    <plantuml output="/home/mrbear/NetBeansProjects/YourProject/${dist.javadoc.dir}/images/" verbose="true">
        <fileset dir="./src">
            <include name="**/*.java" />
            <exclude name="**/*Test.java" />
        </fileset>
    </plantuml>
</target>

This won't work, as plantuml.jar cannot be found automatically. Once you've downloaded it you can let your project know where it is. A good explanation of this can be found at [3].

Running PlantUML and Javadoc

First of all, we add the uml syntax² to the javadoc comments.

/**
 *
 * <p>Indicates the different sizes that are possible in the displaying
 * of pictures. BIG being un-scaled.</p>
 * <img src="../../images/ImageSize.png"/>
 * @author maartenl
 *
 * @startuml
 * "java.lang.Enum<ImageSize>" <|-- enum ImageSize
 * ImageSize : +ImageSize BIG
 * ImageSize : +ImageSize LARGE
 * ImageSize : +ImageSize MEDIUM
 * ImageSize : +ImageSize THUMB
 * ImageSize : +getHeight()
 * ImageSize : +getWidth()
 * @enduml
 */
public enum ImageSize
{

Build the "build-uml" target. It will automatically generate all the javadocs and start off generating uml diagrams. You can do this in the Files explorer in netbeans, right-click on build.xml on toplevel and select the appropriate run target. When the "build-uml" ant target is started in netbeans, the following output is shown:

main:
Starting PlantUML
Nb images generated: 1
BUILD SUCCESSFUL (total time: 0 seconds)

The webpage will look like the image below!^[5] Voilà, uml diagrams!

Issues

- Two files have the same name, so they both create the same named image file. And they get copied in the ant task, so only one of them remains!

The easiest solution is to add a filename after the "@startuml" command, to indicate the name of the image. This is especially important if you have two or more diagrams within the same Java file. I found it especially convenient when dealing with UML diagrams in package-info.java files.

A better solution would be to update the Ant task to take care of this automatically.

- I'm getting "taskdef class net.sourceforge.plantuml.ant.PlantUmlTask cannot be found using the classloader AntClassLoader[]"!

Make sure the plantuml.jar file is reachable in the classpath.

- Auto formatting in Netbeans of my Java source code throws my carefully created UML specs in the Javadoc into disarray!

Yes, while Eclipse has a /* @formatter:on */ editor annotation, I have been unable to find the same in Netbeans.

For now, the only solution I have found it to turn on 'explicit newlines' in formatting of the javadoc comments. You can do this by going in Netbeans to Tools->Options->Editor->Formatting->select Java->Category Comments and turn on "Preserve New Lines".

- The image shows errors, something like the image below.

Dot Executable: /usr/bin/dot
File does not exist
Cannot find Graphviz. You should try

@startuml
testdot
@enduml

or

java -jar plantuml.jar -testdot

It means you haven't installed the graphviz⁴ package that takes care of a lot of rendering.

root@localhost:~# apt-get install graphviz
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following extra packages will be installed:
  libcgraph5 libgvpr1
Suggested packages:
  graphviz-doc
The following NEW packages will be installed:
  graphviz libcgraph5 libgvpr1
0 upgraded, 3 newly installed, 0 to remove and 197 not upgraded.
Need to get 553 kB of archives.
After this operation, 1,741 kB of additional disk space will be used.
Do you want to continue [Y/n]? y
Get:1 http://nl.archive.ubuntu.com/ubuntu/ natty/main libcgraph5 i386 2.26.3-5ubuntu1 [47.8 kB]
Get:2 http://nl.archive.ubuntu.com/ubuntu/ natty/main libgvpr1 i386 2.26.3-5ubuntu1 [198 kB]
Get:3 http://nl.archive.ubuntu.com/ubuntu/ natty/main graphviz i386 2.26.3-5ubuntu1 [307 kB]
Fetched 553 kB in 0s (563 kB/s) 
Selecting previously deselected package libcgraph5.
(Reading database ... 163396 files and directories currently installed.)
Unpacking libcgraph5 (from .../libcgraph5_2.26.3-5ubuntu1_i386.deb) ...
Selecting previously deselected package libgvpr1.
Unpacking libgvpr1 (from .../libgvpr1_2.26.3-5ubuntu1_i386.deb) ...
Selecting previously deselected package graphviz.
Unpacking graphviz (from .../graphviz_2.26.3-5ubuntu1_i386.deb) ...
Processing triggers for man-db ...
Setting up libcgraph5 (2.26.3-5ubuntu1) ...
Setting up libgvpr1 (2.26.3-5ubuntu1) ...
Setting up graphviz (2.26.3-5ubuntu1) ...
Processing triggers for libc-bin ...
ldconfig deferred processing now taking place

Thank the Heavens that I'm still running an old Ubuntu, that downloads the proper (read: old) version of GraphViz. PlantUML, I hear, has issues with the new and improved GraphViz 2.28. ^{1 2}

Unfortunately, I was unable to use a relative path in the output attribute in the build.xml. I hope I can fix this later.

Update: changed ImageSizeEnum to ImageSize. Naming should not contain data type names, according to uncle Bob.

Second Update: PlantUML according to this now works with the newest Graphviz version.

Third Update: Updated NetBeans javadoc formatting problem with a better solution.

References

[1] PlantUML

http://plantuml.sourceforge.net/

[2] Drawing UML with PlantUML - Language Reference Guide (Version 5737)

http://sourceforge.net/projects/plantuml/files/PlantUML%20Language%20Reference%20Guide.pdf/download

[3] NetbeansFAQ

http://wiki.netbeans.org/FaqAntJunitJar

[4] Graphviz

http://www.graphviz.org/

[5] Example

http://maartenl.github.com/YourPersonalPhotographOrganiser/javadoc/gallery/enums/ImageSize.html

[6] "To keep documentation maintained, it is crucial that it be incorporated in the source program, rather than kept as a separate document ... even high-level language syntax does not at all convey purpose." [DRY principle]

The Mythical Man-Month (Frederick P. Brooks, Jr.)