https://github.com/timboudreau/builder-builder
Annotations and annotation processors for generating builders
https://github.com/timboudreau/builder-builder
Last synced: 6 months ago
JSON representation
Annotations and annotation processors for generating builders
- Host: GitHub
- URL: https://github.com/timboudreau/builder-builder
- Owner: timboudreau
- Created: 2022-09-11T07:06:12.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-05-01T05:20:35.000Z (over 2 years ago)
- Last Synced: 2025-01-10T15:51:14.232Z (about 1 year ago)
- Language: Java
- Size: 258 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Builder Builder
===============
A Java annotation and annotation processor for creating builders.
In it's simplest form, usage is simply:
1. Create a class that takes some constructor arguments.
2. Annotate it with `GenerateBuilder`.
That's it. A class will be generated called with the same name as your class with `Builder` appended, in the same package.
Works with types that take generics and similar.
Generation Styles
=================
Two builder styles are available:
* The default mode generates a set of builder classes such that it is impossible *at compile time* to create an
incompletely initialized object, because you only are returned a builder type that **has** a build method when
all but one of the required parameters have been supplied (there will be a `buildWith$NAME()` method that takes
the final parameter.
* This may result in a large number of interim builder classes, but in practice, users of builders will use a
fluent API and be unaware of them
* There is a tremendous advantage to turning runtime errors into compile-time errors - use this mode where practical
* If the type takes an enormous number of parameters and the resulting source file might exceed `javac`'s file
length limit, it will fail over to `FLAT` mode
* FLAT - This generates a more typical builder class, with a build method visible at all times, which simply throws
an IllegalStateException at runtime if a parameter was not provided.
Constraints
===========
A number of annotations can be applied to constructor *parameters* to constrain the legal values, and
those constraints will be enforced by the builder.
### Optional and Defaulted values
* The `@Optionally` annotation allows you to mark a parameter as nullable. If you set `defaulted=true`, then for
types have a logical "null value" (zero, the empty string, an empty array or list) you will get that as a default
* Default values for booleans, numbers and strings can be provided here
### Numeric Constraints
Annotate parameters with `IntMin / IntMax / FloatMin / FloatMax / LongMin / LongMax / DoubleMin / DoubleMax / ByteMin / ByteMax`
to set minimum and/or maximum allowable values.
### String Constraints
Annotatate string parameters with `StringPattern` to enforce a regular expression on the string, and optional minimum and
maximum length values.
### Collection Constraints
`@CollectionConstraint` applies to `java.util.Collection` types, `java.util.Map` types, as well as arrays, and lets you
set minimum and maximum sizes, forbid null values, and force a type check of each element.
Sample Code
===========
Take a look at [the demo project code](https://github.com/timboudreau/builder-builder/blob/main/builder-builder-demo/src/test/java/com/timboudreau/bugdemo/attribution/bug/demo/BuilderBuilderDemoTest.java#L32) to get
a picture of what builder usage looks like in practice, and some descriptoin of what's happening under-the-hood.