Usage

This page describes how to use the BuilderGen API.

Intro

Now that your project is configured to use BuilderGen, let's have fun with it!

The API is quite simple :

• Add @Buildable to any class you wish.
• A builder is automatically created for this class.

Getting into details

Suppose you have a Person class, that you annotate with @Buildable:

@Buildable
public class Person {

    private final int age;
    private final String name;

    Person(String name, int age) {
        this.name = name;
        this.age = age;
    }
    // [...]
}

BuilderGen automatically generates a PersonBuilder, and you can now do the following:

PersonBuilder builder = PersonBuilder.create();
Person john42 = builder.name("John Smith").age(42).build(); // john42 has name "John Smith" and age 42.
Person john69 = builder.age(69).build(); // john69 has name "John Smith" and age 69.

You could also instantiate PersonBuilder using its public constructor : PersonBuilder builder = new PersonBuilder(); (matter of taste).

The @Buildable class should have at least one accessible constructor (public, protected, or default => not private).

@Build

If the class has multiple accessible constructors, you must annotate the one to use with @Build. An accessible constructor is any constructor that is not private.

@Buildable
public class Person {
    private final int age;
    private final String name;
    
    @Build
    Person(String name, int age) {
        this.name = name;
        this.age = age;
    }

    Person(int age) {
        this.name = "Anonymous";
        this.age = age;
    }
    // [...]
}

@Mandatory

If you want to enforce some constructor parameters so that the user won't forget to provide them to the builder, you should use the @Mandatory annotation on those parameters. This will add the parameter as a constructor parameter to the builder. Thus, the builder cannot be created without providing such mandatory parameters.

Notice that you can still change the mandatory fields, they are not final and you may call their setter methods.

Let's add some mandatory parameters to the Person class:

@Buildable
public class Person {
	private final int age;
	private final String name;
	private final String address;

	Person(@Mandatory String name, @Mandatory int age, String address) {
		this.name = name;
		this.age = age;
		this.address = address;
	}
    // [...]
}

The builder create() method now needs those parameters: PersonBuilder builder = PersonBuilder.create("John Smith", 42); builder.name("Joe Bar"); Person joe = builder.build();

You can also use the constructor: PersonBuilder builder = new PersonBuilder("John Smith", 42);

The Builder interface

All generated builders implement the Builder<T> interface, which defines a T build() throws Exception method.

If a @Buildable class declares a constructor that does not throw any checked exception, the generated builder implements the UncheckedBuilder<T> interface, which extends Builder<T> but defines a T build() method (ie, does not throw any checked exception).

Those interfaces allow you to manipulate builders in a generic way (for whatever crazy reason you might want to do this) :

public class BuilderInterfaceExample {
	public <T> List<T> buildMultipleInstances(Builder<T> builder, int numberOfInstances) throws Exception {
		List<T> instances = new ArrayList<T>();
		for (int i = 0; i < numberOfInstances; i++) {
			instances.add(builder.build());
		}
		return instances;
	}
	public <T> List<T> buildMultipleInstances(UncheckedBuilder<T> builder, int numberOfInstances) {
		List<T> instances = new ArrayList<T>();
		for (int i = 0; i < numberOfInstances; i++) {
			instances.add(builder.build());
		}
		return instances;
	}
}

More details

Please have a look at the @Buildable, @Build, Builder and UncheckedBuilder javadocs for more information.

You may also have a look at [how it works](How it works). Or even start contributing by creating issues as well as providing patches.