Groovy Goodness: Use Builder AST Transformation for Fluent API

Since Groovy 2.3 we can easily create a fluent API for our classes with the @Builder AST transformation. We can apply the annotation to our classes and the resulting class file will have all the necessary methods to support a fluent API. We can customize how the fluent API is generated with different annotation parameters. In Groovy code we already can use the with method to have a clean way to set property values or use the named constructor arguments. But if our classes need to be used from Java it is nice to give the Java developers a fluent API for our Groovy classes.

In the following sample we apply the @Builder annotation to a simple class Message with some properties. We leave everything to the default settings and then the resulting Message class file will have a new builder method that return an internal helper class we can use to set our properties. For each property their is a new method with the name of the property so we can set a value. And finally our class contains a build that will return a new instance of the Message class with the correct values for the properties.

If we want to change the names of the builder and build methods we can use the annotation parameters builderMethodName and buildMethodName:

We see that for each property a corresponding method is generated. We can also customize the prefix for the generated method name with the annotation parameter prefix. In the following sample we define the prefix assign for the method names:

Finally we can also include and exclude properties to need to be included or excluded from our fluent API. We use the annotation parameters includes and excludes to define the names of the properties. This can be a list or a comma separated list of names.

The @Builder AST transformation also checks if the @Canonical AST transformation is applied to a class. Any included or excluded properties defined in the @Canonical transformation are also included or excluded for the generated builder code.

We can define the SimpleStrategy strategy with the builderStrategy annotation parameter. Then the generated class will not have a separate inner helper builder class and build method. The default prefix is set to set, but we can change that if we want to:

We will see other feature of the @Builder annotation in future blog posts.

Code written with Groovy 2.3.

Original article

This entry was posted in Groovy and tagged , by mrhaki. Bookmark the permalink.

About mrhaki

My name is Hubert A. Klein Ikkink also known as mrhaki. I work at the great IT company JDriven. Here I work on projects with Groovy & Grails, Gradle and Spring. At JDriven we focus on SpringSource technologies. All colleagues want to learn new technologies, support craftmanship and are very eager to learn. This is truly a great environment to work in. You can contact me via Google+ or @mrhaki.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">