From 34835fa8b7ad24cf8bb80cda71594c9a1eb785de Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Mon, 26 Jan 2015 22:11:57 +0100 Subject: small updates to the documentation of @Singular. --- usage_examples/BuilderExample_post.jpage | 4 ++++ usage_examples/BuilderExample_pre.jpage | 2 +- usage_examples/Singular-snippetExample_post.jpage | 20 ++++++++-------- website/features/Builder.html | 28 +++++++++++------------ 4 files changed, 28 insertions(+), 26 deletions(-) diff --git a/usage_examples/BuilderExample_post.jpage b/usage_examples/BuilderExample_post.jpage index 0446a0dc..863ab19b 100644 --- a/usage_examples/BuilderExample_post.jpage +++ b/usage_examples/BuilderExample_post.jpage @@ -37,14 +37,18 @@ public class BuilderExample { if (this.occupations == null) { this.occupations = new java.util.ArrayList(); } + this.occupations.add(occupation); + return this; } public BuilderExampleBuilder occupations(Collection occupations) { if (this.occupations == null) { this.occupations = new java.util.ArrayList(); } + this.occupations.addAll(occupations); + return this; } public BuilderExample build() { diff --git a/usage_examples/BuilderExample_pre.jpage b/usage_examples/BuilderExample_pre.jpage index 374799ad..1557fff4 100644 --- a/usage_examples/BuilderExample_pre.jpage +++ b/usage_examples/BuilderExample_pre.jpage @@ -6,5 +6,5 @@ import java.util.Set; public class BuilderExample { private String name; private int age; - @Singular Set occupations; + @Singular private Set occupations; } diff --git a/usage_examples/Singular-snippetExample_post.jpage b/usage_examples/Singular-snippetExample_post.jpage index 689d97e8..4e2b0460 100644 --- a/usage_examples/Singular-snippetExample_post.jpage +++ b/usage_examples/Singular-snippetExample_post.jpage @@ -9,7 +9,7 @@ public class SingularExample { private SortedMap elves; private Collection minutiae; - SingularExample(final Set occupations, final ImmutableList axes, final SortedMap elves, final Collection minutiae) { + SingularExample(Set occupations, ImmutableList axes, SortedMap elves, Collection minutiae) { this.occupations = occupations; this.axes = axes; this.elves = elves; @@ -26,7 +26,7 @@ public class SingularExample { SingularExampleBuilder() { } - public SingularExampleBuilder occupation(final String occupation) { + public SingularExampleBuilder occupation(String occupation) { if (this.occupations == null) { this.occupations = new java.util.ArrayList(); } @@ -36,7 +36,7 @@ public class SingularExample { } @java.lang.SuppressWarnings("all") - public SingularExampleBuilder occupations(final java.util.Collection occupations) { + public SingularExampleBuilder occupations(java.util.Collection occupations) { if (this.occupations == null) { this.occupations = new java.util.ArrayList(); } @@ -45,7 +45,7 @@ public class SingularExample { return this; } - public SingularExampleBuilder axis(final String axis) { + public SingularExampleBuilder axis(String axis) { if (this.axes == null) { this.axes = com.google.common.collect.ImmutableList.builder(); } @@ -54,7 +54,7 @@ public class SingularExample { return this; } - public SingularExampleBuilder axes(final java.lang.Iterable axes) { + public SingularExampleBuilder axes(java.lang.Iterable axes) { if (this.axes == null) { this.axes = com.google.common.collect.ImmutableList.builder(); } @@ -63,7 +63,7 @@ public class SingularExample { return this; } - public SingularExampleBuilder elf(final Integer elfKey, final T elfValue) { + public SingularExampleBuilder elf(Integer elfKey, T elfValue) { if (this.elves$key == null) { this.elves$key = new java.util.ArrayList(); this.elves$value = new java.util.ArrayList(); @@ -74,20 +74,20 @@ public class SingularExample { return this; } - public SingularExampleBuilder elves(final java.util.Map elves) { + public SingularExampleBuilder elves(java.util.Map elves) { if (this.elves$key == null) { this.elves$key = new java.util.ArrayList(); this.elves$value = new java.util.ArrayList(); } - for (final java.util.Map.Entry $lombokEntry : elves.entrySet()) { + for (java.util.Map.Entry $lombokEntry : elves.entrySet()) { this.elves$key.add($lombokEntry.getKey()); this.elves$value.add($lombokEntry.getValue()); } return this; } - public SingularExampleBuilder minutia(final java.lang.Object minutia) { + public SingularExampleBuilder minutia(java.lang.Object minutia) { if (this.minutiae == null) { this.minutiae = new java.util.ArrayList(); } @@ -96,7 +96,7 @@ public class SingularExample { return this; } - public SingularExampleBuilder minutiae(final java.util.Collection minutiae) { + public SingularExampleBuilder minutiae(java.util.Collection minutiae) { if (this.minutiae == null) { this.minutiae = new java.util.ArrayList(); } diff --git a/website/features/Builder.html b/website/features/Builder.html index 5cf7c23e..b4731b07 100644 --- a/website/features/Builder.html +++ b/website/features/Builder.html @@ -83,12 +83,11 @@ are very complicated in order to guarantee the following properties:
  • When invoking build(), the produced collection will be immutable.
    • -
  • Repeatedly invoking build() works fine and does not corrupt any of the collections already generated.
    • -
  • Calling one of the 'adder' methods after invoking build() does not modify any already generated objects, and, if build() is later called again, +
  • Calling one of the 'adder' methods after invoking build() does not modify any already generated objects, and, if build() is later called again, another collection with all the elements added since the creation of the builder is generated.
  • The produced collection will be compacted to the smallest feasible format while remaining efficient.

- @Singular can only be applied to collection types for which lombok has a recipe to produce the singular methods. Currently, the supported types are: + @Singular can only be applied to collection types known to lombok. Currently, the supported types are:

  • java.util:
    • Iterable, Collection, and List (backed by a compacted unmodifiable ArrayList in the general case).
      • @@ -98,17 +97,14 @@
    • Guava's com.google.common.collect:
      • ImmutableCollection and ImmutableList (backed by the builder feature of ImmutableList).
      • ImmutableSet and ImmutableSortedSet (backed by the builder feature of those types).
        • -
      • ImmutableMap, ImmutableBiMap, and ImmutableSortedMap (backed by the builder feature of those types).
        • +
      • ImmutableMap, ImmutableBiMap, and ImmutableSortedMap (backed by the builder feature of those types).

    - If your identifiers are written in common english, lombok assumes that any collection with @Singular on it is an english plural and will attempt to automatically - singularize it. 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. If lombok cannot singularize your identifier, or it is ambiguous, lombok will generate an error and force you to explicitly specify the singular name. - To do this, just pass the singular name as string, like so: @Singular("axis") List<Line> axes;. -

    - When using the java.util interfaces, lombok always uses ArrayList to store items added to the builder, because this is more efficient than adding them to a map or - set immediately, as lombok needs to compact and potentially duplicate the result. + 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. @@ -132,9 +128,9 @@

    lombok.builder.flagUsage = [warning | error] (default: not set)
    Lombok will flag any usage of @Builder as a warning or error if configured.
    lombok.singular.useGuava = [true | false] (default: false)
    -
    If true, lombok will use guava's ImmutableX builders and types to implement java.util collection interfaces, instead of creating - implementations based on Collections.unmodifiableX. You must ensure that guava is actually available on the classpath and buildpath if you use this setting. - Guava is used automatically if your field/parameter has one of the guava ImmutableX types. +
    If true, lombok will use guava's ImmutableXxx builders and types to implement java.util collection interfaces, instead of creating + implementations based on Collections.unmodifiableXxx. You must ensure that guava is actually available on the classpath and buildpath if you use this setting. + Guava is used automatically if your field/parameter has one of the guava ImmutableXxx types.
    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). @@ -146,9 +142,11 @@ @Singular support for java.util.NavigableMap/Set only works if you are compiling with JDK1.8 or higher.

    You cannot manually provide some or all parts of a @Singular node; the code lombok generates is too complex for this. If you want to - manually control (part of) the builder nodes associated with some field or parameter, don't use @Singular and add everything you need manually. + manually control (part of) the builder code associated with some field or parameter, don't use @Singular and add everything you need manually.

    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 an implementation detail of the current implementation of the java.util recipes for @Singular @Builder.

    -- cgit