diff options
Diffstat (limited to 'website/features')
23 files changed, 281 insertions, 134 deletions
diff --git a/website/features/Builder.html b/website/features/Builder.html new file mode 100644 index 00000000..b4731b07 --- /dev/null +++ b/website/features/Builder.html @@ -0,0 +1,170 @@ +<!DOCTYPE html> +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + <link rel="stylesheet" type="text/css" href="../logi/reset.css" /> + <link rel="stylesheet" type="text/css" href="features.css" /> + <link rel="shortcut icon" href="../favicon.ico" type="image/x-icon" /> + <meta name="description" content="Spice up your java" /> + <title>@Builder</title> +</head><body><div id="pepper"> + <div class="minimumHeight"></div> + <div class="meat"> + <div class="header"><a href="../index.html">Project Lombok</a></div> + <h1>@Builder</h1> + <div class="byline">... and Bob's your uncle: No-hassle fancy-pants APIs for object creation!</div> + <div class="since"> + <h3>Since</h3> + <p> + <code>@Builder</code> was introduced as experimental feature in lombok v0.12.0. + </p><p> + <code>@Builder</code> gained <code>@Singular</code> support and was promoted to the main <code>lombok</code> package since lombok v1.16.0. + </p> + </div> + <div class="overview"> + <h3>Overview</h3> + <p> + The <code>@Builder</code> annotation produces complex builder APIs for your classes. + </p><p> + <code>@Builder</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>@Builder</code> can be placed on a class, or on a constructor, or on a static method. While the "on a class" and "on a constructor" + mode are the most common use-case, <code>@Builder</code> is most easily explained with the "static method" use-case. + </p><p> + A static method annotated with <code>@Builder</code> (from now on called the <em>target</em>) causes the following 7 things to be generated:<ul> + <li>An inner static class named <code><em>Foo</em>Builder</code>, with the same type arguments as the static method (called the <em>builder</em>).</li> + <li>In the <em>builder</em>: One private non-static non-final field for each parameter of the <em>target</em>.</li> + <li>In the <em>builder</em>: A package private no-args empty constructor.</li> + <li>In the <em>builder</em>: A 'setter'-like method for each parameter of the <em>target</em>: 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.</li> + <li>In the <em>builder</em>: A <code>build()</code> method which calls the static method, passing in each field. It returns the same type that the + <em>target</em> returns.</li> + <li>In the <em>builder</em>: A sensible <code>toString()</code> implementation.</li> + <li>In the class containing the <em>target</em>: A <code>builder()</code> method, which creates a new instance of the <em>builder</em>.</li> + </ul> + Each listed generated element will be silently skipped if that element already exists (disregarding parameter counts and looking only at names). This + includes the <em>builder</em> 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. You may not put any other method (or constructor) generating lombok annotation + on a builder class though; for example, you can not put <code>@EqualsAndHashCode</code> on the builder class. + </p><p> + <code>@Builder</code> can generate so-called 'singular' methods for collection parameters/fields. These take 1 element instead of an entire list, and add the + element to the list. For example: <code>Person.builder().job("Mythbusters").job("Unchained Reaction").build();</code> would result in the <code>List<String> jobs</code> + field to have 2 strings in it. To get this behaviour, the field/parameter needs to be annotated with <code>@Singular</code>. The feature has <a href="#singular">its own documentation</a>. + </p><p> + Now that the "static method" mode is clear, putting a <code>@Builder</code> 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. + </p><p> + Finally, applying <code>@Builder</code> to a class is as if you added <code>@AllArgsConstructor(access = AccessLevel.PACKAGE)</code> to the class and applied the + <code>@Builder</code> 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 <code>@Builder</code> annotation on the constructor instead of on the class. + </p><p> + The name of the builder class is <code><em>Foobar</em>Builder</code>, where <em>Foobar</em> is the simplified, title-cased form of the return type of the + <em>target</em> - that is, the name of your type for <code>@Builder</code> on constructors and types, and the name of the return type for <code>@Builder</code> + on static methods. For example, if <code>@Builder</code> is applied to a class named <code>com.yoyodyne.FancyList<T></code>, then the builder name will be + <code>FancyListBuilder<T></code>. If <code>@Builder</code> is applied to a static method that returns <code>void</code>, the builder will be named + <code>VoidBuilder</code>. + </p><p> + The configurable aspects of builder are:<ul> + <li>The <em>builder's class name</em> (default: return type + 'Builder')</li> + <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>@Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld")</code><br /> + </p> + </div> + <div class="overview"> + <h3><a name="singular">@Singular</a></h3> + <p> + By annotating one of the parameters (if annotating a static method or constructor with <code>@Builder</code>) or fields (if annotating a class with <code>@Builder</code>) with the + <code>@Singular</code> annotation, lombok will treat that builder node as a collection, and it generates 2 'adder' methods instead of a 'setter' method. One which adds a single element to the collection, and one + which adds all elements of another collection to the collection. No setter to just set the collection (replacing whatever was already added) will be generated. These 'singular' builders + are very complicated in order to guarantee the following properties: + <ul> + <li>When invoking <code>build()</code>, the produced collection will be immutable.</li> + <li>Calling one of the 'adder' methods after invoking <code>build()</code> does not modify any already generated objects, and, if <code>build()</code> is later called again, another collection with all the elements added since the creation of the builder is generated.</li> + <li>The produced collection will be compacted to the smallest feasible format while remaining efficient.</li> + </ul> + </p><p> + <code>@Singular</code> can only be applied to collection types known to lombok. Currently, the supported types are: + <ul> + <li><a href="http://docs.oracle.com/javase/8/docs/api/java/util/package-summary.html"><code>java.util</code></a>:<ul> + <li><code>Iterable</code>, <code>Collection</code>, and <code>List</code> (backed by a compacted unmodifiable <code>ArrayList</code> in the general case).</li> + <li><code>Set</code>, <code>SortedSet</code>, and <code>NavigableSet</code> (backed by a smartly sized unmodifiable <code>HashSet</code> or <code>TreeSet</code> in the general case).</li> + <li><code>Map</code>, <code>SortedMap</code>, and <code>NavigableMap</code> (backed by a smartly sized unmodifiable <code>HashMap</code> or <code>TreeMap</code> in the general case).</li> + </ul></li> + <li><a href="https://github.com/google/guava">Guava</a>'s <code>com.google.common.collect</code>:<ul> + <li><code>ImmutableCollection</code> and <code>ImmutableList</code> (backed by the builder feature of <code>ImmutableList</code>).</li> + <li><code>ImmutableSet</code> and <code>ImmutableSortedSet</code> (backed by the builder feature of those types).</li> + <li><code>ImmutableMap</code>, <code>ImmutableBiMap</code>, and <code>ImmutableSortedMap</code> (backed by the builder feature of those types).</li> + </ul></li> + </ul> + </p><p> + If your identifiers are written in common english, lombok assumes that the name of any collection with <code>@Singular</code> 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 <code>statuses</code>, then the add-one method will automatically + be called <code>status</code>. You can also specify the singular form of your identifier explictly by passing the singular form as argument to the annotation like so: <code>@Singular("axis") List<Line> axes;</code>.<br /> + If lombok cannot singularize your identifier, or it is ambiguous, lombok will generate an error and force you to explicitly specify the singular name. + </p><p> + 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="Singular-snippet.html">here</a>. + </p> + </div> + <div class="snippets"> + <div class="pre"> + <h3>With Lombok</h3> + <div class="snippet">@HTML_PRE@</div> + </div> + <div class="sep"></div> + <div class="post"> + <h3>Vanilla Java</h3> + <div class="snippet">@HTML_POST@</div> + </div> + </div> + <div style="clear: left;"></div> + <div class="overview confKeys"> + <h3>Supported configuration keys:</h3> + <dl> + <dt><code>lombok.builder.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set)</dt> + <dd>Lombok will flag any usage of <code>@Builder</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. + <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). + </dl> + </div> + <div class="overview"> + <h3>Small print</h3><div class="smallprint"> + <p> + @Singular support for <code>java.util.NavigableMap/Set</code> only works if you are compiling with JDK1.8 or higher. + </p><p> + You cannot manually provide some or all parts of a <code>@Singular</code> node; the code lombok generates is too complex for this. If you want to + manually control (part of) the builder code associated with some field or parameter, don't use <code>@Singular</code> and add everything you need manually. + </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 an implementation detail of the current implementation of the <code>java.util</code> recipes for <code>@Singular @Builder</code>. + </p> + </div> + </div> + <div class="footer"> + <a href="index.html">Back to features</a> | <a href="Value.html">Previous feature (@Value)</a> | <a href="SneakyThrows.html">Next feature (@SneakyThrows)</a><br /> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + </div> + <div style="clear: both;"></div> + </div> +</div> +<script type="text/javascript"> + var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); + document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); +</script> +<script type="text/javascript"> + try { + var pageTracker = _gat._getTracker("UA-9884254-1"); + pageTracker._trackPageview(); + } catch(err) {} +</script> +</body></html> diff --git a/website/features/Cleanup.html b/website/features/Cleanup.html index f4b16946..a6f25935 100644 --- a/website/features/Cleanup.html +++ b/website/features/Cleanup.html @@ -68,7 +68,7 @@ </div> <div class="footer"> <a href="index.html">Back to features</a> | <a href="NonNull.html">Previous feature (@NonNull)</a> | <a href="GetterSetter.html">Next feature (@Getter / @Setter)</a><br /> - <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/Data.html b/website/features/Data.html index c3d0a644..ed06f299 100644 --- a/website/features/Data.html +++ b/website/features/Data.html @@ -66,7 +66,7 @@ </div> <div class="footer"> <a href="index.html">Back to features</a> | <a href="Constructor.html">Previous feature (@<em>X</em>Constructor)</a> | <a href="Value.html">Next feature (@Value)</a><br /> - <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/EqualsAndHashCode.html b/website/features/EqualsAndHashCode.html index 32dcb6c3..0cad6b1b 100644 --- a/website/features/EqualsAndHashCode.html +++ b/website/features/EqualsAndHashCode.html @@ -76,7 +76,7 @@ </div> <div class="footer"> <a href="index.html">Back to features</a> | <a href="ToString.html">Previous feature (@ToString)</a> | <a href="Constructor.html">Next feature (@<em>X</em>Constructor)</a><br /> - <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/GetterLazy.html b/website/features/GetterLazy.html index a438f08a..ad08b480 100644 --- a/website/features/GetterLazy.html +++ b/website/features/GetterLazy.html @@ -48,7 +48,7 @@ </div> <div class="footer"> <a href="index.html">Back to features</a> | <a href="Synchronized.html">Previous feature (@Synchronized)</a> | <a href="Log.html">Next feature (@Log)</a><br /> - <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/GetterSetter.html b/website/features/GetterSetter.html index ad83f86a..760e1876 100644 --- a/website/features/GetterSetter.html +++ b/website/features/GetterSetter.html @@ -87,7 +87,7 @@ </div> <div class="footer"> <a href="index.html">Back to features</a> | <a href="Cleanup.html">Previous feature (@Cleanup)</a> | <a href="ToString.html">Next feature (@ToString)</a><br /> - <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/Log.html b/website/features/Log.html index 8b635280..22e5d293 100644 --- a/website/features/Log.html +++ b/website/features/Log.html @@ -83,7 +83,7 @@ </div> <div class="footer"> <a href="index.html">Back to features</a> | <a href="GetterLazy.html">Previous feature (@Getter(lazy=true))</a> | <a href="configuration.html">Next feature (configuration)</a><br /> - <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/Singular-snippet.html b/website/features/Singular-snippet.html new file mode 100644 index 00000000..7afbebf8 --- /dev/null +++ b/website/features/Singular-snippet.html @@ -0,0 +1,43 @@ +<!DOCTYPE html> +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + <link rel="stylesheet" type="text/css" href="../logi/reset.css" /> + <link rel="stylesheet" type="text/css" href="features.css" /> + <link rel="shortcut icon" href="../favicon.ico" type="image/x-icon" /> + <meta name="description" content="Spice up your java" /> + <title>@Builder's @Singular (snippet)</title> +</head><body><div id="pepper"> + <div class="minimumHeight"></div> + <div class="meat"> + <div class="header"><a href="../index.html">Project Lombok</a></div> + <h1>@Singular snippet</h1> + <div class="singleColumnSnippets"> + <div class="pre"> + <h3>With Lombok</h3> + <div class="snippet">@HTML_PRE@</div> + </div> + <div class="sep"></div> + <div class="post"> + <h3>Vanilla Java</h3> + <div class="snippet">@HTML_POST@</div> + </div> + </div> + <div style="clear: left;"></div> + <div class="footer"> + <a href="Builder.html">Back to @Builder</a><br /> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + </div> + <div style="clear: both;"></div> + </div> +</div> +<script type="text/javascript"> + var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); + document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); +</script> +<script type="text/javascript"> + try { + var pageTracker = _gat._getTracker("UA-9884254-1"); + pageTracker._trackPageview(); + } catch(err) {} +</script> +</body></html> diff --git a/website/features/SneakyThrows.html b/website/features/SneakyThrows.html index e1cd6685..55f4a0b8 100644 --- a/website/features/SneakyThrows.html +++ b/website/features/SneakyThrows.html @@ -77,8 +77,8 @@ </div> </div> <div class="footer"> - <a href="index.html">Back to features</a> | <a href="Value.html">Previous feature (@Value)</a> | <a href="Synchronized.html">Next feature (@Synchronized)</a><br /> - <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="index.html">Back to features</a> | <a href="Builder.html">Previous feature (@Builder)</a> | <a href="Synchronized.html">Next feature (@Synchronized)</a><br /> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/Synchronized.html b/website/features/Synchronized.html index 85c161c3..df9db6b0 100644 --- a/website/features/Synchronized.html +++ b/website/features/Synchronized.html @@ -67,7 +67,7 @@ </div> <div class="footer"> <a href="index.html">Back to features</a> | <a href="SneakyThrows.html">Previous feature (@SneakyThrows)</a> | <a href="GetterLazy.html">Next feature (@Getter(lazy=true))</a><br /> - <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/ToString.html b/website/features/ToString.html index 57bbd0f0..5071048c 100644 --- a/website/features/ToString.html +++ b/website/features/ToString.html @@ -74,7 +74,7 @@ </div> <div class="footer"> <a href="index.html">Back to features</a> | <a href="GetterSetter.html">Previous feature (@Getter / @Setter)</a> | <a href="EqualsAndHashCode.html">Next feature (@EqualsAndHashCode)</a><br /> - <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/Value.html b/website/features/Value.html index 0e221b63..25bba650 100644 --- a/website/features/Value.html +++ b/website/features/Value.html @@ -20,6 +20,7 @@ <code>@Value</code> no longer implies <code>@Wither</code> since lombok v0.11.8. </p><p> <code>@Value</code> promoted to the main <code>lombok</code> package since lombok v0.12.0. + </p> </div> <div class="overview"> <h3>Overview</h3> @@ -67,8 +68,8 @@ </div> </div> <div class="footer"> - <a href="index.html">Back to features</a> | <a href="Data.html">Previous feature (@Data)</a> | <a href="SneakyThrows.html">Next feature (@SneakyThrows)</a><br /> - <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="index.html">Back to features</a> | <a href="Data.html">Previous feature (@Data)</a> | <a href="Builder.html">Next feature (@Builder)</a><br /> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/configuration.html b/website/features/configuration.html index acf874e7..1f31fe01 100644 --- a/website/features/configuration.html +++ b/website/features/configuration.html @@ -73,7 +73,7 @@ <div style="clear: left;"></div> <div class="footer"> <a href="index.html">Back to features</a> | <a href="Log.html">Previous feature (@Log)</a> | <span class="disabled">Next feature</span><br /> - <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/experimental/Accessors.html b/website/features/experimental/Accessors.html index 20590a07..3934c339 100644 --- a/website/features/experimental/Accessors.html +++ b/website/features/experimental/Accessors.html @@ -97,8 +97,8 @@ </div> </div> <div class="footer"> - <a href="index.html">Back to experimental features</a> | <a href="Builder.html">Previous feature (@Builder)</a> | <a href="ExtensionMethod.html">Next feature (@ExtensionMethod)</a><br /> - <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="index.html">Back to experimental features</a> | <span class="disabled">Previous feature</span> | <a href="ExtensionMethod.html">Next feature (@ExtensionMethod)</a><br /> + <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/experimental/Builder.html b/website/features/experimental/Builder.html index a8e21b9a..9f1266dc 100644 --- a/website/features/experimental/Builder.html +++ b/website/features/experimental/Builder.html @@ -12,118 +12,13 @@ <div class="header"><a href="../../index.html">Project Lombok</a></div> <h1>@Builder</h1> <div class="byline">... and Bob's your uncle: No-hassle fancy-pants APIs for object creation!</div> - <div class="since"> - <h3>Since</h3> - <p> - @Builder was introduced as experimental feature in lombok v0.12.0. - </p> - </div> - <div class="experimental"> - <h3>Experimental</h3> - <p> - Experimental because: - <ul> - <li>New feature - community feedback requested.</li> - </ul> - Current status: <em>sure thing</em> - This feature will move to the core package soon. - </div> - <div class="overview"> - <h3>Overview</h3> - <p> - The <code>@Builder</code> annotation produces complex builder APIs for your classes. - </p><p> - <code>@Builder</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").worksAt("Mythbusters").build();</code> - </p><p> - <code>@Builder</code> can be placed on a class, or on a constructor, or on a static method. While the "on a class" and "on a constructor" - mode are the most common use-case, <code>@Builder</code> is most easily explained with the "static method" use-case. - </p><p> - A static method annotated with <code>@Builder</code> (from now on called the <em>target</em>) causes the following 7 things to be generated:<ul> - <li>An inner static class named <code><em>Foo</em>Builder</code>, with the same type arguments as the static method (called the <em>builder</em>).</li> - <li>In the <em>builder</em>: One private non-static non-final field for each parameter of the <em>target</em>.</li> - <li>In the <em>builder</em>: A package private no-args empty constructor.</li> - <li>In the <em>builder</em>: A 'setter'-like method for each parameter of the <em>target</em>: 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.</li> - <li>In the <em>builder</em>: A <code>build()</code> method which calls the static method, passing in each field. It returns the same type that the - <em>target</em> returns.</li> - <li>In the <em>builder</em>: A sensible <code>toString()</code> implementation.</li> - <li>In the class containing the <em>target</em>: A <code>builder()</code> method, which creates a new instance of the <em>builder</em>.</li> - </ul> - Each listed generated element will be silently skipped if that element already exists (disregarding parameter counts and looking only at names). This - includes the <em>builder</em> 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. You may not put any other method (or constructor) generating lombok annotation - on a builder class though; for example, you can not put <code>@EqualsAndHashCode</code> on the builder class. - </p><p> - Now that the "static method" mode is clear, putting a <code>@Builder</code> 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. - </p><p> - Finally, applying <code>@Builder</code> to a class is as if you added <code>@AllArgsConstructor(access = AccessLevel.PACKAGE)</code> to the class and applied the - <code>@Builder</code> 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 <code>@Builder</code> annotation on the constructor instead of on the class. - </p><p> - The name of the builder class is <code><em>Foobar</em>Builder</code>, where <em>Foobar</em> is the simplified, title-cased form of the return type of the - <em>target</em> - that is, the name of your type for <code>@Builder</code> on constructors and types, and the name of the return type for <code>@Builder</code> - on static methods. For example, if <code>@Builder</code> is applied to a class named <code>com.yoyodyne.FancyList<T></code>, then the builder name will be - <code>FancyListBuilder<T></code>. If <code>@Builder</code> is applied to a static method that returns <code>void</code>, the builder will be named - <code>VoidBuilder</code>. - </p><p> - The configurable aspects of builder are:<ul> - <li>The <em>builder's class name</em> (default: return type + 'Builder')</li> - <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> - <li>The 'fluent' nature of the generated 'setter'-like methods. A fluent 'setter' is named just <code>fieldName()</code>, a non-fluent one is named <code>setFieldName()</code>. (default: <code>true</code>)</li> - <li>The 'chain' nature of the generated 'setter'-like methods. A chainable 'setter' returns the builder object itself, letting you chain 'set' calls. A non-chainable setter returns <code>void</code>. (default: <code>true</code>)</li> - </ul> - Example usage where all options are changed from their defaults:<br /> - <code>@Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld", fluent = false, chain = false)</code><br /> - </p> - </div> - <div class="snippets"> - <div class="pre"> - <h3>With Lombok</h3> - <div class="snippet">@HTML_PRE@</div> - </div> - <div class="sep"></div> - <div class="post"> - <h3>Vanilla Java</h3> - <div class="snippet">@HTML_POST@</div> - </div> - </div> - <div style="clear: left;"></div> - <div class="overview confKeys"> - <h3>Supported configuration keys:</h3> - <dl> - <dt><code>lombok.builder.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set)</dt> - <dd>Lombok will flag any usage of <code>@Builder</code> as a warning or error if configured.</dd> - </dl> - </div> - <div class="overview"> - <h3>Small print</h3><div class="smallprint"> - <p> - Another strategy for fluent APIs is that the programmer using your library statically imports your 'builder' method. In this case, you might want to name your builder - method equal to your type's name. So, the builder method for a class called <code>Person</code> would become <code>person()</code>. This is nicer if the builder method - is statically imported. - </p><p> - If the return type of your target static method is a type parameter (such as <code>T</code>), lombok will enforce an explicit builder class name. - </p><p> - You don't HAVE to use <code>@Builder</code> to build anything; you can for example put it on a static method that has lots of parameter to improve the API of it. - In this case, we suggest you use <code>buildMethodName = </code> to rename the build method to <code>execute()</code> instead. - </p><p> - The builder class will NOT get an auto-generated implementation of <code>hashCode</code> or <code>equals</code> methods! These would suggest that it is sensible to use - instances of a builder as keys in a set or map. However, that's not a sensible thing to do. Hence, no <code>hashCode</code> or <code>equals</code>. - </p><p> - Generics are sorted out for you. - </p><p> - If an explicit constructor is present, but <code>@Builder</code> 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 <code>@AllArgsConstructor</code> 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 <code>@Builder</code> annotation to the constructor. - </p> - </div> + <div class="moved"> + @Builder has been promoted to the core package in lombok release v1.16.0.<br /> + The documentation has been moved here: <a href="../Builder.html">@lombok.Builder</a>. </div> <div class="footer"> - <a href="index.html">Back to experimental features</a> | <span class="disabled">Previous feature</span> | <a href="Accessors.html">Next feature (@Accessors)</a><br /> - <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="index.html">Back to experimental features</a><br /> + <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/experimental/ExtensionMethod.html b/website/features/experimental/ExtensionMethod.html index 58aaf1b3..f1735376 100644 --- a/website/features/experimental/ExtensionMethod.html +++ b/website/features/experimental/ExtensionMethod.html @@ -98,7 +98,7 @@ System.out.println(x.or("Hello, World!"));</pre> </div> <div class="footer"> <a href="index.html">Back to experimental features</a> | <a href="Accessors.html">Previous feature (@Accessors)</a> | <a href="FieldDefaults.html">Next feature (@FieldDefaults)</a><br /> - <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/experimental/FieldDefaults.html b/website/features/experimental/FieldDefaults.html index 12ea7d80..5ad30952 100644 --- a/website/features/experimental/FieldDefaults.html +++ b/website/features/experimental/FieldDefaults.html @@ -73,7 +73,7 @@ </div> <div class="footer"> <a href="index.html">Back to experimental features</a> | <a href="ExtensionMethod.html">Previous feature (@ExtensionMethod)</a> | <a href="Delegate.html">Next feature (@Delegate)</a><br /> - <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/experimental/Value.html b/website/features/experimental/Value.html new file mode 100644 index 00000000..c2b335e6 --- /dev/null +++ b/website/features/experimental/Value.html @@ -0,0 +1,36 @@ +<!DOCTYPE html> +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + <link rel="stylesheet" type="text/css" href="../../logi/reset.css" /> + <link rel="stylesheet" type="text/css" href="../features.css" /> + <link rel="shortcut icon" href="../../favicon.ico" type="image/x-icon" /> + <meta name="description" content="Spice up your java" /> + <title>EXPERIMENTAL - @Value</title> +</head><body><div id="pepper"> + <div class="minimumHeight"></div> + <div class="meat"> + <div class="header"><a href="../../index.html">Project Lombok</a></div> + <h1>@Value</h1> + <div class="byline">Immutable classes made very easy.</div> + <div class="moved"> + @Value has been promoted to the core package in lombok release v1.12.0.<br /> + The documentation has been moved here: <a href="../Value.html">@lombok.Value</a>. + </div> + <div class="footer"> + <a href="index.html">Back to experimental features</a><br /> + <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + </div> + <div style="clear: both;"></div> + </div> +</div> +<script type="text/javascript"> + var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); + document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); +</script> +<script type="text/javascript"> + try { + var pageTracker = _gat._getTracker("UA-9884254-1"); + pageTracker._trackPageview(); + } catch(err) {} +</script> +</body></html> diff --git a/website/features/experimental/Wither.html b/website/features/experimental/Wither.html index 9ca43a46..81ef475e 100644 --- a/website/features/experimental/Wither.html +++ b/website/features/experimental/Wither.html @@ -93,7 +93,7 @@ </div> <div class="footer"> <a href="index.html">Back to experimental features</a> | <a href="Delegate.html">Previous feature (@Delegate)</a> | <a href="onX.html">Next feature (onX)</a><br /> - <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/experimental/index.html b/website/features/experimental/index.html index f37712e0..a5932b73 100644 --- a/website/features/experimental/index.html +++ b/website/features/experimental/index.html @@ -22,8 +22,6 @@ Features that receive positive community feedback and which seem to produce clean, flexible code will eventually become accepted as a core feature and move out of the experimental package. <dl> - <dt><a href="Builder.html"><code>@Builder</code></a></dt> - <dd>... and Bob's your uncle: No-hassle fancy-pants APIs for object creation!</dd> <dt><a href="Accessors.html"><code>@Accessors</code></a></dt> <dd>A more fluent API for getters and setters.</dd> <dt><a href="ExtensionMethod.html"><code>@ExtensionMethod</code></a></dt> @@ -50,10 +48,12 @@ <dl> <dt><a href="../Value.html"><code>@Value</code></a>: Promoted</dt> <dd><code>@Value</code> has proven its value and has been moved to the main package.</li> + <dt><a href="../Builder.html"><code>@Builder</code></a>: Promoted</dt> + <dd><code>@Builder</code> is a solid base to build APIs on, and has been moved to the main package.</li> </dl> </div> <div class="footer"> - <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/experimental/onX.html b/website/features/experimental/onX.html index ba2ead86..064db557 100644 --- a/website/features/experimental/onX.html +++ b/website/features/experimental/onX.html @@ -70,7 +70,7 @@ </div> <div class="footer"> <a href="index.html">Back to experimental features</a> | <a href="Wither.html">Previous feature (@Wither)</a> | <span class="disabled">Next feature</span><br /> - <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> diff --git a/website/features/features.css b/website/features/features.css index b3017fe8..58897ccd 100644 --- a/website/features/features.css +++ b/website/features/features.css @@ -92,7 +92,7 @@ dd { white-space: nowrap; } -.snippets { +.snippets, .singleColumnSnippets { margin-top: 0px; } diff --git a/website/features/index.html b/website/features/index.html index 09a148f0..84457077 100644 --- a/website/features/index.html +++ b/website/features/index.html @@ -32,6 +32,8 @@ <code>@Getter</code> on all fields, and <code>@Setter</code> on all non-final fields, and <code>@RequiredArgsConstructor</code>!</dd> <dt><a href="Value.html"><code>@Value</code></a></dt> <dd>Immutable classes made very easy.</dd> + <dt><a href="Builder.html"><code>@Builder</code></a></dt> + <dd>... and Bob's your uncle: No-hassle fancy-pants APIs for object creation!</dd> <dt><a href="SneakyThrows.html"><code>@SneakyThrows</code></a></dt> <dd>To boldly throw checked exceptions where no one has thrown them before!</dd> <dt><a href="Synchronized.html"><code>@Synchronized</code></a></dt> @@ -70,7 +72,7 @@ your source files for source-level tools such as javadoc and GWT. More information about how to run delombok, including instructions for build tools can be found at the <a href="delombok.html">delombok page</a>.</div> <div class="footer"> - <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2014 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> </div> |