diff options
Diffstat (limited to 'website')
| -rw-r--r-- | website/features/Builder.html | 9 | ||||
| -rw-r--r-- | website/features/Constructor.html | 3 | ||||
| -rw-r--r-- | website/features/Data.html | 2 | ||||
| -rw-r--r-- | website/features/NonNull.html | 5 | ||||
| -rw-r--r-- | website/features/configuration.html | 9 | ||||
| -rw-r--r-- | website/features/experimental/FieldDefaults.html | 4 | ||||
| -rw-r--r-- | website/features/experimental/Helper.html | 83 | ||||
| -rw-r--r-- | website/features/experimental/UtilityClass.html | 2 | ||||
| -rw-r--r-- | website/features/experimental/index.html | 2 |
9 files changed, 112 insertions, 7 deletions
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 @@ <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> + <li>In the class containing the <em>target</em>: A static <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 @@ -59,6 +59,8 @@ <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> + If using <code>@Builder</code> to generate builders to produce instances of your own class (this is always the case unless adding <code>@Builder</code> to a static method that doesn't return your own type), you can use <code>@Builder(toBuilder = true)</code> to also generate an instance method in your class called <code>toBuilder()</code>; it creates a new builder that starts out with all the values of this instance. You can put the <code>@Builder.ObtainVia</code> annotation on the parameters (in case of a constructor or static method) or fields (in case of <code>@Builder</code> 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: <code>@Builder.ObtainVia(method = "calculateFoo")</code>. + </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 @@ -69,9 +71,10 @@ <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>If you want <code>toBuilder()</code> (default: no)</li> </ul> Example usage where all options are changed from their defaults:<br /> - <code>@Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld")</code><br /> + <code>@Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld", toBuilder = true)</code><br /> </p> </div> <div class="overview"> @@ -147,6 +150,8 @@ 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><p> + With <code>toBuilder = true</code> applied to static methods, any type parameter on the annotated static method must show up in the returntype. </p> </div> </div> diff --git a/website/features/Constructor.html b/website/features/Constructor.html index cbb76fcf..d7168372 100644 --- a/website/features/Constructor.html +++ b/website/features/Constructor.html @@ -17,8 +17,7 @@ <p> This set of 3 annotations generate a constructor that will accept 1 parameter for certain fields, and simply assigns this parameter to the field. </p><p> - <code>@NoArgsConstructor</code> will generate a constructor with no parameters. If this is not possible (because of final fields), a compiler error will result instead. - For fields with constraints, such as <code>@NonNull</code> fields, <em>no</em> check or assignment is generated, so be aware that these constraints may then not be + <code>@NoArgsConstructor</code> will generate a constructor with no parameters. If this is not possible (because of final fields), a compiler error will result instead, unless <code>@NoArgsConstructor(force = true)</code> is used, then all final fields are initialized with 0 / false / null. For fields with constraints, such as <code>@NonNull</code> fields, <em>no</em> check or assignment is generated, so be aware that these constraints may then not be fulfilled until those fields are properly initialized later. Certain java constructs, such as hibernate and the Service Provider Interface require a no-args constructor. This annotation is useful primarily in combination with either <code>@Data</code> or one of the other constructor generating annotations. </p><p> diff --git a/website/features/Data.html b/website/features/Data.html index ed06f299..4c37247d 100644 --- a/website/features/Data.html +++ b/website/features/Data.html @@ -18,7 +18,7 @@ <p> <code>@Data</code> is a convenient shortcut annotation that bundles the features of <a href="ToString.html"><code>@ToString</code></a>, <a href="EqualsAndHashCode.html"><code>@EqualsAndHashCode</code></a>, <a href="GetterSetter.html"><code>@Getter</code> / <code>@Setter</code></a> and <a href="Constructor.html"><code>@RequiredArgsConstructor</code></a> together: In other words, <code>@Data</code> generates <em>all</em> the boilerplate that is normally associated with simple POJOs (Plain Old Java Objects) and beans: getters for all fields, setters for all non-final fields, and appropriate <code>toString</code>, <code>equals</code> and <code>hashCode</code> implementations that involve the fields of the class, and a constructor that initializes all final fields, as well as all non-final fields with no initializer that have been marked with <code>@NonNull</code>, in order to ensure the field is never null. </p><p> - <code>@Data</code> is like having implicit <code>@Getter</code>, <code>@Setter</code>, <code>@ToString</code>, <code>@EqualsAndHashCode</code> and <code>@RequiredArgsConstructor</code> annotations on the class. However, the parameters of these annotations (such as <code>callSuper</code>, <code>includeFieldNames</code> and <code>exclude</code>) cannot be set with <code>@Data</code>. If you need to set non-default values for any of these parameters, just add those annotations explicitly; <code>@Data</code> is smart enough to defer to those annotations. + <code>@Data</code> is like having implicit <code>@Getter</code>, <code>@Setter</code>, <code>@ToString</code>, <code>@EqualsAndHashCode</code> and <code>@RequiredArgsConstructor</code> annotations on the class (except that no constructor will be generated if any explicitly written constructor exists). However, the parameters of these annotations (such as <code>callSuper</code>, <code>includeFieldNames</code> and <code>exclude</code>) cannot be set with <code>@Data</code>. If you need to set non-default values for any of these parameters, just add those annotations explicitly; <code>@Data</code> is smart enough to defer to those annotations. </p><p> All generated getters and setters will be <code>public</code>. To override the access level, annotate the field or class with an explicit <code>@Setter</code> and/or <code>@Getter</code> annotation. You can also use this annotation (by combining it with <code>AccessLevel.NONE</code>) to suppress generating a getter and/or setter altogether. </p><p> diff --git a/website/features/NonNull.html b/website/features/NonNull.html index d62441f4..50acf627 100644 --- a/website/features/NonNull.html +++ b/website/features/NonNull.html @@ -15,7 +15,7 @@ <div class="overview"> <h3>Overview</h3> <p> - <em>NEW in Lombok 0.11.10: </em>You can use <code>@NonNull</code> on the parameter of a method or constructor to have lombok generate a null-check statement for you. + <em>NEW in Lombok 0.11.10: </em>You can use <code>@NonNull</code> on the parameter of a method or constructor to have lombok generate a null-check statement for you.<br /> </p><p> Lombok has always treated any annotation named <code>@NonNull</code> on a field as a signal to generate a null-check if lombok generates an entire method or constructor for you, via for example <a href="Data.html"><code>@Data</code></a>. Now, however, using lombok's own <code>@lombok.NonNull</code> on a parameter results in the insertion of just the null-check @@ -60,6 +60,9 @@ this feature only triggers on lombok's own <code>@NonNull</code> annotation from the <code>lombok</code> package. </p><p> A <code>@NonNull</code> on a primitive parameter results in a warning. No null-check will be generated. + </p><p> + A <code>@NonNull</code> on a parameter of an abstract method used to generate a warning; starting with version 1.16.8, this is no longer the case, to acknowledge the notion that <code>@NonNull</code> also has a + documentary role. For the same reason, you can annotate a method as <code>@NonNull</code>; this is allowed, generates no warning, and does not generate any code. </p> </div> </div> diff --git a/website/features/configuration.html b/website/features/configuration.html index 7e79a9c0..21864409 100644 --- a/website/features/configuration.html +++ b/website/features/configuration.html @@ -85,6 +85,15 @@ <code>lombok.extern.findbugs.addSuppressFBWarnings = true</code> </div> </div> + <div class="overview" style="clear: left;"> + <h3>Config keys that can even affect source files with 0 lombok annotations</h3> + <p> + <div class="snippet example"> + <code>lombok.fieldDefaults.defaultPrivate = true</code><br /> + <code>lombok.fieldDefaults.defaultFinal = true</code> + </div> + Turning either of these options on means lombok will make <em>every</em> field in <em>every</em> source file final and/or private unless it has an explicit access modifier or annotation to suppress this. <a href="experimental/FieldDefaults.html">See the <code>@FieldDefaults</code> documentation for more</a>. + </div> <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 /> diff --git a/website/features/experimental/FieldDefaults.html b/website/features/experimental/FieldDefaults.html index 5ad30952..026f23fc 100644 --- a/website/features/experimental/FieldDefaults.html +++ b/website/features/experimental/FieldDefaults.html @@ -61,6 +61,10 @@ <dl> <dt><code>lombok.fieldDefaults.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set)</dt> <dd>Lombok will flag any usage of <code>@FieldDefaults</code> as a warning or error if configured.</dd> + <dt><code>lombok.fieldDefaults.defaultPrivate</code> = [<code>true</code> | <code>false</code>] (default: false)</dt> + <dd>(Since 1.16.8) If set to <code>true</code>, <em>every</em> field in <em>every</em> class or enum anywhere in the sources being compiled will be marked as <code>private</code> unless it has an explicit access modifier or the <code>@PackagePrivate</code> annotation, or an explicit <code>@FieldDefaults</code> annotation is present to override this config key.</dd> + <dt><code>lombok.fieldDefaults.defaultFinal</code> = [<code>true</code> | <code>false</code>] (default: false)</dt> + <dd>(Since 1.16.8) If set to <code>true</code>, <em>every</em> field in <em>every</em> class or enum anywhere in the sources being compiled will be marked as <code>final</code> unless it has the <code>@NonFinal</code> annotation, or an explicit <code>@FieldDefaults</code> annotation is present to override this config key.</dd> </dl> </div> <div class="overview"> diff --git a/website/features/experimental/Helper.html b/website/features/experimental/Helper.html new file mode 100644 index 00000000..7658b780 --- /dev/null +++ b/website/features/experimental/Helper.html @@ -0,0 +1,83 @@ +<!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>@Helper</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>@Helper</h1> + <div class="byline">With a little help from my friends... Helper methods for java.</div> + <div class="since"> + <h3>Since</h3> + <p> + <code>@Helper</code> was introduced as an experimental feature in lombok v1.16.6. + </p> + </div> + <div class="experimental"> + <h3>Experimental</h3> + <p> + Experimental because: + <ul> + <li>Lambdas with general function types offer an alternative strategy.</li> + <li>Perhaps a way to make helper methods with less boilerplate is possible, making this feature obsolete.</li> + </ul> + Current status: <em>unknown</em> - We don't have enough experience with this feature to make predictions on its future. + </div> + <div class="overview"> + <h3>Overview</h3> + <p> + This annotation lets you put methods in methods. You might not know this, but you can declare classes inside methods, and the methods in this class can access any (effectively) final local variable or parameter defined and set before the declaration. Unfortunately, to actually call any methods you'd have to make an instance of this method local class first, but that's where <code>@Helper</code> comes in and helps you out! Annotate a method local class with <code>@Helper</code> and it's as if all the methods in that helper class are methods that you can call directly, just as if java had allowed methods to exist inside methods. + </p><p> + Normally you'd have to declare an instance of your helper, for example: <code>HelperClass h = new HelperClass();</code> directly after declaring your helper class, and then call methods in your helper class with <code>h.helperMethod();</code>. With <code>@Helper</code>, both of these things are no longer needed: You do not need to waste a line of code declaring an instance of the helper, and you don't need to prefix all your calls to helper methods with <code>nameOfHelperInstance.</code> + </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"> + <h3>Small print</h3><div class="smallprint"> + <p> + <code>@Helper</code> requires that the helper class has a no-args constructor. A compiler error will be generated if this is not the case. + </p><p> + Currently, the instance of your helper that's made under the hood is called <code>$Foo</code>, where <code>Foo</code> is the name of your helper. We might change this in the future; please don't rely on this variable existing. We might even replace this later with a sibling method instead. + </p><p> + Please don't rely on <code>this</code> making any sense in the helper method code. You can refer to the real 'this' by using the syntax <code>NameOfMyClass.this</code>. + </p><p> + <em>ANY</em> unqualified method call in code that exists <em>below</em> the declaration of the helper method with the same name as any method in the helper is assumed to be a call to the helper. If the arguments don't end up being compatible, you get a compiler error. + </p><p> + Unless you're using JDK8 or higher (which introduced the concept of 'effectively final'), you'll have to declare local variables and parameters as <code>final</code> if you wish to refer to them in your method local class. This is a java limitation, not something specific to lombok's <code>@Helper</code>. + </p> + </div> + </div> + <div class="footer"> + <a href="index.html">Back to experimental features</a> | <a href="UtilityClass.html">Previous feature (@UtilityClass)</a> | <span class="disabled">Next feature</span><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/UtilityClass.html b/website/features/experimental/UtilityClass.html index 5526ec77..3c79b35e 100644 --- a/website/features/experimental/UtilityClass.html +++ b/website/features/experimental/UtilityClass.html @@ -61,7 +61,7 @@ </div> </div> <div class="footer"> - <a href="index.html">Back to experimental features</a> | <a href="onX.html">Previous feature (onX)</a> | <span class="disabled">Next feature</span><br /> + <a href="index.html">Back to experimental features</a> | <a href="onX.html">Previous feature (onX)</a> | <a href="Helper.html">Next feature (@Helper)</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> diff --git a/website/features/experimental/index.html b/website/features/experimental/index.html index 3f2d2802..ce21f819 100644 --- a/website/features/experimental/index.html +++ b/website/features/experimental/index.html @@ -36,6 +36,8 @@ <dd>Sup dawg, we heard you like annotations, so we put annotations in your annotations so you can annotate while you're annotating.</dd> <dt><a href="UtilityClass.html"><code>@UtilityClass</code></a></dt> <dd>Utility, metility, wetility! Utility classes for the masses.</dd> + <dt><a href="Helper.html"><code>@Helper</code></a></dt> + <dd>With a little help from my friends... Helper methods for java.</dd> </dl> </div> <div class="overview confKeys"> |