diff options
Diffstat (limited to 'website/templates')
| -rw-r--r-- | website/templates/features/experimental/SuperBuilder.html | 69 | ||||
| -rw-r--r-- | website/templates/features/experimental/index.html | 4 |
2 files changed, 73 insertions, 0 deletions
diff --git a/website/templates/features/experimental/SuperBuilder.html b/website/templates/features/experimental/SuperBuilder.html new file mode 100644 index 00000000..a1e8cb4d --- /dev/null +++ b/website/templates/features/experimental/SuperBuilder.html @@ -0,0 +1,69 @@ +<#import "_features.html" as f> + +<@f.scaffold title="@SuperBuilder" logline="Bob now knows his ancestors: Builders with fields from superclasses, too. "> + <@f.history> + <p> + <code>@SuperBuilder</code> was introduced as experimental feature in lombok v0.16.21. + </p> + </@f.history> + + <@f.overview> + <p> + The <code>@SuperBuilder</code> annotation produces complex builder APIs for your classes. + In contrast to <a href="/features/Builder"><code>@Builder</code></a>, <code>@SuperBuilder</code> also works with fields from superclasses. + However, it only works for types, and cannot be customized by providing a partial builder implementation. + Most importantly, it requires that <em>all superclasses</em> also have the <code>@SuperBuilder</code> annotation. + </p><p> + <code>@SuperBuilder</code> lets you automatically produce the code required to have your class be instantiable with code such as:<br /> + <code>Person.builder().name("Adam Savage").city("San Francisco").job("Mythbusters").job("Unchained Reaction").build();</code> + </p><p> + <code>@SuperBuilder</code> can generate so-called 'singular' methods for collection parameters/fields. For details, see <a href="/features/Builder#singular">the <code>@Singular</code> documentation in <code>@Builder</code></a>. + </p><p> + As lombok has no access to the fields of superclasses when generating the builder code, the methods for setting those superclass fields can only be in the builder of the superclass. + Therefore, a <code>@SuperBuilder</code> must extend the <code>@SuperBuilder</code> of the superclass in order to include those methods. + Furthermore, the generated builder code heavily relies on generics to avoid class casting when using the builder. + <code>@SuperBuilder</code> generates a private constructor on the class that takes a builder instances as a parameter. This constructor sets the fields of the new instance to the values from the builder. + </p><p> + To ensure type-safety, <code>@SuperBuilder</code> generates two inner builder classes for each annotated class, one abstract and one concrete class named <code><em>Foobar</em>Builder</code> and <code><em>Foobar</em>BuilderImpl</code> (where <em>Foobar</em> is the name of the annotated class). + </p><p> + The configurable aspects of builder are: + <ul> + <li> + The <em>build()</em> method's name (default: <code>"build"</code>) + </li><li> + The <em>builder()</em> method's name (default: <code>"builder"</code>) + </li> + </ul> + Example usage where all options are changed from their defaults:<br /> + <code>@SuperBuilder(buildMethodName = "execute", builderMethodName = "helloWorld")</code><br /> + </p> + </@f.overview> + + <@f.snippets name="Builder" /> + + <@f.confKeys> + <dt> + <code>lombok.builder.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + </dt><dd> + Lombok will flag any usage of <code>@SuperBuilder</code> as a warning or error if configured. + </dd><dt> + <code>lombok.singular.useGuava</code> = [<code>true</code> | <code>false</code>] (default: false) + </dt><dd> + If <code>true</code>, lombok will use guava's <code>ImmutableXxx</code> builders and types to implement <code>java.util</code> collection interfaces, instead of creating implementations based on <code>Collections.unmodifiableXxx</code>. 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 <code>ImmutableXxx</code> types. + </dd><dt> + <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> + </@f.confKeys> + + <@f.smallPrint> + <p> + @Singular support for <code>java.util.NavigableMap/Set</code> only works if you are compiling with JDK1.8 or higher. + </p><p> + The sorted collections (java.util: <code>SortedSet</code>, <code>NavigableSet</code>, <code>SortedMap</code>, <code>NavigableMap</code> and guava: <code>ImmutableSortedSet</code>, <code>ImmutableSortedMap</code>) require that the type argument of the collection has natural order (implements <code>java.util.Comparable</code>). There is no way to pass an explicit <code>Comparator</code> to use in the builder. + </p><p> + An <code>ArrayList</code> is used to store added elements as call methods of a <code>@Singular</code> marked field, if the target collection is from the <code>java.util</code> package, <em>even if the collection is a set or map</em>. 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 <code>ArrayList</code> 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 <code>java.util</code> recipes for <code>@Singular</code>. + </p> + </@f.smallPrint> +</@f.scaffold> diff --git a/website/templates/features/experimental/index.html b/website/templates/features/experimental/index.html index 21e8fceb..309303a0 100644 --- a/website/templates/features/experimental/index.html +++ b/website/templates/features/experimental/index.html @@ -62,6 +62,10 @@ <@main.feature title="@Helper" href="Helper"> With a little help from my friends... Helper methods for java. </@main.feature> + + <@main.feature title="@SuperBuilder" href="SuperBuilder"> + Bob now knows his ancestors: Builders with fields from superclasses, too. + </@main.feature> </div> <@f.confKeys> |