From e95680a76733c22ee5937a586ee50c703d5ba621 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Mon, 20 Jan 2020 15:25:08 +0100 Subject: [issue #2221] [issue #788] Lombok now adds nullity annotations. Which 'flavour' is defined in lombok.config; applied to toString, equals, canEqual, and plural-form of `@Singular`. --- website/templates/features/Builder.html | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'website/templates/features/Builder.html') diff --git a/website/templates/features/Builder.html b/website/templates/features/Builder.html index 08ff1ec8..9e5b34c8 100644 --- a/website/templates/features/Builder.html +++ b/website/templates/features/Builder.html @@ -136,6 +136,8 @@ The snippet below does not show what lombok generates for a @Singular field/parameter because it is rather complicated. You can view a snippet here.

If also using setterPrefix = "with", the generated names are, for example, withName (add 1 name), withNames (add many names), and clearNames (reset all names). +

+ Ordinarily, the generated 'plural form' method (which takes in a collection, and adds each element in this collection) will check if a null is passed and throws a NullPointerException with an appropriate message. However, you can configure alternative behaviour. For example, for deserialization classes it can be useful to just do nothing (as if an empty collection was passed) instead: @Singular(nullBehavior = NullCollectionBehavior.IGNORE). If you want to change the kind of nullcheck lombok generates (for example, if you prefer the non-recommended IllegalArgumentException instead, we suggest you configure this in one central place by making a lombok.config entry instead; the intended use for specifying the behavior on the @Singular annotation directly is to explicitly request the IGNORE behaviour.

@@ -146,7 +148,7 @@ @Value @Builder @JsonDeserialize(builder = JacksonExample.JacksonExampleBuilder.class) public class JacksonExample { - @Singular private List<Foo> foos; + @Singular(nullBehavior = NullCollectionBehavior.IGNORE) private List<Foo> foos; @JsonPOJOBuilder(withPrefix = "") public static class JacksonExampleBuilder implements JacksonExampleBuilderMeta { @@ -179,6 +181,10 @@ public class JacksonExample { lombok.singular.auto = [true | false] (default: true)
If true (which is the default), lombok automatically tries to singularize your identifier name by assuming that it is a common english plural. If false, you must always explicitly specify the singular name, and lombok will generate an error if you don't (useful if you write your code in a language other than english). +
+ lombok.singular.nullCollections = [NullPointerException | IllegalArgumentException | Guava | JDK | ignore] (default: NullPointerException) +
+ What should lombok do when a generated 'plural form' (for singular properties) method is called with a null argument? Normally, lombok does an explicit null check with an appropriate message, but you can use this configuration to pick another flavour of nullcheck. The ignore option makes lombok treat null as an empty collection: Do nothing. An appropriate nullity annotation will be placed on the generated plural form method's parameter if you configured the flavour of nullity annotations you want via lombok.config key lombok.addNullAnnotations.
@@ -211,6 +217,8 @@ public class JacksonExample {

If setting the access level to PROTECTED, all methods generated inside the builder class are actually generated as public; the meaning of the protected keyword is different inside the inner class, and the precise behaviour that PROTECTED would indicate (access by any source in the same package is allowed, as well as any subclasses from the outer class, marked with @Builder is not possible, and marking the inner members public is as close as we can get. +

+ If you have configured a nullity annotation flavour via lombok.config key lombok.addNullAnnotations, any plural-form generated builder methods for @Singular marked properties (these plural form methods take a collection of some sort and add all elements) get a nullity annotation on the parameter. You get a non-null one normally, but if you have configured the behaviour on null being passed in as collection to IGNORE, a nullable annotation is generated instead.

-- cgit