PojoBuilder - A Code Generator for Pojo Builders

Author: Michael Karneim

Project Homepage: http://github.com/mkarneim/pojobuilder

About

PojoBuilder is a Java annotation processor that creates a fluent builder class for POJOs (Plain Old Java Object).

The generated builder offers:

A fluent interface to set the pojo's properties.
A build() method that creates a new pojo instance with the given values.

You can use a generated pojo builder like this:

	Contact james = new ContactBuilder()
		.withSurname("Bond")
		.withFirstname("James")
		.withEmail("007@secretservice.org")
		.build();

Builders can help you create test data by letting you set only the relevant properties.

For more details on:

Test data builders, see http://c2.com/cgi/wiki?TestDataBuilder and http://www.natpryce.com/articles/000714.html (by Nat Pryce).
The builder pattern, see http://en.wikipedia.org/wiki/Builder_pattern.
Fluent interfaces, see http://www.martinfowler.com/bliki/FluentInterface.html (by Martin Fowler)

License and Dependencies

The source code in the "src" directory is in the PUBLIC DOMAIN. For details, read the [COPYING] file.

PojoBuilder is a code generator. It does not add runtime dependencies to your project.

It adds one compile-time dependency with its own license:

[JavaWriter] 2.5.0 (see license)

Download

PojoBuilder is open source. The source code is available at http://github.com/mkarneim/pojobuilder. For older versions and a change log, see the [release history page].

PojoBuilder binaries are available at [Sonatype OSS Maven Repository] and [Maven Central].

If you do not use a build automation tool that supports Maven repos, download the [pojobuilder-4.3.1-jar-with-dependencies.jar] to get PojoBuilder with all its dependencies.

How To Use

PojoBuilder uses an annotation processor to generate pojo builders. You can trigger code generation during compilation by:

annotating a pojo's constructor
annotating the pojo class
annotating a factory method

Annotating a Constructor

To generate a builder, annotate one of the pojo's constructors with @GeneratePojoBuilder.

Example:

public class Contact {
  private final String surname;
  private final String firstname;
  private String email;

  @GeneratePojoBuilder
  public Contact(String surname, String firstname) {
    this.surname = surname;
    this.firstname = firstname;
  }

  public String getEmail() {
    return email;
  }

  public void setEmail(String email) {
    this.email = email;
  }

  public String getSurname() {
    return surname;
  }

  public String getFirstname() {
    return firstname;
  }
}

The [@GeneratePojoBuilder] annotation tells the processor to create a source file named ContactBuilder. Check [ContactBuilder.java] to see the generated code.

Ensure the constructor is public or accessible to the generated builder (for example, if it is protected, the builder must be in the same package).

Also, the constructor parameter names must match the pojo's property names exactly.

You can use an optional [@ConstructorProperties] annotation to map constructor parameter names to bean property names if they differ.

public class Contact {
  private final String surname;
  private final String firstname;
  private String email;

  @GeneratePojoBuilder
  @ConstructorProperties({"surname","firstname"})
  public Contact(String arg1, String arg2) {
    this.surname = arg1;
    this.firstname = arg2;
  }

  public String getEmail() {
    return email;
  }

  public void setEmail(String email) {
    this.email = email;
  }

  public String getSurname() {
    return surname;
  }

  public String getFirstname() {
    return firstname;
  }
}

Annotating the Pojo

If your pojo does not define a specific constructor, has only a public default constructor, or defines exactly one constructor, annotate the class with @GeneratePojoBuilder..

Example:

@GeneratePojoBuilder
public class User {
  private String name;
  private char[] password;

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public char[] getPassword() {
    return password;
  }

  public void setPassword(char[] password) {
    this.password = password;
  }
}

See [UserBuilder.java] to review the generated code.

Annotating a Factory Method

If you cannot modify the pojo's source or prefer not to annotate the pojo, annotate a factory method:

public class UrlFactory {

