Java code generation with JAnnocessor

Background

Every Java developer uses some sort of code generation tool on a daily basis. Setters, getters, trivial constructors, toString – all of these is just a boilerplate code. Usually we generate it with our favorite IDE’s help. I can’t really imagine coding it manually and because Java is a static language we will never be able to skip this process.

Those trivial examples of code generation provided by all modern IDEs are not the only situations when code generation is useful. There are many modern frameworks generate some code to help us to write more reliable code and do it faster. I think the most well known examples are QueryDSL and JPA2 Metamodel Generator that creates objects used to perform type-safe database queries.

There are also other situations – not so well supported by IDE – where we could use code generation. Usually it might be helpful in generating:

• builder
• facade
• DTOs and mappers from domain objects to DTOs

These are only examples. For some projects there might be something project specific where we can’t use any existing code generation tool and we have to write our own. How to do that? With Java APT – Annotation Processing Tool.

Few words about Java APT

Annotation Processing Tool was introduced in Java 1.5 and provides low level API for processing annotated classes. It is a base for most (maybe all?) existing code generation frameworks and because of really low level API I don’t recommend using plain Java APT if you just want to generate some classes. How creepy is code generation with APT look at example on apt-jelly (another code generation tool) page.

Instead of using plain Java APT – you can use one of existing frameworks. Recently I’ve attended to conference talk about interesting JAnnocessor that seems to do its job pretty well.

Hello JAnnocessor

JAnnocessor is a quite new framework made by Nikolche Mihajlovski. How is it different from APT? Here is how author what author says:

JAnnocessor is built on top of Java APT, encapsulating the Java source code model in a rich and convenient high-level domain model that serves as a good target for expressive matching and transformation.

JAnnocessor comes with couple of built in processors: builder, dto, facade and mapper. If you need custom functionality you can easily write it by your own.

There is one big drawback – very very poor documentation. Actually there is almost no documentation at all. In wiki you won’t find too much and what is even worse – you won’t find Javadocs in framework classes neither. Although there is Getting Started Guide written by author I miss there some points so I will guide you through basics step by step.  

Maven setup

We will use JAnnocessor only during compile phase so there is no need to add it into our application package – we set scope to provided

<dependency>
    <groupId>com.googlecode.jannocessor</groupId>
    <artifactId>jannocessor</artifactId>
    <version>0.7.2</version>
    <scope>provided</scope>
</dependency>

Next part is annotation processing plugin. Although Getting Started Guide recommends to use jannocessor-maven-plugin I was forced to do it “old fashioned way” with maven-processor-plugin because I missed some configuration options.

Into build/plugins section we add:

<plugin>
	<groupId>org.bsc.maven</groupId>
	<artifactId>maven-processor-plugin</artifactId>
	<version>2.0.4</version>
	<executions>
		<execution>
			<id>generate-code</id>
			<goals>
				<goal>process</goal>
			</goals>
			<phase>compile</phase>

			<configuration>
				<processors>
					<processor>org.jannocessor.processor.JannocessorProcessor</processor>
				</processors>

				<systemProperties>
					<logback.configurationFile>${project.basedir}/etc/jannocessor-logback.xml</logback.configurationFile>
				</systemProperties>
				<options>
					<templates.path>${project.basedir}/src/main/resources</templates.path>
				</options>
				<defaultOutputDirectory>${project.basedir}/target/generated-sources/</defaultOutputDirectory>
			</configuration>
		</execution>
	</executions>
</plugin>

• processors – tells maven-processor-plugin which class performs annotation processing – don’t change it
• configuration/logback.configurationFile – that’s optional. JAnnocessor uses inside logback for logging and if you do so as well in your project and you have logback.xml in classpath it is going to be used by JAnnocessor. I recommend to write separate logging configuration for JAnnocessor to avoid possible problems (for example if you use janino conditionals). jannocessor-logback.xml can be as simple as:

  <?xml version="1.0" encoding="UTF-8"?>
  <configuration>
  
  	<appender name="console" class="ch.qos.logback.core.ConsoleAppender">
  		<encoder>
  			<pattern>%-30(%date) %-5level %logger{0} %msg%n</pattern>
  		</encoder>
  	</appender>
  
  	<root level="error">
  		<appender-ref ref="console"/>
  	</root>
  
  </configuration>
  

• options/templates.path – probably you will use custom JAnnocessor templates. That line can be removed if you won’t
• defaultOutputDirectory – that’s important – by default generated classes are added to src/main/java – which is in my opinon very bad idea. Remember that all generated classes are recreated every Maven build and all modifications made by hand are lost. That’s why generated classes should be places in /target/generated-sources/ or /target/generated-test-sources/

Builder generation

