Software Component: Builder generator

This builder came forth from a need for a builder which would work the same as the one generated by a jaxb-module.

Yet another builder generator, but different

Below is a table with different builders and what support they have in comparison to this builder generator:

Builder	Fluent Prefix 'with'	Nested Builders	Builder inheritence	Remarks
lombok Builder	✔️			With the way lombok works implementing nested builders will not be supported
lombok SuperBuilder	✔️		✔️	With the way lombok works implementing nested builders will not be supported
Jilt				Does not follow javabean spec
Pojobuilder	✔️
Freebuilder		✔️		Requires interfaces instead of classes as the source for the builder
Immutables			✔️	Requires interfaces instead of classes as the source for the builder
RIGD-Loxia builder	✔️	✔️	✔️

Need a support for other styles, feel free to make an issue for this. If you want you can even make a PR for it.

Description

Generates Builder classes based on the @Builder annotation. The following are by default generated:

• fluent api with with prefix
• builder chaining
• builder inheritence
• builder copyOf method

See the Reference Guide for all supported features.

Usage example

Take for example the following structure of classes:

class Car {
        private String brand;
	private int numberOfDoors;
	private Engine engine;
	private List<Seat> seats;
}

class Engine {
	private String name;
	private int maxRPM;
}

class Seat {
	private String type;
}

If we would annotate all classes with the @Builder annotation we could use the following bit of code to create the Car class:

private Car createCar() {
	return new CarBuilder()
		.withBrand("Custom Made")
		.withNumberOfDoors(4)
		.withEngine()
			.withName("V7 refurbished")
			.withMaxRPM(7000)
		.end()
		.addSeats()
			withType("driver seat")
		.end()
		.addSeats()
			withType("front passenger seat")
		.end()
		.addSeats()
			withType("large back seat")
		.end()
		.build();
}

Installation using maven

Adding the dependency on the annotations

<dependency>
    <groupId>nl.loxia.builder.generator</groupId>
    <artifactId>annotations</artifactId>
    <version>${buildergenerator.version}</version>
</dependency>

Configuring APT for generating classes

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <annotationProcessorPath>
                <groupId>nl.loxia.builder.generator</groupId>
                <artifactId>builderGenerator</artifactId>
                <version>${buildergenerator.version}</version>
            </annotationProcessorPath>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Overview compiler arguments

Compiler argument	default value	behaviour	Since
nl.loxia.BuilderGenerator.builderValidation	true	determines whether or not validation code should be generated	1.0.0
nl.loxia.BuilderGenerator.copyOfMethodGeneration	true	determines whether or not copyOf methods should be generated	0.2.0
nl.loxia.BuilderGenerator.methodPrefix	with	the prefix to be used for the chaining of methods, can be empty	0.2.0
nl.loxia.BuilderGenerator.verbose	false	outputs which file is currently handled by the builder generator	1.0.0

Contributing

if you want to contribute to the development of this module, then please see the documentation here: Contribution documentation

Release Notes

1.0.0 (12-12-2023)

• introduced the verbose option for output on which classes get builders generated for them. (#43)
• generate javadoc for the builder. (#41)
• support subpackages of java.lang. (#34)
  • support subpackages of the current builder. (#47)
• allow a constructor which accepts the builder as input. (#31)
• if for an unexpected reason the builder generator crashes it now adds information about during which class and general location in the process it crashes (#44)
• The builder generator now tries to generate as many builders as possible, even if builder generation would result in a runtime exception of the generator itself. (#44)
• Added support for package scope fields. (#50)
• Constructor arguments are now validated as required arguments when calling the build method. (#39)

0.2.0 (27-11-2023)

• copyOf method can now be disabled, this allows for generation of builders without matching get methods for each field. (#15)
• support InnerClassBuilder when InnerClass is in a List (#16)
• determine the properties using setters and constructor arguments (#7)
• allow lists to be accessed using a getter and then add methods on the list (#18)

0.1.0

• Fixed SeeAlso ordering, first childs then parents instead of first parents then childs.
• copyOf method now supports the SeeAlso referencing.
• copyOf method now does an in-depth copy.
• Builder-collections for builder-chaining combined with collections will now be correctly instantiated.
• Builders for builder-chaining with direct field will only be instantiated once. Sequential actions take place on the same builder.
• Lists now have a add... method which accepts a varArgs instead of a single value.
• Compiler warning when parent is missing @Builder annotation.
• Added 'copyOf' method to all builders