https://github.com/h908714124/auto-builder
Convenience builders for auto-value classes
https://github.com/h908714124/auto-builder
auto-value builder-pattern dry productivity
Last synced: 5 months ago
JSON representation
Convenience builders for auto-value classes
- Host: GitHub
- URL: https://github.com/h908714124/auto-builder
- Owner: h908714124
- Created: 2017-04-30T15:39:42.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2019-08-02T20:20:53.000Z (over 6 years ago)
- Last Synced: 2025-04-28T06:36:04.889Z (8 months ago)
- Topics: auto-value, builder-pattern, dry, productivity
- Language: Java
- Homepage:
- Size: 243 KB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
### auto-builder
[](https://maven-badges.herokuapp.com/maven-central/com.github.h908714124/auto-builder)
The builder pattern is useful because it lets us "update" immutable objects.
However the pattern is very repetitive to write and maintain,
so it might be a good idea to actually generate it.
Please note that this processor depends on another processor
called [auto-value](https://github.com/google/auto/tree/master/value).
See below for the necessary configuration.
#### Quick start
Take the `Animal` class from the
[auto-value docs](https://github.com/google/auto/blob/master/value/userguide/builders.md),
and add the auto-builder annotation:
````java
@AutoBuilder
@AutoValue
abstract class Animal {
abstract String name();
abstract int numberOfLegs();
}
````
A class `Animal_Builder` will be generated in the same package as `Animal`.
An instance of `Animal_Builder` can be obtained in two different ways:
* `Animal_Builder.builder()` returns a builder filled with `null`, `0`, `false` and `Optional.empty()`.
* If you already have an instance of `Animal`, `Animal_Builder.toBuilder(Animal input)`
can be used to create a modified copy.
#### Aliasing the builder methods
It is often convenient to add these the alias methods `builder` and `toBuilder`
to `Animal`:
````java
@AutoBuilder
@AutoValue
abstract class Animal {
abstract String name();
abstract int numberOfLegs();
static Animal_Builder builder() {
return Animal_Builder.builder();
}
Animal_Builder toBuilder() {
return Animal_Builder.toBuilder(this);
}
}
````
#### Usage
Given the above example, we can create an
animal as follows:
````java
Animal betty = Animal.builder()
.name("Betty")
.numberOfLegs(4)
.build();
````
Note that the runtime type of `betty` is `AutoValue_Animal`.
This processor is just a convenience to create "regular"
auto-value objects.
Updating the immutable object `betty` is straightforward:
````java
Animal sally = betty.toBuilder()
.name("Sally")
.build();
````
#### Internals
This annotation processor scans the generated class `AutoValue_Animal`,
rather than `Animal` itself.
Specifically, it looks at the constructor of `AutoValue_Animal`
to figure out what to do.
If `AutoValue_Animal` can't be found at the end of processing,
because the auto-value processing failed,
then auto-builder will not generate anything either.
#### Reducing the garbage collection overhead
Since version 1.5, auto-builder is capable of caching the builder instance.
This should in theory reduce the garbage collection overhead
(I have not measured it, though).
Use `reuseBuilder = true` to make
the generated code cache and re-use
the same builder instance:
````java
@AutoBuilder(reuseBuilder = true)
@AutoValue
abstract class Animal {
// [...]
}
````
#### Configuration
The annotations are in a separate jar.
They are not needed at runtime, so the scope can be `optional`
or `provided`.
````xml
com.github.h908714124
auto-builder-annotations
1.0
provided
com.google.auto.value
auto-value-annotations
1.6.5
````
The processor itself is only needed on the compiler classpath.
````xml
org.apache.maven.plugins
maven-compiler-plugin
3.8.1
com.github.h908714124
auto-builder
${auto-builder.version}
com.google.auto.value
auto-value
1.6.5
````
The equivalent gradle configuration looks as follows:
````groovy
dependencies {
api "com.google.auto.value:auto-value-annotations:1.6.5"
implementation "com.github.h908714124:auto-builder-annotations:1.0"
annotationProcessor "com.google.auto.value:auto-value:1.6.5"
annotationProcessor "com.github.h908714124:auto-builder:$autoBuilderVersion"
}
````