@Builder gained @Singular support and was promoted to the main lombok package since lombok v1.16.0.
@Builder with @Singular adds a clear method since lombok v1.16.8.
+
+ @Builder.Default functionality was added in lombok v1.16.16.
@Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld", toBuilder = true)
+ If a certain field/parameter is never set during a build session, then it always gets 0 / null / false. If you've put @Builder on a class (and not a method or constructor) you can instead specify the default directly on the field, and annotate the field with @Builder.Default:
+ @Builder.Default private final long created = System.currentTimeMillis();
+
By annotating one of the parameters (if annotating a method or constructor with @Builder) or fields (if annotating a class with @Builder) with the @Singular annotation, lombok will treat that builder node as a collection, and it generates 2 'adder' methods instead of a 'setter' method. One which adds a single element to the collection, and one which adds all elements of another collection to the collection. No setter to just set the collection (replacing whatever was already added) will be generated. A 'clear' method is also generated. These 'singular' builders are very complicated in order to guarantee the following properties:
Even if a field is explicitly initialized with null, lombok will consider the requirement to avoid null as fulfilled, and will NOT consider the field as a 'required' argument. The assumption is that if you explicitly assign null to a field that you've also marked as @NonNull signals you must know what you're doing.
- The @java.beans.ConstructorProperties annotation is never generated for a constructor with no arguments. This also explains why @NoArgsConstructor lacks the suppressConstructorProperties annotation method. The @ConstructorProperties annotation is also omitted for private constructors. The generated static factory methods also do not get @ConstructorProperties, as this annotation can only be added to real constructors.
+ The @java.beans.ConstructorProperties annotation is never generated for a constructor with no arguments. This also explains why @NoArgsConstructor lacks the suppressConstructorProperties annotation method. The generated static factory methods also do not get @ConstructorProperties, as this annotation can only be added to real constructors.
@XArgsConstructor can also be used on an enum definition. The generated constructor will always be private, because non-private constructors aren't legal in enums. You don't have to specify AccessLevel.PRIVATE.
diff --git a/website2/templates/features/experimental/onX.html b/website2/templates/features/experimental/onX.html index 8e07f0ac..fd2e7b58 100644 --- a/website2/templates/features/experimental/onX.html +++ b/website2/templates/features/experimental/onX.html @@ -32,7 +32,9 @@
@Setter and @Wither support onParam in addition to onMethod; annotations listed will be put on the only parameter that the generated method has. @EqualsAndHashCode also supports onParam; the listed annotation(s) will be placed on the single parameter of the generated equals method, as well as any generated canEqual method.
- The syntax is a little strange; to use any of the 3 onX features, you must wrap the annotations to be applied to the constructor / method / parameter in @__(@AnnotationGoesHere). To apply multiple annotations, use @__({@Annotation1, @Annotation2}). The annotations can themselves obviously have parameters as well.
+ The syntax is a little strange and depends on the javac you are using.
+ On javac7, to use any of the 3 onX features, you must wrap the annotations to be applied to the constructor / method / parameter in @__(@AnnotationGoesHere). To apply multiple annotations, use @__({@Annotation1, @Annotation2}). The annotations can themselves obviously have parameters as well.
+ On javac8 and up, you add an underscore after onMethod, onParam, or onConstructor.
The reason of the weird syntax is to make this feature work in javac 7 compilers; the @__ type is an annotation reference to the annotation type __ (double underscore) which doesn't actually exist; this makes javac 7 delay aborting the compilation process due to an error because it is possible an annotation processor will later create the __ type. Instead, lombok applies the annotations and removes the references so that the error will never actually occur. The point is: The __ type must not exist, otherwise the feature does not work. In the rare case that the __ type does exist (and is imported or in the package), you can simply add more underscores. Technically any non-existent type would work, but to maintain consistency and readability and catch erroneous use, lombok considers it an error if the 'wrapper' annotation is anything but a series of underscores.
+
+ In javac8, the above feature should work but due to a bug in javac8 it does not. However, starting in javac8, if the parameter name does not exist in the annotation type, compilation proceeds to a phase where lombok can fix it.
To reiterate: This feature can disappear at any time; if you use this feature, be prepared to adjust your code when we find a nicer way of implementing this feature, or, if a future version of javac forces us to remove this feature entirely with no alternative.