diff options
Diffstat (limited to 'website/features')
| -rw-r--r-- | website/features/Cleanup.html | 2 | ||||
| -rw-r--r-- | website/features/Data.html | 2 | ||||
| -rw-r--r-- | website/features/Delegate.html | 11 | ||||
| -rw-r--r-- | website/features/GetterLazy.html | 12 | ||||
| -rw-r--r-- | website/features/GetterSetter.html | 4 | ||||
| -rw-r--r-- | website/features/Log.html | 8 | ||||
| -rw-r--r-- | website/features/NonNull.html | 73 | ||||
| -rw-r--r-- | website/features/SneakyThrows.html | 10 | ||||
| -rw-r--r-- | website/features/Synchronized.html | 2 | ||||
| -rw-r--r-- | website/features/ToString.html | 2 | ||||
| -rw-r--r-- | website/features/Value.html (renamed from website/features/experimental/Value.html) | 36 | ||||
| -rw-r--r-- | website/features/experimental/Accessors.html | 2 | ||||
| -rw-r--r-- | website/features/experimental/Builder.html | 134 | ||||
| -rw-r--r-- | website/features/experimental/Wither.html | 4 | ||||
| -rw-r--r-- | website/features/experimental/index.html | 11 | ||||
| -rw-r--r-- | website/features/experimental/onX.html | 2 | ||||
| -rw-r--r-- | website/features/index.html | 23 | ||||
| -rw-r--r-- | website/features/val.html | 2 |
18 files changed, 280 insertions, 60 deletions
diff --git a/website/features/Cleanup.html b/website/features/Cleanup.html index d1637dd4..a6e41f39 100644 --- a/website/features/Cleanup.html +++ b/website/features/Cleanup.html @@ -60,7 +60,7 @@ </div> </div> <div class="footer"> - <a href="index.html">Back to features</a> | <a href="Data.html">Previous feature (@Data)</a> | <a href="Synchronized.html">Next feature (@Synchronized)</a><br /> + <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-2013 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/Data.html b/website/features/Data.html index 8ace96cb..ad3aa892 100644 --- a/website/features/Data.html +++ b/website/features/Data.html @@ -75,7 +75,7 @@ </div> </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="Cleanup.html">Next feature (@Cleanup)</a><br /> + <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-2013 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/Delegate.html b/website/features/Delegate.html index 532f3f54..02cdf290 100644 --- a/website/features/Delegate.html +++ b/website/features/Delegate.html @@ -55,16 +55,15 @@ When passing classes to the annotation's <code>types</code> or <code>excludes</code> parameter, you cannot include generics. This is a limitation of java. Use private inner interfaces or classes that extend the intended type including the generics parameter to work around this problem. - </p> - <p> + </p><p> When passing classes to the annotation, these classes do not need to be supertypes of the field. See the example. - </p> - <p> + </p><p> <code>@Delegate</code> cannot be used on static fields or methods. - <div> + </p> + </div> </div> <div class="footer"> - <a href="index.html">Back to features</a> | <a href="val.html">Previous feature (val)</a> | <span class="disabled">Next feature</span><br /> + <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 © 2010-2013 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/GetterLazy.html b/website/features/GetterLazy.html index bc5ecb0c..c6d21f01 100644 --- a/website/features/GetterLazy.html +++ b/website/features/GetterLazy.html @@ -15,12 +15,7 @@ <div class="overview"> <h3>Overview</h3> <p> - <em>NEW IN Lombok 0.10: </em>You can let lombok generate a getter which will calculate a value once, the first time this getter is called, and cache it from then on. This can be useful - if calculating the value takes a lot of CPU, or the value takes a lot of memory. To use this feature, create a <code>private final</code> variable, - initialize it with the expression that's expensive to run, and annotate your field with <code>@Getter(lazy=true)</code>. The field will be hidden from the - rest of your code, and the expression will be evaluated no more than once, when the getter is first called. There are no magic marker values (i.e. even - if the result of your expensive calculation is <code>null</code>, the result is cached) and your expensive calculation need not be thread-safe, as lombok - takes care of locking. + <em>NEW IN Lombok 0.10: </em>You can let lombok generate a getter which will calculate a value once, the first time this getter is called, and cache it from then on. This can be useful if calculating the value takes a lot of CPU, or the value takes a lot of memory. To use this feature, create a <code>private final</code> variable, initialize it with the expression that's expensive to run, and annotate your field with <code>@Getter(lazy=true)</code>. The field will be hidden from the rest of your code, and the expression will be evaluated no more than once, when the getter is first called. There are no magic marker values (i.e. even if the result of your expensive calculation is <code>null</code>, the result is cached) and your expensive calculation need not be thread-safe, as lombok takes care of locking. </p> </div> <div class="snippets"> @@ -38,15 +33,14 @@ <div class="overview"> <h3>Small print</h3><div class="smallprint"> <p> - Lombok actually creates a few fields all prefixed with <code>$lombok$</code> to cache the value. You should not rely on the exact type, name, and structure - of these fields as future implementations may change them. To access the lazily initialized value, <em>always</em> use the generated getter. + You should never refer to the field directly, always use the getter generated by lombok, because the type of the field will be mangled into an <code>AtomicReference</code>. Do not try to directly access this <code>AtomicReference</code>; if it points to itself, the value has been calculated, and it is <code>null</code>. If the reference points to <code>null</code>, then the value has not been calculated. This behaviour may change in future versions. Therefore, <em>always</em> use the generated getter to access your field! </p><p> Other Lombok annotations such as <code>@ToString</code> always call the getter even if you use <code>doNotUseGetters=true</code>. </p> </div> </div> <div class="footer"> - <a href="index.html">Back to features</a> | <a href="GetterSetter.html">Previous feature (@Getter / @Setter)</a> | <a href="ToString.html">Next feature (@ToString)</a><br /> + <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-2013 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/GetterSetter.html b/website/features/GetterSetter.html index 03704119..7e2ff226 100644 --- a/website/features/GetterSetter.html +++ b/website/features/GetterSetter.html @@ -30,6 +30,8 @@ behaviour of a <code>@Getter</code>, <code>@Setter</code> or <code>@Data</code> annotation on a class. </p><p> To put annotations on the generated method, you can use <code>onMethod=@_({@AnnotationsHere})</code>; to put annotations on the only parameter of a generated setter method, you can use <code>onParam=@_({@AnnotationsHere})</code>. Be careful though! This is an experimental feature. For more details see the documentation on the <a href="experimental/onX.html">onX</a> feature. + </p><p> + <em>NEW in lombok v1.12.0:</em> javadoc on the field will now be copied to generated getters and setters. Normally, all text is copied, and <code>@return</code> is <em>moved</em> to the getter, whilst <code>@param</code> lines are <em>moved</em> to the setter. Moved means: Deleted from the field's javadoc. It is also possible to define unique text for each getter/setter. To do that, you create a 'section' named <code>GETTER</code> and/or <code>SETTER</code>. A section is a line in your javadoc containing 2 or more dashes, then the text 'GETTER' or 'SETTER', followed by 2 or more dashes, and nothing else on the line. If you use sections, <code>@return</code> and <code>@param</code> stripping for that section is no longer done (move the <code>@return</code> or <code>@param</code> line into the section). </p> </div> <div class="snippets"> @@ -75,7 +77,7 @@ </div> </div> <div class="footer"> - <a href="index.html">Back to features</a> | <span class="disabled">Previous feature</span> | <a href="GetterLazy.html">Next feature (@Getter(lazy=true))</a><br /> + <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-2013 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/Log.html b/website/features/Log.html index fb529426..2d4fa375 100644 --- a/website/features/Log.html +++ b/website/features/Log.html @@ -16,9 +16,9 @@ <h3>Overview</h3> <p> <em>NEW in lombok 0.10: </em>You can annotate any class with a log annotation to let lombok generate a logger field.<br /> - The logger is named <code>log</code> and field's type depends on which logger you have selected. + The logger is named <code>log</code> and the field's type depends on which logger you have selected. </p><p> - There are four choices available:<br /> + There are six choices available:<br /> <dl> <dt><code>@CommonsLog</code></dt> <dd>Creates <code><span class="keyword">private static final </span><a href="http://commons.apache.org/logging/apidocs/org/apache/commons/logging/Log.html">org.apache.commons.logging.Log</a> <span class="staticfield">log</span> = <a href="http://commons.apache.org/logging/apidocs/org/apache/commons/logging/LogFactory.html#getLog(java.lang.Class)">org.apache.commons.logging.LogFactory.getLog</a>(LogExample.<span class="keyword">class</span>);</code></dd> @@ -26,6 +26,8 @@ <dd>Creates <code><span class="keyword">private static final </span><a href="http://download.oracle.com/javase/6/docs/api/java/util/logging/Logger.html">java.util.logging.Logger</a> <span class="staticfield">log</span> = <a href="http://download.oracle.com/javase/6/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)">java.util.logging.Logger.getLogger</a>(LogExample.<span class="keyword">class</span>.getName());</code></dd> <dt><code>@Log4j</code></dt> <dd>Creates <code><span class="keyword">private static final </span><a href="http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/Logger.html">org.apache.log4j.Logger</a> <span class="staticfield">log</span> = <a href="http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/Logger.html#getLogger(java.lang.Class)">org.apache.log4j.Logger.getLogger</a>(LogExample.<span class="keyword">class</span>);</code></dd> + <dt><code>@Log4j2</code></dt> + <dd>Creates <code><span class="keyword">private static final </span><a href="http://logging.apache.org/log4j/2.0/log4j-api/apidocs/org/apache/logging/log4j/Logger.html">org.apache.logging.log4j.Logger</a> <span class="staticfield">log</span> = <a href="http://logging.apache.org/log4j/2.0/log4j-api/apidocs/org/apache/logging/log4j/LogManager.html#getLogger(java.lang.Class)">org.apache.logging.log4j.LogManager.getLogger</a>(LogExample.<span class="keyword">class</span>);</code></dd> <dt><code>@Slf4j</code></dt> <dd>Creates <code><span class="keyword">private static final </span><a href="http://www.slf4j.org/api/org/slf4j/Logger.html">org.slf4j.Logger</a> <span class="staticfield">log</span> = <a href="http://www.slf4j.org/apidocs/org/slf4j/LoggerFactory.html#getLogger(java.lang.Class)">org.slf4j.LoggerFactory.getLogger</a>(LogExample.<span class="keyword">class</span>);</code></dd> <dt><code>@XSlf4j</code></dt> @@ -58,7 +60,7 @@ </div> </div> <div class="footer"> - <a href="index.html">Back to features</a> | <a href="SneakyThrows.html">Previous feature (@SneakyThrows)</a> | <a href="val.html">Next feature (val)</a><br /> + <a href="index.html">Back to features</a> | <a href="GetterLazy.html">Previous feature (@Getter(lazy=true))</a> | <a href="Delegate.html">Next feature (@Delegate)</a><br /> <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2013 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/NonNull.html b/website/features/NonNull.html new file mode 100644 index 00000000..9faad502 --- /dev/null +++ b/website/features/NonNull.html @@ -0,0 +1,73 @@ +<!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>val</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>@NonNull</h1> + <div class="byline">or: How I learned to stop worrying and love the NullPointerException.</div> + <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. + </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 + statement inside your own method or constructor. + </p><p> + The null-check looks like <code>if (param == null) throw new NullPointerException("param");</code> and will be inserted at the very top of your method. For constructors, the null-check + will be inserted immediately following any explicit <code>this()</code> or <code>super()</code> calls. + </p><p> + If a null-check is already present at the top, no additional null-check will be generated. + </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> + Lombok's detection scheme for already existing null-checks consists of scanning for if statements that look just like lombok's own. Any 'throws' statement as + the 'then' part of the if statement, whether in braces or not, counts. The conditional of the if statement <em>must</em> look exactly like <code>PARAMNAME == null</code>. + The first statement in your method that is not such a null-check stops the process of inspecting for null-checks. + </p><p> + While <code>@Data</code> and other method-generating lombok annotations will trigger on any annotation named <code>@NonNull</code> regardless of casing or package name, + 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> + </div> + </div> + <div class="footer"> + <a href="index.html">Back to features</a> | <a href="val.html">Previous feature (val)</a> | <a href="Cleanup.html">Next feature (@Cleanup)</a><br /> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2013 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 0f04b7d9..3b3987e4 100644 --- a/website/features/SneakyThrows.html +++ b/website/features/SneakyThrows.html @@ -54,8 +54,6 @@ <div class="overview"> <h3>Small print</h3><div class="smallprint"> <p> - <code>@SneakyThrows</code> is an implementation of this feature request: <a href="http://bugs.sun.com/view_bug.do?bug_id=6534270">http://bugs.sun.com/view_bug.do?bug_id=6534270</a>. - </p><p> Because <code>@SneakyThrows</code> is an implementation detail and not part of your method signature, it is an error if you try to declare a checked exception as sneakily thrown when you don't call any methods that throw this exception. (Doing so is perfectly legal for <code>throws</code> statements to accommodate subclasses). Similarly, <code>@SneakyThrows</code> does not inherit. @@ -64,11 +62,15 @@ statement in a try/catch block with just <code>e.printStackTrace()</code> in the catch block. This is so spectacularly non-productive compared to just sneakily throwing the exception onwards, that Roel and Reinier feel more than justified in claiming that the checked exception system is far from perfect, and thus an opt-out mechanism is warranted. - </p> + </p><p> + If you put <code>@SneakyThrows</code> on a constructor, any call to a sibling or super constructor is <em>excluded</em> from the <code>@SneakyThrows</code> treatment. This is a + java restriction we cannot work around: Calls to sibling/super constructors MUST be the first statement in the constructor; they cannot be placed inside try/catch blocks. + </p><p> + <code>@SneakyThrows</code> on an empty method, or a constructor that is empty or only has a call to a sibling / super constructor results in no try/catch block and a warning. </div> </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="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-2013 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/Synchronized.html b/website/features/Synchronized.html index 4b6ef251..9ab6c87f 100644 --- a/website/features/Synchronized.html +++ b/website/features/Synchronized.html @@ -59,7 +59,7 @@ </div> </div> <div class="footer"> - <a href="index.html">Back to features</a> | <a href="Cleanup.html">Previous feature (@Cleanup)</a> | <a href="SneakyThrows.html">Next feature (@SneakyThrows)</a><br /> + <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-2013 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/ToString.html b/website/features/ToString.html index c3b389ba..585dc72b 100644 --- a/website/features/ToString.html +++ b/website/features/ToString.html @@ -68,7 +68,7 @@ </div> </div> <div class="footer"> - <a href="index.html">Back to features</a> | <a href="GetterLazy.html">Previous feature (@Getter(lazy=true))</a> | <a href="EqualsAndHashCode.html">Next feature (@EqualsAndHashCode)</a><br /> + <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-2013 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/Value.html b/website/features/Value.html index d2acfee4..6bbd6f2a 100644 --- a/website/features/experimental/Value.html +++ b/website/features/Value.html @@ -1,15 +1,15 @@ <!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" /> + <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 - @ExtensionMethod</title> + <title>@ExtensionMethod</title> </head><body><div id="pepper"> <div class="minimumHeight"></div> <div class="meat"> - <div class="header"><a href="../../index.html">Project Lombok</a></div> + <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="since"> @@ -18,27 +18,20 @@ <code>@Value</code> was introduced as experimental feature in lombok v0.11.4. </p><p> <code>@Value</code> no longer implies <code>@Wither</code> since lombok v0.11.8. - </div> - <div class="experimental"> - <h3>Experimental</h3> - <p> - Experimental because: - <ul> - <li>Various choices still have to be vetted as being the correct 'least surprise' choice: Should the class be made final by default, etc.</li> - </ul> - Current status: <em>positive</em> - Currently we feel this feature may move out of experimental status with no or minor changes soon. + </p><p> + <code>@Value</code> promoted to the main <code>lombok</code> package since lombok v0.12.0. </div> <div class="overview"> <h3>Overview</h3> <p> - <code>@Value</code> is the immutable variant of <a href="../Data.html"><code>@Data</code></a>; all fields are made <code>private</code> and <code>final</code> by default, and setters are not generated. The class itself is also made <code>final</code> by default, because immutability is not something that can be forced onto a subclass. Like <code>@Data</code>, useful <code>toString()</code>, <code>equals()</code> and <code>hashCode()</code> methods are also generated, each field gets a getter method, and a constructor that covers every + <code>@Value</code> is the immutable variant of <a href="Data.html"><code>@Data</code></a>; all fields are made <code>private</code> and <code>final</code> by default, and setters are not generated. The class itself is also made <code>final</code> by default, because immutability is not something that can be forced onto a subclass. Like <code>@Data</code>, useful <code>toString()</code>, <code>equals()</code> and <code>hashCode()</code> methods are also generated, each field gets a getter method, and a constructor that covers every argument (except <code>final</code> fields that are initialized in the field declaration) is also generated. </p><p> In practice, <code>@Value</code> is shorthand for: <code>final @ToString @EqualsAndHashCode @AllArgsConstructor @FieldDefaults(makeFinal = true, level = AccessLevel.PRIVATE) @Getter</code>. </p><p> It is possible to override the final-by-default and private-by-default behaviour using either an explicit access level on a field, or by using the <code>@NonFinal</code> or <code>@PackagePrivate</code> annotations.<br /> It is possible to override any default behaviour for any of the 'parts' that make up <code>@Value</code> by explicitly using that annotation. - </p> + </p> </div> <div class="snippets"> <div class="pre"> @@ -55,15 +48,20 @@ <div class="overview"> <h3>Small print</h3><div class="smallprint"> <p> - Look for the documentation on the 'parts' of <code>@Value</code>: <a href="../ToString.html"><code>@ToString</code></a>, <a href="../EqualsAndHashCode.html"><code>@EqualsAndHashCode</code></a>, <a href="../Constructor.html"><code>@AllArgsConstructor</code></a>, <a href="FieldDefaults.html"><code>@FieldDefaults</code></a>, and <a href="../GetterSetter.html"><code>@Getter</code></a>. + Look for the documentation on the 'parts' of <code>@Value</code>: <a href="ToString.html"><code>@ToString</code></a>, <a href="EqualsAndHashCode.html"><code>@EqualsAndHashCode</code></a>, <a href="Constructor.html"><code>@AllArgsConstructor</code></a>, <a href="experimental/FieldDefaults.html"><code>@FieldDefaults</code></a>, and <a href="GetterSetter.html"><code>@Getter</code></a>. </p><p> For classes with generics, it's useful to have a static method which serves as a constructor, because inference of generic parameters via static methods works in java6 and avoids having to use the diamond operator. While you can force this by applying an explicit <code>@AllArgsConstructor(staticConstructor="of")</code> annotation, there's also the <code>@Value(staticConstructor="of")</code> feature, which will make the generated all-arguments constructor private, and generates a public static method named <code>of</code> which is a wrapper around this private constructor. + </p><p> + <code>@Value</code> was an experimental feature from v0.11.4 to v0.11.9 (as <code>@lombok.experimental.Value</code>). It has since been moved into the core package. The old annotation is still + around (and is an alias). It will eventually be removed in a future version, though. + </p><p> + It is not possible to use <code>@FieldDefaults</code> to 'undo' the private-by-default and final-by-default aspect of fields in the annotated class. Use <code>@NonFinal</code> and <code>@PackagePrivate</code> on the fields in the class to override this behaviour. </p> </div> </div> <div class="footer"> - <a href="index.html">Back to experimental features</a> | <a href="Wither.html">Previous feature (@Wither)</a> | <a href="onX.html">Next feature (onX)</a><br /> - <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2013 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="SneakyThrows.html">Next feature (@SneakyThrows)</a><br /> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2013 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 dce77d32..3ca79de5 100644 --- a/website/features/experimental/Accessors.html +++ b/website/features/experimental/Accessors.html @@ -84,7 +84,7 @@ </div> </div> <div class="footer"> - <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="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-2013 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/Builder.html b/website/features/experimental/Builder.html new file mode 100644 index 00000000..0616afc9 --- /dev/null +++ b/website/features/experimental/Builder.html @@ -0,0 +1,134 @@ +<!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 - @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> + @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"> + <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> + <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-2013 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 da2156cd..b334cd7c 100644 --- a/website/features/experimental/Wither.html +++ b/website/features/experimental/Wither.html @@ -46,6 +46,8 @@ a 'wither' is generated for each field (even non-final fields). </p><p> To put annotations on the generated method, you can use <code>onMethod=@_({@AnnotationsHere})</code>; to put annotations on the only parameter of a generated wither method, you can use <code>onParam=@_({@AnnotationsHere})</code>. Be careful though! This is an experimental feature. For more details see the documentation on the <a href="onX.html">onX</a> feature. + </p><p> + <em>NEW in lombok v1.12.0:</em> javadoc on the field will now be copied to generated withers. Normally, all text is copied, and <code>@param</code> is <em>moved</em> to the wither, whilst <code>@return</code> lines are stripped from the wither's javadoc. Moved means: Deleted from the field's javadoc. It is also possible to define unique text for the wither's javadoc. To do that, you create a 'section' named <code>WITHER</code>. A section is a line in your javadoc containing 2 or more dashes, then the text 'WITHER', followed by 2 or more dashes, and nothing else on the line. If you use sections, <code>@return</code> and <code>@param</code> stripping / copying for that section is no longer done (move the <code>@param</code> line into the section). </p> </div> <div class="snippets"> @@ -83,7 +85,7 @@ </div> </div> <div class="footer"> - <a href="index.html">Back to experimental features</a> | <a href="FieldDefaults.html">Previous feature (@FieldDefaults)</a> | <a href="Value.html">Next feature (@Value)</a><br /> + <a href="index.html">Back to experimental features</a> | <a href="FieldDefaults.html">Previous feature (@FieldDefaults)</a> | <a href="onX.html">Next feature (onX)</a><br /> <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2013 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 24fbb541..16d58050 100644 --- a/website/features/experimental/index.html +++ b/website/features/experimental/index.html @@ -22,6 +22,8 @@ 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> @@ -30,12 +32,17 @@ <dd>New default field modifiers for the 21st century.</dd> <dt><a href="Wither.html"><code>@Wither</code></a></dt> <dd>Immutable 'setters' - methods that create a clone but with one changed field.</dd> - <dt><a href="Value.html"><code>@Value</code></a></dt> - <dd>Immutable classes made very easy.</dd> <dt><a href="onX.html"><code>onMethod= / onConstructor= / onParam</code></a></dt> <dd>Sup dawg, we heard you like annotations, so we put annotations in your annotations so you can annotate while you're annotating.</dd> </dl> </div> + <div class="index overview"> + <h3>Putting the "Ex" in "Experimental": promoted or deleted experimental features.</h3> + <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> + </dl> + </div> <div class="footer"> <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2013 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> diff --git a/website/features/experimental/onX.html b/website/features/experimental/onX.html index 99365deb..66b0164f 100644 --- a/website/features/experimental/onX.html +++ b/website/features/experimental/onX.html @@ -69,7 +69,7 @@ </div> </div> <div class="footer"> - <a href="index.html">Back to experimental features</a> | <a href="Value.html">Previous feature (@Value)</a> | <span class="disabled">Next feature</span><br /> + <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-2013 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/index.html b/website/features/index.html index 37038ddb..f9b8cdfa 100644 --- a/website/features/index.html +++ b/website/features/index.html @@ -13,10 +13,14 @@ <h1>Lombok features</h1> <div class="index overview"> <dl> + <dt><a href="val.html"><code>val</code></a></dt> + <dd>Finally! Hassle-free final local variables.</dd> + <dt><a href="NonNull.html"><code>@NonNull</code></a></dt> + <dd>or: How I learned to stop worrying and love the NullPointerException.</dd> + <dt><a href="Cleanup.html"><code>@Cleanup</code></a></dt> + <dd>Automatic resource management: Call your <code>close()</code> methods safely with no hassle.</dd> <dt><a href="GetterSetter.html"><code>@Getter</code> / <code>@Setter</code></a></dt> <dd>Never write <code>public int getFoo() {return foo;}</code> again.</dd> - <dt><a href="GetterLazy.html"><code>@Getter(lazy=true)</code></a></dt> - <dd>Laziness is a virtue!</dd> <dt><a href="ToString.html"><code>@ToString</code></a></dt> <dd>No need to start a debugger to see your fields: Just let lombok generate a <code>toString</code> for you!</dd> <dt><a href="EqualsAndHashCode.html"><code>@EqualsAndHashCode</code></a></dt> @@ -26,16 +30,16 @@ <dt><a href="Data.html"><code>@Data</code></a></dt> <dd>All together now: A shortcut for <code>@ToString</code>, <code>@EqualsAndHashCode</code>, <code>@Getter</code> on all fields, and <code>@Setter</code> on all non-final fields, and <code>@RequiredArgsConstructor</code>!</dd> - <dt><a href="Cleanup.html"><code>@Cleanup</code></a></dt> - <dd>Automatic resource management: Call your <code>close()</code> methods safely with no hassle.</dd> - <dt><a href="Synchronized.html"><code>@Synchronized</code></a></dt> - <dd><code>synchronized</code> done right: Don't expose your locks.</dd> + <dt><a href="Value.html"><code>@Value</code></a></dt> + <dd>Immutable classes made very easy.</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> + <dd><code>synchronized</code> done right: Don't expose your locks.</dd> + <dt><a href="GetterLazy.html"><code>@Getter(lazy=true)</code></a></dt> + <dd>Laziness is a virtue!</dd> <dt><a href="Log.html"><code>@Log</code></a></dt> <dd>Captain's Log, stardate 24435.7: "What was that line again?"</dd> - <dt><a href="val.html"><code>val</code></a></dt> - <dd>Finally! Hassle-free final local variables.</dd> <dt><a href="Delegate.html"><code>@Delegate</code></a></dt> <dd>Don't lose your composition.</dd> <dt><a href="experimental/index.html">experimental features</a></dt> @@ -43,6 +47,9 @@ </dl> </div> <div class="pointer"> + If you'd rather read a longer tutorial, <a href="http://jnb.ociweb.com/jnb/jnbJan2010.html">here is a great tutorial (including a walkthrough through some of the above features)</a> written by Michael Kimberlin. + </div> + <div class="pointer"> The documentation above is a lot easier to follow, but if you want to build your own transformations, or you want to add javadoc to <code>lombok.jar</code> in your IDE, you can also check out <a href="../api/index.html">the javadoc</a>. </div> diff --git a/website/features/val.html b/website/features/val.html index cec799e9..c4c8ad27 100644 --- a/website/features/val.html +++ b/website/features/val.html @@ -50,7 +50,7 @@ </div> </div> <div class="footer"> - <a href="index.html">Back to features</a> | <a href="Log.html">Previous feature (@Log)</a> | <a href="Delegate.html">Next feature (@Delegate)</a><br /> + <a href="index.html">Back to features</a> | <span class="disabled">Previous feature</span> | <a href="NonNull.html">Next feature (@NonNull)</a><br /> <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2010-2013 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> |