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

The Pitfalls of Boolean Trap

A colleague is looking to update all inspections in IntelliJ at work, which is commendable.

He referred a link, see [1], to me regarding the use of Booleans as method parameters ("switches"), which is a pet peeve of another colleague of mine.

I thought I'd just mention it here, for who's interested.

References

[1] The Pitfalls of Boolean Trap

https://ariya.io/2011/08/hall-of-api-shame-boolean-trap

Unit Testing vs. Integration Testing

I was talking with a colleague on the way home, when we started talking about his troubles with his bike.

In short, he could turn the pedals like crazy, and the bike was not moving an inch.

That's when I realized that this is a perfect example of the difference between Unit Testing and Integration Testing.

In short:

unit test

write a unit test, to see if we can properly turn the pedals in the proper direction.

Conclusion: Success! Software works fine. In fact it works extremely well. We achieved a performance increase of over 500%! Yay!

integration test

write an integration test, to see if when we turn the pedals, the bicycle will move.

Conclusion: Failure! Pedals turn fine, but the bicycle doesn't move.

It turns out the integration between the component "pedals" and the component "wheels" was busted.

It totally shows that though Unit tests may all pass, it is not a guarantee that your software is actually doing what it should.

Lesson learned.

Abuse of Lambdas

So, sometimes when you have an existing software structure, with lots of domain rules inside, it becomes difficult to change. Especially when there is a lot of cohesion between your classes.

This is the problem of tight coupling, as opposed to loose coupling¹.

I recently encountered this in our software.

And of course, I needed to change something deep inside.

Now, I didn't need to change anything about the domain logic. It was very good and working as intended.

But I needed a change purely for technical reasons. In this case, the domain logic was used in a Batch Processing on Hibernate Entities, and the domain logic was (in this case, not normally) generating a lot of Entities, and they were all persisted in the Session Context, which naturally grew. And then the dirty check and the session closing takes a long time, etc, etc. See reference [2] on why this's bad.

So I was looking for a way to persist entities, without adding them to all the collections with the CascadeType without changing the domain logic too much, and also keep the default behaviour as standard.

I didn't want to use inheritance, as it was a persisted Hibernate Entity.

So, I came up with the following hack:

Quite simply, I can now add behaviour to an Entity when I need it.

For example:

As me and my colleague say "A seemingly innocent first step on a slippery slope to hell."

Of course, this kind of abuse has always been possible, but it is now easier to do than ever (without having to create an entire class for the priviledge).

References

[1] Wikipedia - Loose coupling

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

[2] Vlad Mihalcea - The best way to do batch processing with JPA and Hibernate

https://vladmihalcea.com/the-best-way-to-do-batch-processing-with-jpa-and-hibernate/

Proper use of Optional

Using Optional is hard in the beginning.

Especially for first-timers one has a tendency to use the wrong methods.

Take the following sequence of refactoring for example:

First without any kind of Optional:

A first bad attempt at an optional:

It looks like the person just... kind of removed the Optional back to a situation that he knew and was more familiar with.

Let's try this again:

Now this is a good try. It is very common to see the two Optional class methods being used together. isPresent() and get().

But we can do better.

It's often the same: we wish to do something, only when there's a value available.

Like so:

Of course, it's sometimes better to create a method reference:

But I do find this proliferates the number of methods, but it's an acceptable side effect.

We finally arrive at something concise and easy to read, once you get the hang of it.

On Rewriting Software

I came across the reference¹ below on "rewriting" software, and it struck a cord with me.

Turns out that, as is so often the case, the fact where "you should never ever do that"² has its successful exceptions.

References

[1] Lessons from 6 software rewrite stories

https://medium.com/@herbcaudill/lessons-from-6-software-rewrite-stories-635e4c8f7c22

[2] Joel Spolsky - Things You Should Never Do, Part I

https://www.joelonsoftware.com/2000/04/06/things-you-should-never-do-part-i/

Attending Devoxx Belgium 2018

I shall be attending the Devoxx Belgium 2018 Java Conference in Antwerp, from 12th - 16th of November 2018.

My first time.

References

Devoxx Belgium 2018

https://devoxx.be/

Mutable members should not be stored or returned directly

But SonarLint is complaining about it, so I refactored it into this:

It's high time this old codebase gets converted to LocalDates.

References

SonarSource - RSPEC-2384

