record-builder/customizing.md

◀︎ RecordBuilder • Customizing RecordBuilder

RecordBuilderFull

Note: @RecordBuilderFull has most optional features enabled. It's an alternate form of @RecordBuilder that uses the templating mechanism to enable optional features.

Customizing RecordBuilder

RecordBuilder can be customized in a number of ways. The types of customizations will change over time. See @RecordBuilder.Options for the current set of customizations and their default values. For example, the useImmutableCollections option adds special handling for record components of type java.util.List, java.util.Set, java.util.Map and java.util.Collection. When the record is built, any components of these types are passed through an added shim method that uses the corresponding immutable collection (e.g. List.copyOf(o)) or an empty immutable collection if the component is null.

You can:

• Customize an entire build - all uses of @RecordBuilder in your project
• Customize a single record annotated with @RecordBuilder
• Create a custom annotation that specifies your options and use that instead of @RecordBuilder

Customize an entire build

To customize an entire build, use javac's annotation processor options via -A on the command line. The options available are the same as the attributes in @RecordBuilder.Options. i.e. to disable "prefixing enclosing class names", compile with:

javac -AprefixEnclosingClassNames=false ...

Note: use a separate -A for each option.

Maven

If you are using Maven, specify the options in the compiler plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>${maven-compiler-plugin-version}</version>
    <configuration>
        <compilerArgs>
            <arg>-AprefixEnclosingClassNames=false</arg>
            <arg>-AfileComment="something different"</arg>
        </compilerArgs>
    </configuration>
</plugin>

Gradle

For Gradle, specify the options:

compilerArgs.addAll(['-AprefixEnclosingClassNames=false', '-AfileComment="something different"'])

Customize a single record

To customize a single record, add @RecordBuilder.Options in addition to @RecordBuilder.

E.g.

@RecordBuilder.Options(withClassName = "Wither")
@RecordBuilder
public record MyRecord(String s){}

Create a custom annotation

Using @RecordBuilder.Template you can create your own RecordBuilder annotation that uses the set of options you want. E.g. to create a custom annotation that uses an alternate file comment and an alternate With classname:

@RecordBuilder.Template(options = @RecordBuilder.Options(
        fileComment = "MyCo license",
        withClassName = "Wither"
))
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
@Inherited
public @interface MyCoRecordBuilder {
}

Now, you can use @MyCoRecordBuilder instead of @RecordBuilder and the record will be built with options as specified.

Note: the template mechanism also supports @RecordInterface templates via the asRecordInterface attribute. When it is set a @RecordInterface template is created instead.