From c42bfbae39990b365a5f05eb23895da6203023bc Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Fri, 31 Jan 2020 06:33:33 +0100 Subject: [issue #2221] simplified configuration for `@Singular`-generated plural form nullchecks. --- website/templates/features/Builder.html | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) (limited to 'website') diff --git a/website/templates/features/Builder.html b/website/templates/features/Builder.html index 9e5b34c8..23977837 100644 --- a/website/templates/features/Builder.html +++ b/website/templates/features/Builder.html @@ -46,7 +46,7 @@ Each listed generated element will be silently skipped if that element already exists (disregarding parameter counts and looking only at names). This includes the builder itself: If that class already exists, lombok will simply start injecting fields and methods inside this already existing class, unless of course the fields / methods to be injected already exist. You may not put any other method (or constructor) generating lombok annotation on a builder class though; for example, you can not put @EqualsAndHashCode on the builder class.

- @Builder can generate so-called 'singular' methods for collection parameters/fields. These take 1 element instead of an entire list, and add the element to the list. For example: Person.builder().job("Mythbusters").job("Unchained Reaction").build(); would result in the List<String> jobs field to have 2 strings in it. To get this behaviour, the field/parameter needs to be annotated with @Singular. The feature has its own documentation. + @Builder can generate so-called 'singular' methods for collection parameters/fields. These take 1 element instead of an entire list, and add the element to the list. For example: Person.builder().job("Mythbusters").job("Unchained Reaction").build(); would result in the List<String> jobs field to have 2 strings in it. To get this behavior, the field/parameter needs to be annotated with @Singular. The feature has its own documentation.

Now that the "method" mode is clear, putting a @Builder annotation on a constructor functions similarly; effectively, constructors are just static methods that have a special syntax to invoke them: Their 'return type' is the class they construct, and their type parameters are the same as the type parameters of the class itself.

@@ -133,11 +133,11 @@ If your identifiers are written in common english, lombok assumes that the name of any collection with @Singular on it is an english plural and will attempt to automatically singularize that name. If this is possible, the add-one method will use this name. For example, if your collection is called statuses, then the add-one method will automatically be called status. You can also specify the singular form of your identifier explictly by passing the singular form as argument to the annotation like so: @Singular("axis") List<Line> axes;.
If lombok cannot singularize your identifier, or it is ambiguous, lombok will generate an error and force you to explicitly specify the singular name.

- 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. + 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. + 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 the same way @NonNull does (by default, throws a NullPointerException with an appropriate message). However, you can also tell lombok to ignore such collection (so, add nothing, return immediately): @Singular(ignoreNullCollections = true.

@@ -181,10 +181,6 @@ 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.
@@ -196,7 +192,7 @@ public class JacksonExample {

The sorted collections (java.util: SortedSet, NavigableSet, SortedMap, NavigableMap and guava: ImmutableSortedSet, ImmutableSortedMap) require that the type argument of the collection has natural order (implements java.util.Comparable). There is no way to pass an explicit Comparator to use in the builder.

- An ArrayList is used to store added elements as call methods of a @Singular marked field, if the target collection is from the java.util package, even if the collection is a set or map. Because lombok ensures that generated collections are compacted, a new backing instance of a set or map must be constructed anyway, and storing the data as an ArrayList during the build process is more efficient that storing it as a map or set. This behaviour is not externally visible, an implementation detail of the current implementation of the java.util recipes for @Singular @Builder. + An ArrayList is used to store added elements as call methods of a @Singular marked field, if the target collection is from the java.util package, even if the collection is a set or map. Because lombok ensures that generated collections are compacted, a new backing instance of a set or map must be constructed anyway, and storing the data as an ArrayList during the build process is more efficient that storing it as a map or set. This behavior is not externally visible, an implementation detail of the current implementation of the java.util recipes for @Singular @Builder.

With toBuilder = true applied to methods, any type parameter of the annotated method itself must also show up in the return type.

@@ -216,9 +212,9 @@ public class JacksonExample { Due to a peculiar way javac processes static imports, trying to do a non-star static import of the static builder() method won't work. Either use a star static import: `import static TypeThatHasABuilder.*;` or don't statically import the builder method.

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. + protected keyword is different inside the inner class, and the precise behavior 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. + 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 behavior on null being passed in as collection to IGNORE, a nullable annotation is generated instead.

-- cgit