diff options
Diffstat (limited to 'website')
| -rw-r--r-- | website/templates/features/Builder.html | 10 | ||||
| -rw-r--r-- | website/templates/features/EqualsAndHashCode.html | 2 | ||||
| -rw-r--r-- | website/templates/features/ToString.html | 2 | ||||
| -rw-r--r-- | website/templates/features/With.html | 2 | ||||
| -rw-r--r-- | website/templates/features/configuration.html | 6 |
5 files changed, 20 insertions, 2 deletions
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 <code>@Singular</code> field/parameter because it is rather complicated. You can view a snippet <a href="builderSingular">here</a>. </p><p> If also using <code>setterPrefix = "with"</code>, the generated names are, for example, <code>withName</code> (add 1 name), <code>withNames</code> (add many names), and <code>clearNames</code> (reset all names). + </p><p> + Ordinarily, the generated 'plural form' method (which takes in a collection, and adds each element in this collection) will check if a <code>null</code> is passed and throws a <code>NullPointerException</code> 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: <code>@Singular(nullBehavior = NullCollectionBehavior.IGNORE)</code>. If you want to change the kind of nullcheck lombok generates (for example, if you prefer the non-recommended <code>IllegalArgumentException</code> instead, we suggest you configure this in one central place by making a <code>lombok.config</code> entry instead; the intended use for specifying the behavior on the <code>@Singular</code> annotation directly is to explicitly request the <code>IGNORE</code> behaviour. </p> </@f.featureSection> @@ -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 { <code>lombok.singular.auto</code> = [<code>true</code> | <code>false</code>] (default: true) </dt><dd> If <code>true</code> (which is the default), lombok automatically tries to singularize your identifier name by assuming that it is a common english plural. If <code>false</code>, 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). + </dd><dt> + <code>lombok.singular.nullCollections</code> = [<code>NullPointerException</code> | <code>IllegalArgumentException</code> | <code>Guava</code> | <code>JDK</code> | <code>ignore</code>] (default: <code>NullPointerException</code>) + </dt><dd> + What should lombok do when a generated 'plural form' (for singular properties) method is called with a <code>null</code> 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 <code>ignore</code> 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 <a href="configuration"><code>lombok.config</code></a> key <code>lombok.addNullAnnotations</code>. </dd> </@f.confKeys> @@ -211,6 +217,8 @@ public class JacksonExample { </p><p> If setting the access level to <code>PROTECTED</code>, all methods generated inside the builder class are actually generated as <code>public</code>; the meaning of the <code>protected</code> keyword is different inside the inner class, and the precise behaviour that <code>PROTECTED</code> would indicate (access by any source in the same package is allowed, as well as any subclasses <em>from the outer class, marked with <code>@Builder</code></em> is not possible, and marking the inner members <code>public</code> is as close as we can get. + </p><p> + If you have configured a nullity annotation flavour via <a href="configuration"><code>lombok.config</code></a> key <code>lombok.addNullAnnotations</code>, any plural-form generated builder methods for <code>@Singular</code> 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 <code>null</code> being passed in as collection to <code>IGNORE</code>, a nullable annotation is generated instead. </p> </@f.smallPrint> </@f.scaffold> diff --git a/website/templates/features/EqualsAndHashCode.html b/website/templates/features/EqualsAndHashCode.html index 5b54e027..2ea2954a 100644 --- a/website/templates/features/EqualsAndHashCode.html +++ b/website/templates/features/EqualsAndHashCode.html @@ -54,7 +54,7 @@ If a getter exists for a field to be included, it is called instead of using a direct field reference. This behaviour can be suppressed:<br /> <code>@EqualsAndHashCode(doNotUseGetters = true)</code> </p><p> - If the class (or an enclosing class) has either the <code>@org.eclipse.jdt.annotation.NonNullByDefault</code> or the <code>@javax.annotation.ParametersAreNonnullByDefault</code> annotation, the parameter of the generated <code>equals</code> method will have the appropriate <code>@Nullable</code> annotation; JDK8+ is required when you do this. <span class="since">(since 1.18.12)</span>. + If you have configured a nullity annotation flavour via <a href="configuration"><code>lombok.config</code></a> key <code>lombok.addNullAnnotations</code>, the parameter of both the generated <code>equals</code> method as well as any <code>canEqual</code> method is annotated with a nullable annotation. This is required if you use a <code>@NonNullByDefault</code> style annotation in combination with strict nullity checking. </p> </@f.smallPrint> </@f.scaffold> diff --git a/website/templates/features/ToString.html b/website/templates/features/ToString.html index d2644629..456092d5 100644 --- a/website/templates/features/ToString.html +++ b/website/templates/features/ToString.html @@ -59,6 +59,8 @@ <code>@ToString(doNotUseGetters = true)</code> </p><p> <code>@ToString</code> can also be used on an enum definition. + </p><p> + If you have configured a nullity annotation flavour via <a href="configuration"><code>lombok.config</code></a> key <code>lombok.addNullAnnotations</code>, the method or return type (as appropriate for the chosen flavour) is annotated with a non-null annotation. </p> </@f.smallPrint> </@f.scaffold> diff --git a/website/templates/features/With.html b/website/templates/features/With.html index 425a1640..8b34f038 100644 --- a/website/templates/features/With.html +++ b/website/templates/features/With.html @@ -47,6 +47,8 @@ No method is generated if any method already exists with the same name (case insensitive) and same parameter count. For example, <code>withX(int x)</code> will not be generated if there's already a method <code>withX(String... x)</code> even though it is technically possible to make the method. This caveat exists to prevent confusion. If the generation of a method is skipped for this reason, a warning is emitted instead. Varargs count as 0 to N parameters. </p><p> Various well known annotations about nullity cause null checks to be inserted and will be copied to the parameter. See <a href="/features/GetterSetter">Getter/Setter</a> documentation's small print for more information. + </p><p> + If you have configured a nullity annotation flavour via <a href="configuration"><code>lombok.config</code></a> key <code>lombok.addNullAnnotations</code>, the method or return type (as appropriate for the chosen flavour) is annotated with a non-null annotation. </p> </@f.smallPrint> </@f.scaffold> diff --git a/website/templates/features/configuration.html b/website/templates/features/configuration.html index 4d7b1547..26d9af4f 100644 --- a/website/templates/features/configuration.html +++ b/website/templates/features/configuration.html @@ -80,6 +80,12 @@ </ol> can be included. We suggest you put this in the root of your workspace directory. </p><p> + Lombok can add nullity annotations (usually called <code>@NonNull</code> and <code>@Nullable</code>) whenever it makes sense to do so; think of generated <a href="ToString"><code>toString</code></a> and <a href="with"><code>withX</code> methods (these never return null), or the parameter of a generated <a href="EqualsAndHashCode"><code>equals</code></a> method, which is allowed to be null, and requires such an annotation if you've set up your IDE for strict null checks as well as 'parameters are non-null by default'. There are many such libraries; you must tell lombok which one to use. By default, no such annotations are added. Enable this feature with: + <div class="snippet example"> + <code>lombok.addNullAnnotations = <em>flavour</em></code> (flavours: <code>javax</code> (=JSR305; not recommended), <code>eclipse</code>, <code>jetbrains</code>, <code>netbeans</code>, <code>androidx</code>, <code>android.support</code> (deprecated within android), <code>checkerframework</code> (recommended), <code>findbugs</code>, <code>spring</code>, <code>jml</code>, or define your own via <code>CUSTOM:fully.qualified.NonNullAnnotation:fully.qualified.NullableAnnotation</code>. + </div> + <em>This feature was introduced in lombok v1.20.0</em>. + </p><p> Lombok can add <code>@javax.annotation.Generated</code> annotations to all generated nodes where possible. You can enable this with: <ol class="snippet example oneliner"> <li><code>lombok.addJavaxGeneratedAnnotation = true</code></li> |