From 22dc8827b6f21529862335dcaf2ff0461fd9baa8 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Tue, 21 Jul 2015 05:28:21 +0200 Subject: docs for the new toBuilder=true feature. --- website/features/Builder.html | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'website') diff --git a/website/features/Builder.html b/website/features/Builder.html index 60c69a42..6cf46600 100644 --- a/website/features/Builder.html +++ b/website/features/Builder.html @@ -40,7 +40,7 @@
  • In the builder: A build() method which calls the static method, passing in each field. It returns the same type that the target returns.
  • In the builder: A sensible toString() implementation.
    • -
  • In the class containing the target: A builder() method, which creates a new instance of the builder.
    • +
  • In the class containing the target: A static builder() method, which creates a new instance of the builder.
    • 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 @@ -59,6 +59,8 @@ @Builder annotation to this all-args-constructor. This only works if you haven't written any explicit constructors yourself. If you do have an explicit constructor, put the @Builder annotation on the constructor instead of on the class.

    + If using @Builder to generate builders to produce instances of your own class (this is always the case unless adding @Builder to a static method that doesn't return your own type), you can use @Builder(toBuilder = true) to also generate an instance method in your class called toBuilder(); it creates a new builder that starts out with all the values of this instance. You can put the @Builder.ObtainVia annotation on the parameters (in case of a constructor or static method) or fields (in case of @Builder on a type) to indicate alternative means by which the value for that field/parameter is obtained from the instance. For example, you can specify a method to be invoked: @Builder.ObtainVia(method = "calculateFoo"). +

    The name of the builder class is FoobarBuilder, where Foobar is the simplified, title-cased form of the return type of the target - that is, the name of your type for @Builder on constructors and types, and the name of the return type for @Builder on static methods. For example, if @Builder is applied to a class named com.yoyodyne.FancyList<T>, then the builder name will be @@ -69,9 +71,10 @@

  • The builder's class name (default: return type + 'Builder')
  • The build() method's name (default: "build")
  • The builder() method's name (default: "builder")
    • +
  • If you want toBuilder() (default: no)
    • Example usage where all options are changed from their defaults:
    - @Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld")
    + @Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld", toBuilder = true)

    @@ -147,6 +150,8 @@ 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. +

    + With toBuilder = true applied to static methods, any type parameter on the annotated static method must show up in the returntype.

    -- cgit