https://rules.sonarsource.com/java/RSPEC-2384

Java Language Futures: 2018 edition

On Monday, 23 April 2018, in the evening, I was attending two talks by Brian Goetz, Oracle Language Architect, at the Werkspoorkathedraal in Utrecht. The talk was made possible with the help of several parties, for example JPoint² and Code Nomads³.

First talk - On Software Design

This first talk was not about technical details, but more about us software designers as a group, and how we tend to be tribal like the rest of the Human Race. Our tribes are split up upon the lines of programming languages, editors, software paradigms, layout, etc.

From an evolutionary standpoint this has always been a good idea, to protect the group, from predators and other software designers. Currently, it will limit us in our way of thinking, in trying new ideas (generated "outside the tribe") and promotes right-wrong judgmental thinking, etc.

All the energy that is spent condemning other practices of software design, can be better spent on becoming a better software designer.

Most users of software do not care about software design, they care about working programs.

Software design

When comparing Functional Programming to Object Oriented Design, what immediately stands out is that Objects are a bit more ambitious compared to Functions. Functions are derived from the Procedural way of programming.

Every programming language has a "Everything is an object|function|file|thingamabob", and that works for 5 minutes, and then it becomes impractical.

A lot of programming paradigms have always been quickly hailed as the solution to all our problems. So far this has not worked out. Every programming paradigm must be seen as another tool in the software designers toolbox.

One of the more interesting questions of course is when should you apply what. I think that is where the good software designer can stand out from the rest. Brian mentioned that, in the case of object oriented versus functional, the functional is a good fit for business logic, where the object oriented is a good fit for everything surrounding the business logic, for example databases and IO.

Second Talk - All Aboard Project Amber

The second talk went quite in-depth into the new features of project Amber⁴ and also the problems associated with changing an old language that everyone is using, without everyone trying to hang the Language Architect. As well as how to decide what new features to add, how easy they are to add, and how much use they would be.

What was interesting was to see the area each JDK focused on, the following list was mentioned:

JDK 5

rebooting data abstraction (by means of Generics)

JDK 8

rebooting behavioural abstraction (by means of Lambdas)

JDK 9

rebooting configuration and encapsulation (by means of Modules)

Java Language Principles

He mentioned his favorite sheet, which looked like this:

• code should be a joy to read
• the language should not hide what is happening
• code should do what it seems to do
• a clear semantic model greatly boosts reusability
• every good feature adds more bad weight
• sometimes it is best to leave things out

General rule: type inferences is ok in implementation not in APIs.

Naming is the single most expressive place to indicate to our audience what our program is.

Raw string literals

It will be possible to use backticks to indicate a beginning and an end of a string. Everything in between will be treated as raw information.

Product types

It is a class that only contains data, for example:

record Point(int x, int y)

You could call them Plain Old Data Objects - PODOs

Disclaimer: uh, the abbreviation PODO is mine, and not Brians.

Records are like Enums, in that you decide to give up some things, and in return you get reliable defaults.

Sum types

The possibility to limit the amount of subclasses, by means of a sealed Interface. For example:

sealed Interface Shape;

record Point(int x, int y);

record Circle (Point center, int radius) implements Shape;
record Rect (Point 11, Point ur) implements Shape;

Pattern matching and the improved switch

The switch statement has always been very limiting to Strings and primitive data types.

That is why usually you had to use the Visitor⁵ pattern to get anything complex done.

Im going to have to point you to documentation that explains this a lot more in depth, than I can in this blog^{6, 7}.

Conclusion

Brian talked about a lot of things, some of which I have endeavoured to transcribe here. I enjoyed listening to him immensely as he is a captivating speaker, who seems to really know what works and what not in the realm of programming languages.

Brian is a big proponent of the new Java release cadence, and what it has to offer for us software designers.

Choice quotes

I always enjoy hearing pithy comments. Somewhere along the talk, he mentioned these gems:

“Homomorphism : the translation from real world to software applications (or vice versa), where all the relations stay intact. It does not work, because inevitably information is lost during the transformation.”

- Brian Goetz

“It's very common for software designers to have opinions on things they know nothing about.”

- Brian Goetz

“Nothing is more dangerous than an idea, if it's the only idea you have.”

- Émile Chartier

“Sorcerers Apprentice Objects.”

- Brian Goetz - on classes created when you are still learning the language

