diff options
| author | Reinier Zwitserloot <reinier@zwitserloot.com> | 2010-07-20 07:43:02 +0200 |
|---|---|---|
| committer | Reinier Zwitserloot <reinier@zwitserloot.com> | 2010-07-20 07:43:02 +0200 |
| commit | aaf8547d91a540334419f2faebb897b327d535d8 (patch) | |
| tree | 77f31019f0c87e823c5ed6a2569170b8bce7c7f6 /website/features/Constructor.html | |
| parent | f17ba28daa683a4ef9f7743a1ccdde8f8632cb94 (diff) | |
| download | lombok-aaf8547d91a540334419f2faebb897b327d535d8.tar.gz lombok-aaf8547d91a540334419f2faebb897b327d535d8.tar.bz2 lombok-aaf8547d91a540334419f2faebb897b327d535d8.zip | |
Added documentation for @RequiredArgsConstructor, @NoArgsConstructor, @AllArgsConstructor, and also how these generate @ConstructorProperties annotations.
Also updated @Getter and @Setter's documentation to explain their new class-level feature, and updated @Data's description to highlight how @Data is now truly nothing more than the combination of @RequiredArgsConstructor, @EqualsAndHashCode, @ToString, @Getter, and @Setter.
Diffstat (limited to 'website/features/Constructor.html')
| -rw-r--r-- | website/features/Constructor.html | 90 |
1 files changed, 90 insertions, 0 deletions
diff --git a/website/features/Constructor.html b/website/features/Constructor.html new file mode 100644 index 00000000..f8a6a200 --- /dev/null +++ b/website/features/Constructor.html @@ -0,0 +1,90 @@ +<!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>@Data</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>@NoArgsConstructor, @RequiredArgsConstructor, @AllArgsConstructor</h1> + <div class="byline">Constructors made to order: Generates constructors that take no arguments, one argument per final / non-null field, or one argument for every field.</div> + <div class="overview"> + <h3>Overview</h3> + <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 + 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> + <code>@RequiredArgsConstructor</code> generates a constructor with 1 parameter for each field that requires special handling. All <code>final</code> fields get a parameter, + as well as any fields that are marked as <code>@NonNull</code> that aren't initialized where they are declared. For those fields marked with <code>@NonNull</code>, an explicit + null check is also generated. The constructor will throw a <code>NullPointerException</code> if any of the parameters intended for the fields marked with <code>@NonNull</code> + contain <code>null</code>. The order of the parameters match the order in which the fields appear in your class. + </p><p> + <code>@AllArgsConstructor</code> generates a constructor with 1 parameter for each field in your class. Fields marked with <code>@NonNull</code> result in null checks on + those parameters. + </p><p> + Each of these annotations allows an alternate form, where the generated constructor is always private, and an additional static factory method that wraps around the + private constructor is generated. This mode is enabled by supplying the <code>staticName</code> value for the annotation, like so: <code>@RequiredArgsConstructor(staticName = "of")</code>. + Such a static factory method will infer generics, unlike a normal constructor. This means your API users get write <code>MapEntry.of("foo", 5)</code> instead of the much longer + <code>new MapEntry<String, Integer>("foo", 5)</code>. + </p><p> + Static fields are skipped by these annotations. Also, a <code>@java.beans.ConstructorProperties</code> annotation is added for all constructors with at least 1 argument, + which allows bean editor tools to call the generated constructors. <code>@ConstructorProperties</code> is now in Java 1.6, which means that if your code is intended for + compilation on Java 1.5, a compiler error will occur. <em>Running</em> on a JVM 1.5 should be no problem (the annotation will be ignored). To suppress the generation of + the <code>@ConstructorProperties</code> annotation, add a parameter to your annotation: <code>@AllArgsConstructor(suppressConstructorProperties=true)</code>. However, + as java 1.5, which has already been end-of-lifed, fades into obscurity, this parameter will eventually be removed. It has also been marked deprecated for this reason. + </p><p> + Unlike most other lombok annotations, the existence of an explicit constructor does not stop these annotations from generating their own constructor. This means you can write + your own specialized constructor, and let lombok generate the boilerplate ones as well. If a conflict arises (one of your constructors ends up with the same + signature as one that lombok generates), a compiler error will occur. + </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> + Even if a field is explicitly initialized with <code>null</code>, lombok will consider the requirement to avoid null as fulfilled, and will <em>NOT</em> consider + the field as a 'required' argument. The assumption is that if you explicitly assign <code>null</code> to a field that you've also marked as <code>@NonNull</code> + signals you must know what you're doing. + </p><p> + The <code>@java.beans.ConstructorProperties</code> annotation is never generated for a constructor with no arguments. This also explains why <code>@NoArgsConstructor</code> + lacks the <code>suppressConstructorProperties</code> annotation method. The <code>@ConstructorProperties</code> annotation is also omitted for private constructors. + </p> + </div> + </div> + <div class="footer"> + <a href="index.html">Back to features</a> | <a href="EqualsAndHashCode.html">Previous feature (@EqualsAndHashCode)</a> | <a href="Data.html">Next feature (@Data)</a><br /> + <a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2010 Reinier Zwitserloot and Roel Spilker, 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> |