Apache Groovy 3.0.20 · groovy.transform.builder.Builder

The @Builder AST transformation is used to help write classes that can be created using fluent api calls. The transform supports multiple building strategies to cover a range of cases and there are a number of configuration options to customize the building process. In addition, a number of annotation attributes let you customise the building process. Not all annotation attributes are supported by all strategies. See the individual strategy documentation for more details. If you're an AST hacker, you can also define your own strategy class. The following strategies are bundled with Groovy:

SimpleStrategy for creating chained setters
ExternalStrategy where you annotate an explicit builder class while leaving some buildee class being built untouched
DefaultStrategy which creates a nested helper class for instance creation
InitializerStrategy which creates a nested helper class for instance creation which when used with @CompileStatic allows type-safe object creation

Note that Groovy provides other built-in mechanisms for easy creation of objects, e.g. the named-args constructor:

new Person(firstName: "Robert", lastName: "Lewandowski", age: 21)

or the with statement:

new Person().with {
    firstName = "Robert"
    lastName = "Lewandowski"
    age = 21
}

so you might not find value in using the builder transform at all. But if you need Java integration or in some cases improved type safety, the @Builder transform might prove very useful.

Method Summary

Modifier and Type	Method and Description
public boolean	allNames() Whether the generated builder should support all properties, including those with names that are considered internal.
public boolean	allProperties() Whether to include all properties (as per the JavaBean spec) in the generated builder.
public String	builderClassName() For strategies which create a builder helper class, the class name to use for the helper class.
public String	builderMethodName() The method name to use for a builder factory method in the source class for easy access of the builder helper class for strategies which create such a helper class.
public Class<? extends BuilderASTTransformation.BuilderStrategy>	builderStrategy() A class capturing the builder strategy
public String	buildMethodName() For strategies which create a builder helper class that creates the instance, the method name to call to create the instance.
public String[]	excludes() List of field and/or property names to exclude from generated builder methods.
public boolean	force() Whether to always include helper constructors.
public Class<T>	forClass() A class for which builder methods should be created.
public String[]	includes() List of field and/or property names to include within the generated builder methods.
public boolean	includeSuperProperties() Generate builder methods for properties from super classes.
public String	prefix() The prefix to use when creating the setter methods.
public boolean	useSetters() By default, properties are set directly using their respective field.

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

Method Detail

allNames	back to summary
public boolean allNames() Whether the generated builder should support all properties, including those with names that are considered internal. Since 2.5.0

allNames

back to summary

public boolean allNames()

Whether the generated builder should support all properties, including those with names that are considered internal.

Since: 2.5.0

allProperties back to summary

allProperties	back to summary
public boolean allProperties() Whether to include all properties (as per the JavaBean spec) in the generated builder. Groovy recognizes any field-like definitions with no explicit visibility as property definitions and always includes them in the `@Builder` generated classes. Groovy also treats any explicitly created getXxx() or isYyy() methods as property getters as per the JavaBean specification. Old versions of Groovy did not. So set this flag to false for the old behavior or if you want to explicitly exclude such properties. Currently only supported by DefaultStrategy and ExternalStrategy. Since 2.5.0

public boolean allProperties()

Whether to include all properties (as per the JavaBean spec) in the generated builder. Groovy recognizes any field-like definitions with no explicit visibility as property definitions and always includes them in the @Builder generated classes. Groovy also treats any explicitly created getXxx() or isYyy() methods as property getters as per the JavaBean specification. Old versions of Groovy did not. So set this flag to false for the old behavior or if you want to explicitly exclude such properties. Currently only supported by DefaultStrategy and ExternalStrategy.

Since: 2.5.0

builderClassName	back to summary
public String builderClassName() For strategies which create a builder helper class, the class name to use for the helper class. Not used if using `forClass` since in such cases the builder class is explicitly supplied. Default is determined by the strategy, e.g. TargetClass + "Builder" or TargetClass + "Initializer".

builderMethodName	back to summary
public String builderMethodName() The method name to use for a builder factory method in the source class for easy access of the builder helper class for strategies which create such a helper class. Must not be used if using `forClass`. Default is determined by the strategy, e.g. builder or createInitializer.

builderStrategy	back to summary
public Class<? extends BuilderASTTransformation.BuilderStrategy> builderStrategy() A class capturing the builder strategy

buildMethodName	back to summary
public String buildMethodName() For strategies which create a builder helper class that creates the instance, the method name to call to create the instance. Default is determined by the strategy, e.g. build or create.

excludes	back to summary
public String[] excludes() List of field and/or property names to exclude from generated builder methods. Must not be used if 'includes' is used. For convenience, a String with comma separated names can be used in addition to an array (using Groovy's literal list notation) of String values.

force back to summary

force	back to summary
public boolean force() Whether to always include helper constructors. Currently only supported by InitializerStrategy. By default, the InitializerStrategy only adds a needed helper tuple constructor if no `@TupleConstructor` annotations are present. If such annotations are present, it is assumed they will provide the helper constructor that this strategy needs. If made true, the helper constructor will be generated and it is up to you to make sure this doesn't conflict with any other generated constructors. Since 2.5.0

public boolean force()

Whether to always include helper constructors. Currently only supported by InitializerStrategy. By default, the InitializerStrategy only adds a needed helper tuple constructor if no @TupleConstructor annotations are present. If such annotations are present, it is assumed they will provide the helper constructor that this strategy needs. If made true, the helper constructor will be generated and it is up to you to make sure this doesn't conflict with any other generated constructors.

Since: 2.5.0

forClass	back to summary
public Class<T> forClass() A class for which builder methods should be created. It will be an error to leave this attribute with its default value for some strategies.

includes	back to summary
public String[] includes() List of field and/or property names to include within the generated builder methods. Must not be used if 'excludes' is used. For convenience, a String with comma separated names can be used in addition to an array (using Groovy's literal list notation) of String values. The default value is a special marker value indicating that no includes are defined; all fields are included if includes remains undefined and excludes is explicitly or implicitly an empty list.

includes

back to summary

public String[] includes()

List of field and/or property names to include within the generated builder methods. Must not be used if 'excludes' is used. For convenience, a String with comma separated names can be used in addition to an array (using Groovy's literal list notation) of String values. The default value is a special marker value indicating that no includes are defined; all fields are included if includes remains undefined and excludes is explicitly or implicitly an empty list.

includeSuperProperties	back to summary
public boolean includeSuperProperties() Generate builder methods for properties from super classes. Since 2.5.0

includeSuperProperties

back to summary

public boolean includeSuperProperties()

Generate builder methods for properties from super classes.

Since: 2.5.0

prefix	back to summary
public String prefix() The prefix to use when creating the setter methods. Default is determined by the strategy which might use "" or "set" but you can choose your own, e.g. "with". If non-empty the first letter of the property will be capitalized before being appended to the prefix.

useSetters back to summary

useSetters	back to summary
public boolean useSetters() By default, properties are set directly using their respective field. By setting `useSetters=true` then a writable property will be set using its setter. If turning on this flag we recommend that setters that might be called are made null-safe wrt the parameter. Since 2.5.0

public boolean useSetters()

By default, properties are set directly using their respective field. By setting useSetters=true then a writable property will be set using its setter. If turning on this flag we recommend that setters that might be called are made null-safe wrt the parameter.

Since: 2.5.0

public @Interface Builder

Method Summary

Method Detail