“Actually I made up the term object oriented and I can tell you that I did not have C++ in mind.”

- Alan Kay

“We write in C++ so you don't have to.”

- JVM software designers.

References

[1] Brian Goetz

https://www.linkedin.com/in/briangoetz

[2] JPoint

https://www.jpoint.nl/

[3] Code Nomads

https://www.codenomads.nl/

[4] Openjdk - Project Amber

http://openjdk.java.net/projects/amber/

[5] Wikipedia - Visitor Pattern

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

[6] JEP 305 - Pattern matching

http://openjdk.java.net/jeps/305

[7] JEP 325 - Switch expressions

http://openjdk.java.net/jeps/325

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

The Dangers of Optional.orElse

Our architect at work explained how to properly use the Optional class, and sometimes it is not easy. I shall explain one of the intricaties in this blog with the aid of Cake, because who doesn't love cake?

Now some people tell me that the cake is a lie^{1 2}. Now, this may or may not be the case. So there may or there may not be cake.

This is basically the definition of the Optional² class in Java 8.

Optional<Cake> cake;

One of my colleagues is a fan of Eddie Izzard^{4 5}.

Our architect at work presented us the code he encountered of the Optional.orElse. I've changed it a bit by adding more cake.

If you run this program, you'll notice that after you have received a nice cake, you immediately die!

This is due to the fact that the expression in the .orElse is immediately evaluated after the new Cake(). This is very basic Java and what is to be expected.

Unfortunately, we software designers seem to have a blind spot, when it comes to the orElse() method. We automatically compare it to the if-else construction we know and love, and then we assume the behaviour is the same.

It is as if your brain automatically shunts over to the wrong abstraction.

The .orElse() is actually only suitable for constants.

Conclusion

In order to fix the problem, you need to use a lambda. To use a lambda, you need to use a different method of the Optional class, namely .orElseGet().

The code would look as follows:

    cake.orElseGet(this::death);

I had really hoped, that they would have changed the method name to something better. Some notable good examples would have been:

• "orElseConstant"
• "orDefault"

References

[1] Know Your Memes - The Cake is a Lie!

http://knowyourmeme.com/memes/the-cake-is-a-lie

[2] Wikipedia - Portal (video game)

https://en.wikipedia.org/wiki/Portal_(video_game)

[3] Oracle Javadoc - Optional

https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html

[4] Wikipedia - Eddie Izzard

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

[5] Youtube - Eddie izzard-cake or death

https://www.youtube.com/watch?v=BNjcuZ-LiSY

Creating special F dependent on class A

Current situation:

New situation required:

We don't wish to touch the intervening classes, as they are called from different parts of the application for different reasons.

Solutions:

1. provide a boolean flag all up/down the chain
2. provide a "nicer" boolean flag, for example an enum or a Factory that determines which f should be created
3. use a static flag in f2, in class a2 just set the flag appropriately -> completely unthreadsafe.
4. use the ThreadLocal storage to store the boolean in a/a2 and read it in f/f2.
5. in e -> call up the stacktrace and check for the existence of class a2.
6. in e -> throw exception, call up the stacktrace and cehck for the existence of class a2.

However, the underlying problem is of course, that the two classes are too far apart, and there is too much tight coupling between the intervening classes and the rest of the system.

Also, the whole problem might go away with Functional Programming, but I'm not sure about that.

What do the experts say?

A little Architecture Lesson

I found this blogpost:

http://blog.cleancoder.com/uncle-bob/2016/01/04/ALittleArchitecture.html

I think I still have a lot to learn.

Abstraction Considered Harmful

One of the more thought-provoking pieces I have read in a long time, and one I happen to fully agree with, having seen myself what too much Abstraction can lead to:

http://bravenewgeek.com/abstraction-considered-harmful/

I like the quote:

“duplication is far cheaper than the wrong abstraction”

Calling super constructors

So, a constructor in a subclass, if it needs to call the constructor in the super class, is required to do this in the first line of the body of the constructor¹.

If it does not, Java will insert a call to the default super constructor. If it does not exist, you get a compile time error.

So, what if you need to do things, before the super call takes place?

As the object is in the process of being constructed (that's why it's called a constructor), the object is in a non-valid state. This likely explains why the language designers felt that a call to another constructor should be the first part of the body of a constructor.

Well, apparently the only solution is to do everything you need inside the expressions that take the place of the super constructor arguments.

