Monday, 26 September 2016

Java has long suffered from the pain of beans.
To declare a simple data class takes far too much code.
At JavaOne 2016, I talked about code generation options - see the slides.

Code generation of mutable and immutable beans

The Java ecosystem is massive. So many libraries releasd as open source and beyond, which naturally leads to the question as to how those libraries communicate. And it is the basic concept of beans that is the essential glue,
despite the ancient specification.
How do ORMs (Hibernate etc.), Serialization (Jackson etc.) and Bean Mappers (Dozer etc.) communicate? Via getters and setters.

The essential features of beans have moved beyond the JavaBeans spec, and are sometimes referred to as POJOs.
The features are:

Mutable

No-args constructor

Getters and Setters

equals() / hashCode() / toString()

But writing these manually is slow, tedious and error-prone.
Code generation should be able to help us here.

But should we be using mutable beans in 2016? No, no, no!

It is time to be writing immutable data structure (immutable beans).
But the only practical way to do so is code generation, especially if you want to have builders.

In my talk at JavaOne 2016, I considered various code generation approaches:

IDE code generation

This is fine as far as it goes, but while the code is likely to be correct immediately after generation, there is still no guarantee that the generated code will stay correct as the class is maintained over time.

AutoValue, Immutables and VALJOGen

These three projects -
AutoValue,
Immutables,
VALJOGen -
use annotation processors to generate code during compilation.
The idea is simple - the developer writes an abstract class or interface, and the tool code generates
the implementation at compile time. However, these tool all focus on immutable beans, not mutable
(Immutables can generate a modifiable bean, but it doesn't match the JavaBeans spec, so many tools will reject it).

On the up side, there is no chance to mess up the equals / hashCode / toString.
While the tools all allow the methods to be manually written if necessary, most of the time, the default is what you want.
It is also great not to have to implement the immutable builder class manually.

On the down side, you as the developer have to write abstract methods, not fields.
A method is a few more keystrokes than a field, and the Javadoc requires an @return line too.
With AutoValue, this is particularly painful, as you have to write the outline of the builder class.
With Immutables, there is no need for this.

Of the three projects, AutoValue provides a straightforward simple tool that works, and where the implementation class is hidden (package scoped).
Immutables provides a full-featured tool, with many options and ways to generate. By default, the implementation class is publicly visible and used by callers, but there are ways to make it package-scoped (with more code written by you). VALJOGen allows full customisation of the generation template.
There is no doubt that Immutables is the most comprehensive of the three projects.

All three annotation processing tools must be setup before use. In general, adding the tool to Maven will do most of the work (Maven support is good). For Eclipse and IntelliJ, these instructions are comprehensive.

Lombok

The Lombok project also uses annotations to control code generation.
However, instead of acting as an annotation processor, it hacks into the internal APIs of Eclipse and the Java compiler.

This approach allows code to be generated within the same class, avoiding the need for developers to work with an abstract class or interface. This means that instead of writing abstract methods, the developer writes fields, which is a more natural thing to do.

The key question with Lombok is not what it generates, but the way it generates it. If you are willing to accept the hacky approach, IDE limitations, and the inability to debug into the generated code, then it is a neat enough solution.

For Eclipse, Lombok must be installed, which is fairly painless as there is a GUI. Other tools require other installation approaches, see this page.

Joda-Beans

The Joda-Beans project takes a third approach to code generation.
It is a source code regenerator, creating code within the same source file, identified by "autogenerated start/end" comments.

Developers write fields, not abstract methods which is simpler and less code. They also generate code into the same class, which can be final if desired.

One key benefit of generating all the code to the same class is that the code is entirely valid when checked out.
There is no need to install a plugin or configure your IDE in any way.

Unlike the other choices, Joda-Beans also provides functionality at runtime.
It aims to add C# style properties to Java.
What this means in practice is that you can easily treat a bean as a set of properties, loop over the properties
and create instances using a standardized builder.
These features are the ideal building block for serialization frameworks, and Joda-Beans provides XML, JSON and binary serialization that operates using the properties, generally without reflection.
The trade off here is that Joda-Beans is a runtime dependency, so it is only the best option if you use the additional properties feature.

The Joda-Beans regenerator can be run from Maven using a plugin. If you use the standard Eclipse Maven support, then simply saving the file in Eclipse will regenerate it. There is also a Gradle plugin.

Comparing

Most of the projects have some appeal.

AutoValue is a simple annotation processor that hides the implementation class, but requires more code to trigger it.

Immutables is a flexible and comprehensive annotation processor that can be used in many ways.

Lombok requires the least coding by the developer, but the trade-off is the implementation via internal APIs.

Joda-Beans is different in that it has a runtime dependency adding C# style properties to Java, allowing code to reliably loop over beans.

My preference is Joda-Beans (which I wrote), because I like the fact that the generated code is in the same source file, so callers see a normal final class, not an interface or abstract class. It also means that it compiles immediately in an IDE that has not been configured when checked out from source control. But Joda-Beans should really only be used if you understand the value of the properties support it provides.

If I was to pick another tool, I would use Immutables. It is comprehensive, and providing you invest the time to choose the best way to generate beans for your needs, it should have everything you need.

Finally, it is important that readers have a chance to look at the code written and the code generated.
To do this, I have created the compare-beangen GitHub project.
This project contains source code for all the tools above and more, demonstrating what you have to write.

To make best use of the project, check it out and import it into your IDE. That way, you will experience what code generation means, and how practical it is to work with it. (For example, see what happens when you rename a field/method/class. Does the code generator cope?)

Summary

It is time to start writing and using immutable beans instead of mutable ones.
The Strata open source market risk project (my day job) has no mutable beans, so it is perfectly possible to do.
But to use immutable beans, you are going to need a code generator, as they are too painful to use otherwise.

This blog has summarised five code generators, and provided a nice GitHub project for you to do you own comparisons.

Note that I have chosen to use the full declaration, with "public" on all three methods even though it is not required.
I have argued that this is best practice for Java SE 8, because it makes the code clearer (now there are three types of method) and prepares for a time when there will be non-public methods.

Thus, methods can be public or private (with the default being public if not specified).
Private methods can be static or instance.
In both cases, the private method is not inherited by sub-interfaces or implementations.
The valid combinations of modifiers in Java 9 will be as follow:

public static - supported

public abstract - supported

public default - supported

private static - supported

private abstract - compile error

private default - compile error

private - supported

Private methods on interfaces will be very useful in rounding out the functionality added in Java 8.