From 7af9add9996f2efab6cccc50c5503b3457534930 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Tue, 16 Jul 2013 00:51:31 +0200 Subject: * Fixed issues with @FieldDefaults and @Value (you can NOT override @Value's final-by-default and private-by-default with it; now appropriate warnings are emitted) * Builder now errors out on presence of most lombok annotations on an explicit builder class. * Builder now takes @FieldDefaults/@Value into account. * Builder on type now generates the constructor as package private instead of private to avoid synthetic accessor constructors. * added a bunch of test cases. * added a test case feature: If the expected file is omitted entirely but there are expected messages, the differences in the output itself are ignored. * streamlined checking for boolean-ness (removed some duplicate code) * added 'fluent' and 'chain' to @Builder. --- website/features/experimental/Builder.html | 33 ++++++++++++++++++------------ 1 file changed, 20 insertions(+), 13 deletions(-) (limited to 'website/features/experimental/Builder.html') diff --git a/website/features/experimental/Builder.html b/website/features/experimental/Builder.html index 5ba74a27..a43d024b 100644 --- a/website/features/experimental/Builder.html +++ b/website/features/experimental/Builder.html @@ -11,7 +11,7 @@
Project Lombok

@Builder

-
It's like drinking tea with an extended pinky while wearing a monocle: No-hassle fancy-pants APIs for object creation!
+
... and Bob's your uncle: No-hassle fancy-pants APIs for object creation!

Since

@@ -24,7 +24,6 @@ Experimental because:

  • New feature - community feedback requested.
    • -
  • This feature will move to the core package soon.
Current status: sure thing - This feature will move to the core package soon.
@@ -43,7 +42,7 @@
  • An inner static class named FooBuilder, with the same type arguments as the static method (called the builder).
  • In the builder: One private non-static non-final field for each parameter of the target.
  • In the builder: A package private no-args empty constructor.
    • -
  • In the builder: A 'setter'-like method for each parmeter of the target: It has the same type as that parameter and the same name. +
  • In the builder: A 'setter'-like method for each parameter of the target: It has the same type as that parameter and the same name. It returns the builder itself, so that the setter calls can be chained, as in the above example.
  • In the builder: A build() method which calls the static method, passing in each field. It returns the same type that the target returns.
    • @@ -52,18 +51,16 @@ 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. + 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.

    Now that the "static 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.

    - Finally, applying @Builder to a class is as if you added @AllArgsConstructor(acces = AccessLevel.PACKAGE) to the class and applied the - @Builder annotation to this all-args-constructor. Note that this constructor is only generated if there is no explicit - constructor present in the so annotated class, but this @AllArgsConstructor has priority over any other implicitly - generated lombok constructor (such as @Data and @Value). If an explicit constructor is present, no constructor is generated, - but the builder will be created with the assumption that this constructor exists. If you've written another constructor, you'll get a compilation error.
    - The solution is to either let lombok write this constructor (delete your own), or, annotate your constructor instead. + Finally, applying @Builder to a class is as if you added @AllArgsConstructor(access = AccessLevel.PACKAGE) to the class and applied the + @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.

    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 @@ -71,9 +68,15 @@ FancyListBuilder<T>. If @Builder is applied to a static method that returns void, the builder will be named VoidBuilder.

    - The only configurable aspect of builder are the builder's class name (default: return type + 'Builder'), the build() method's name, and the - builder() method's name:
    - @Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld") + The configurable aspects of builder are:

    + Example usage where all options are changed from their defaults:
    + @Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld", fluent = false, chain = false)

    @@ -104,6 +107,10 @@ instances of a builder as keys in a set or map. However, that's not a sensible thing to do. Hence, no hashCode or equals.

    Generics are sorted out for you. +

    + If an explicit constructor is present, but @Builder is placed on the class, then the builder will be generated as if an explicit constructor is present with the + same arguments list as what @AllArgsConstructor would produce. If this constructor does not exist, a compile time error will result. Usually you should just either let + lombok make this constructor (delete your constructor from the source), or, move the @Builder annotation to the constructor.

    -- cgit