In this example I will use built-in generator to generate builder class for my simple POJO.

First of all we need new annotation to mark classes for whom we want to generate builder. It can be as simple as:

package pl.maciejwalkowiak.jannocessor.domain;

public @interface GenerateBuilder {
}

Our sample POJO:

package pl.maciejwalkowiak.jannocessor.domain;

@GenerateBuilder
public class Person {
	private String firstName;
	private String lastName;
	private Integer age;

	public String getFirstName() {
		return firstName;
	}

	public void setFirstName(String firstName) {
		this.firstName = firstName;
	}

	public String getLastName() {
		return lastName;
	}

	public void setLastName(String lastName) {
		this.lastName = lastName;
	}

	public Integer getAge() {
		return age;
	}

	public void setAge(Integer age) {
		this.age = age;
	}
}

Next important part is to tell JAnnocessor what has to be generated. In order to do that we need to create specific class in specific package: org.jannocessor.config.Processors. I couldn’t find a way to make it configurable so that configuration could be in our project’s package.

In configuration we specify where created classes should be placed: pl.maciejwalkowiak.jannocessor.domain.builder and where are base bean classes: pl.maciejwalkowiak.jannocessor.domain. Last parameter means if we want to use debug mode – for now it isn’t important.

package org.jannocessor.config;

import pl.maciejwalkowiak.jannocessor.domain.GenerateBuilder;

import org.jannocessor.extra.processor.BuilderGenerator;
import org.jannocessor.model.structure.JavaClass;
import org.jannocessor.processor.annotation.Annotated;
import org.jannocessor.processor.annotation.Types;

public class Processors {

	@Annotated(GenerateBuilder.class)
	@Types(JavaClass.class)
	public BuilderGenerator generateBuilder() {
		return new BuilderGenerator("pl.maciejwalkowiak.jannocessor.domain.builder", "pl.maciejwalkowiak.jannocessor.domain", false);
	}
}

Let’s run it

In order to run it we just need to execute mvn compile. In target/generated-sources/pl/maciejwalkowiak/jannocessor/domain/builder/ we will find class PersonBuilder:

package pl.maciejwalkowiak.jannocessor.domain.builder;

import pl.maciejwalkowiak.jannocessor.domain.Person;
import javax.annotation.Generated;

/**
 * Generated by JAnnocessor
 */
@Generated("Easily with JAnnocessor")
public class PersonBuilder {

    private String firstName;

    private String lastName;

    private Integer age;

    public PersonBuilder firstName(String firstName) {
        this.firstName = firstName;
        return this;
    }

    public PersonBuilder lastName(String lastName) {
        this.lastName = lastName;
        return this;
    }

    public PersonBuilder age(Integer age) {
        this.age = age;
        return this;
    }

    public Person build() {
        Person instance = new Person();

        instance.setFirstName(firstName);
        instance.setLastName(lastName);
        instance.setAge(age);

        return instance;
    }

}

Thanks to builder class we have fluent interface for creating Person objects:

Person person = new PersonBuilder().firstName("John").lastName("Doe").age(25).build();

Creating our own generator

For creating custom generators JAnnocessor provides rich API and couple of examples. Unfortunately there is no guide or tutorial available. For this article I wanted to write quickly generator for FEST Assert 2.x but after some time digging in JAnnocessor source code I gave up. Instead I will just show concept.

In order to code custom generator you just need to create class that inherits from org.jannocessor.extra.processor.AbstractGenerator.

public class MyCustomGenerator extends AbstractGenerator<AbstractJavaClass> {

	public MyCustomGenerator(String destPackage, boolean inDebugMode) {
		super(destPackage, inDebugMode);
	}

	@Override
	protected void generateCodeFrom(PowerList<AbstractJavaClass> models, ProcessingContext context) {
		// ....
	}
}

PowerList<AbstractJavaClass> models represents collection of all classes annotated with custom annotation. Then you have access to all class fields, methods, implemented interfaces etc. The only thing that I missed is rich access to classes superclass. In order to get superclass’ fields I had to use Java Reflection API.

If you want to write custom generator I encourage you to look into examples like BuilderGenerator. It’s not much but it will be definitely helpful.  

Summary

In this post I’ve shown how to setup and use JAnnocessor. Although I think its good and possibly very useful library, lack of documentation makes it impossible to use it in real serious project. I hope Nikolche will write good docs or build community around project that will do it. I also hope that project will move to github. It somehow become a standard so if author want’s to build community around it – I think it is the only right move. Nevertheless I asked him about that and at least for now he doesn’t have any plans to do so.

Reference: Java code generation with JAnnocessor from our JCG partner Maciej Walkowiak at the Software Development Journey blog.