  @GeneratePojoBuilder(withName="UrlBuilder", intoPackage = "samples")
  public static URL createUrl(
    String protocol, String host, int port, String file, URLStreamHandler handler)
      throws MalformedURLException {
    return new URL(protocol, host, port, file, handler);
  }
}

Check [UrlBuilder.java] to see the generated code.

Ensure the factory method is public and static. Its parameter names must match the pojo's property names exactly.

You can use an optional [@FactoryProperties] annotation to map the parameter names if needed.

public class FileFactory {

  @GeneratePojoBuilder(intoPackage = "samples")
  @FactoryProperties({"path"})
  public static File createFile(String arg1) {
    return new File(arg1);
  }
}

See [FileBuilder.java] for the generated code.

Annotating a Record

Starting with PojoBuilder 4.3, you can annotate a Java 17 record:

@GeneratePojoBuilder
public record MyRecord(int x, int y, String blah) {}

Directives

You can use the following elements of [@GeneratePojoBuilder] to configure code generation:

withName=<String> specifies the pattern of the builder's name. An asterisk will be replaced with the pojos simple name. For example, the result of the pattern Fluent*Builder will become FluentContactBuilder if the pojo's name is Contact. The default pattern is *Builder.
withConstructor=<Visibility> Specifies the visibility of the builder's constructor. Default is Visibility.PUBLIC.
intoPackage=<String> specifies the package of the generated builder. An asterisk will be replaced with the pojos package. For example, the result of the pattern *.util will become com.example.util if the pojo's package is com.example. The default pattern is *.
withBaseclass=<Class> specifies the base class of the generated builder. The default class is Object.class.
withBuilderInterface=<Class> specifies the interface of the generated builder. The interface must declare exactly one type parameter and a build method with this type as return type. For an example please see [Address.java], [Builder.java] and [AddressBuilder.java]. Default is Void.class, which means, that no interface should be implemented.
withBuilderProperties=<boolean> specifies whether the generated builder should define builder-based with-methods using the builder interface (see above). For an example please see [Recipient.java], [Builder.java] and [RecipientBuilder.java]. Default is false.
includeProperties=<String[]> specifies which of the pojo's properties will be included into the generated builder. All properties that match any [property pattern] in the specified array will be included. All other non-mandatory properties will be excluded. Mandatory properties are those which are passed as constructor or factory method arguments. They will never be excluded, neither explicitly nor implicitly. For an example please see [InputSourceFactory.java] and [InputSourceBuilder.java]. Default is *.
excludeProperties=<String[]> specifies which of the pojo's properties will be excluded from the generated builder. All property that match any [property pattern] in the specified array will be excluded, except those that are mandatory. Mandatory properties are those which are passed as constructor or factory method arguments. They will never be excluded, neither explicitly nor implicitly. For an example please see [CalendarFactory.java] and [GregorianCalendarBuilder.java]. Default is the empty array.
withGenerationGap=<boolean> specifies whether the [generation gap pattern] is used. If enabled, this will generate two classes (instead of one), of which one contains the ordinary builder code, whereas the other class extends the first one and is an empty template for handwritten code. Please move it out of the generated-sources folder to prevent it from being overwritten. For examples please see [Player.java], [PlayerBuilder.java], and [AbstractPlayerBuilder.java]. Default is false.
withCopyMethod=<boolean> specifies whether a copy method should be generated. Use the copy method to initialize the builder's values from a given pojo instance. For an example please see [TextEmail.java] and [TextEmailBuilder.java]. Default is false.
withOptionalProperties=<Class> specifies whether the generated builder should define optional-based setter-methods using the specified 'Optional' type. Examples are Google Guava's com.google.common.base.Optional and java.util.Optional introduced with Java 8. Default is Void.class, which means, that no optional-based setter-methods are generated.
withSetterNamePattern=<String> specifies the name pattern of

Pojobuilder

Install / Use

README