9268c295fe
- Add `@RecordBuilderFull` which will have most optional features enabled - Change `@RecordBuilder.Template` to be `RetentionPolicy.CLASS`
96 lines
3.4 KiB
Markdown
96 lines
3.4 KiB
Markdown
[◀︎ RecordBuilder](README.md) • Customizing RecordBuilder
|
|
|
|
# RecordBuilderFull
|
|
|
|
Note: `@RecordBuilderFull` has most optional features enabled. It's an alternate
|
|
form of `@RecordBuilder` that uses the [templating mechanism](#create-a-custom-annotation) 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](record-builder-core/src/main/java/io/soabase/recordbuilder/core/RecordBuilder.java)
|
|
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](#customize-an-entire-build) - all uses of `@RecordBuilder` in your project
|
|
- [Customize a single record](#customize-a-single-record) annotated with `@RecordBuilder`
|
|
- [Create a custom annotation](#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](record-builder-core/src/main/java/io/soabase/recordbuilder/core/RecordBuilder.java).
|
|
i.e. to disable "prefixing enclosing class names", compile with:
|
|
|
|
```shell
|
|
javac -AprefixEnclosingClassNames=false ...
|
|
```
|
|
|
|
_Note: use a separate `-A` for each option._
|
|
|
|
#### Maven
|
|
|
|
If you are using Maven, specify the options in the compiler plugin:
|
|
|
|
```xml
|
|
<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:
|
|
|
|
```groovy
|
|
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.
|
|
|
|
```java
|
|
@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:
|
|
|
|
```java
|
|
@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.
|