I was forced to do just that in my MudWebException.

So, there's an easy workaround, but it feels clumsy.

Take care not to access any of the methods or properties of the object that is being constructed, as it is in a non-valid state. As a matter of fact, I think it's a really bad idea to call methods in the object from within your constructor.

References

[1] JLS 8.0 Section 8.8.7. Constructor Body

https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#d5e14100

StackOverflow - Why does this and super have to be the first statement in a constructor?

http://stackoverflow.com/questions/1168345/why-does-this-and-super-have-to-be-the-first-statement-in-a-constructor

Should I use an ORM?

Martin Fowler has a very nice article about why you should use an ORM, when you should not, and what alternatives there are.

See http://martinfowler.com/bliki/OrmHate.html.

Of course, as I have often said (but not always, never always), think before you blindly pick something to use. Is it appropriate? Is there something better?

My Enum Frustration

At work, there is a bit of Legacy around.

The following example of several Enum classes we have, is what is currently frustrating me (and I try actively to change them).

Let's enumerate (oh, look, I made a joke) the issues:
Replacing magic numbers with constants and enums is, of course, one of the Good Things^tm.

But in this example, they seem to have totally missed the point.

Not only have they replaced magic numbers with "magic enums", it's an eyesore to use the underscore in the Enum instances.

When you have to take refuge in the use of underscores to make things work, it is a sure sign that you are doing something seriously wrong.

getAsModifableSet()

At work we have taken great care to limit access to a Set of values, as elements of the set have constraints between each other, that need to be sustained.

So any call to retrieve a set, is always done using Collections.unmodifiableSet.

public Set<T> getCycles() 
{
  return Collections.unmodifiableSet(cycles);
}

I would have been much more at ease, if we had also decided to make the elements of the set Immutable Objects, but alas, this is the status quo.

As it is right now, it's possible to change the attributes of the individual elements, and so break the constraints between them.

Surprise

Imagine the surprise of my colleague, when, out of nowhere, he found the following method:

public abstract SortedSet<T> getAsModifableSet();

The typo in the name is actually in the code, I swear! My grasp of the intricacies of spelling is beyond reproach.

And it returns a very implementation-specific Set as well.

And it's public too.

I'm sure there are always good reasons for these things, but sometimes I'd like to run my head into a wall.

Successfully completed Functional Programming Principles in Scala

I earned 97.7% with distinction.

Evaluation

One can tell that the subject matter was Academic, with a firm grounding in Mathematics, which appealed to me.

The assignments provided a lot of information on what is expected, so there are no surprises, but you do need to read carefully.

The one assigment that provided the most difficulty was assignment 6, regarding the discovery of Anagrams of a sentence.

I had to wrestle a bit with the Scala syntax. It's new for me.

I especially found foldLeft and foldRight counter-intuitive sometimes.

I learned a lot on the following topics, in no specific ordering.

Scala Programming Language

by the creator, Martin Odersky, himself.

Functional Programming

one of the main subjects of the course

Domain Specific Language

Scala provides several ways to program according to a domain model², instead of a technical/software model

Mathematics - Set Theory

the code is very close to the mathematical theory. Purposefully crafted that way, of course. It means we can actually use mathematical operators (some of the time).

Behaviour Driven Development

you can write tests that read more naturally

Test Driven Development

assignments had to pass certain tests (that are unknown), so your own tests had better be complete/sufficient

Recursion

we used a lot of recursion, you do not see that in "normal" programming languages.

It was a huge amount of fun to do, both to learn a new Programming Language¹ and to learn a new Programming Paradigm.

References

[1] Coursera - Functional Programming Principles in Scala, by Martin Odersky

https://class.coursera.org/progfun-004

[2] Wikipedia - Domain Model

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

Coursera - Functional Programming Principles in Scala

On the 25th of April, meaning this Friday, I start my course on Scala.

I found Coursera¹, an education platform that partners with universities to provide courses online for free.

I am really excited in finding out how Scala differs from Java, and what new programming methods I'll learn.

The fact that the Course² has been set up by the creator of the language, Martin Odersky of École Polytechnique Fédérale de Lausanne, is a big plus.

I hope I can meet the deadlines.

References

[1] Coursera

https://www.coursera.org/

[2] Coursera - Functional Programming Principles in Scala

https://www.coursera.org/course/progfun