Skip to content

Commit

Permalink
Added documentation for @requiredargsconstructor, @NoArgsConstructor, @…
Browse files Browse the repository at this point in the history 
…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.
  • Loading branch information
@rzwitserloot
rzwitserloot committed Jul 20, 2010
1 parent f17ba28 commit aaf8547
Show file tree
Hide file tree
Showing 8 changed files with 164 additions and 20 deletions.
6 changes: 4 additions & 2 deletions buildScripts/website.ant.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,9 @@ such as converting the changelog into HTML, and creating javadoc.
<antcall target="-integrateSnippet">
<param name="transformationName" value="SneakyThrows" />
</antcall>
<antcall target="-integrateSnippet">
<param name="transformationName" value="Constructor" />
</antcall>
</target>

<target name="-website-dist">
Expand Down Expand Up @@ -283,8 +286,7 @@ such as converting the changelog into HTML, and creating javadoc.
write your own plugins, the other packages are what you're looking for.</body></html>
]]></echo>
<javadoc sourcepath="src/core" defaultexcludes="yes" destdir="build/api" windowtitle="Lombok" Overview="${javadoc.overview.html}">
<classpath refid="deps.path" />
<classpath refid="libs.path" />
<classpath refid="build.path" />
<link href="http://java.sun.com/javase/6/docs/api/" offline="true" packagelistLoc="./deps/javadoc/java6"/>
<header><![CDATA[<a href='http://projectlombok.org/'>Lombok</a> - ]]>v${lombok.version}</header>
<bottom><![CDATA[<i>Copyright &#169; 2009 Reinier Zwitserloot and Roel Spilker, licensed under the <a href='http://www.opensource.org/licenses/mit-license.php'>MIT licence</a>.]]></bottom>
Expand Down
30 changes: 30 additions & 0 deletions usage_examples/ConstructorExample_post.jpage
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
@RequiredArgsConstructor(staticName = "of")
@AllArgsConstructor(access = AccessLevel.PROTECTED)
public class ConstructorExample<T> {
private int x, y;
@NonNull private T description;

private ConstructorExample(T description) {
if (description == null) throw new NullPointerException("description");
this.description = description;
}

public static <T> ConstructorExample<T> of(T description) {
return new ConstructorExample<T>(description);
}

@java.beans.ConstructorProperties({"x", "y", "description"})
protected ConstructorExample(int x, int y, T description) {
if (description == null) throw new NullPointerException("description");
this.x = x;
this.y = y;
this.description = description;
}

public static class NoArgsExample {
@NonNull private String field;

public NoArgsExample() {
}
}
}
16 changes: 16 additions & 0 deletions usage_examples/ConstructorExample_pre.jpage
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
import lombok.AccessLevel;
import lombok.RequiredArgsConstructor;
import lombok.AllArgsConstructor;
import lombok.NonNull;

@RequiredArgsConstructor(staticName = "of")
@AllArgsConstructor(access = AccessLevel.PROTECTED)
public class ConstructorExample<T> {
private int x, y;
@NonNull private T description;

@NoArgsConstructor
public static class NoArgsExample {
@NonNull private String field;
}
}
90 changes: 90 additions & 0 deletions website/features/Constructor.html
View file
Original file line number Diff line number Diff line change
@@ -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&lt;String, Integer&gt;("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 &copy; 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>
25 changes: 12 additions & 13 deletions website/features/Data.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,25 +12,24 @@
<div class="header"><a href="../index.html">Project Lombok</a></div>
<h1>@Data</h1>
<div class="byline">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. You even
get a free constructor to initialize your final fields!</div>
<code>@Getter</code> on all fields, <code>@Setter</code> on all non-final fields, and <code>@RequiredArgsConstructor</code>!</div>
<div class="overview">
<h3>Overview</h3>
<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> and <a href="GetterSetter.html"><code>@Getter</code> / <code>@Setter</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. In addition, <code>@Data</code> generates a constructor that
<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> or <code>@NotNull</code>,
in order to ensure the field is never null.
</p><p>
<code>@Data</code> is like having implicit <code>@ToString</code> and <code>@EqualsAndHashCode</code> annotations on the class.
However, the parameters of <code>@ToString</code> and <code>@EqualsAndHashCode</code> (such as <code>callSuper</code>, <code>includeFieldNames</code> and
<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.
</p><p>
All generated getters and setters will be <code>public</code>. To override the access level, annotate the field with an explicit <code>@Setter</code> and/or
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>
Expand Down Expand Up @@ -62,8 +61,8 @@ <h3>Vanilla Java</h3>
<div style="clear: left;"></div>
<div class="overview">
<h3>Small print</h3><div class="smallprint">
<p>See the small print of <a href="ToString.html"><code>@ToString</code></a>, <a href="EqualsAndHashCode.html"><code>@EqualsAndHashCode</code></a> and
<a href="GetterSetter.html"><code>@Getter / @Setter</code></a>.
<p>See the small print of <a href="ToString.html"><code>@ToString</code></a>, <a href="EqualsAndHashCode.html"><code>@EqualsAndHashCode</code></a>,
<a href="GetterSetter.html"><code>@Getter / @Setter</code></a> and <a href="Constructor.html">@RequiredArgsConstructor</a>.
</p><p>
Any annotations named <code>@NonNull</code> (case insensitive) on a field are interpreted as: This field must not ever hold
<em>null</em>. Therefore, these annotations result in an explicit null check in the generated constructor for the provided field. Also, these
Expand All @@ -76,8 +75,8 @@ <h3>Small print</h3><div class="smallprint">
</div>
</div>
<div class="footer">
<a href="index.html">Back to features</a> | <a href="EqualsAndHashCode.html">Previous feature (@EqualsAndHashCode)</a> | <a href="Cleanup.html">Next feature (@Cleanup)</a><br />
<a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright &copy; 2009 Reinier Zwitserloot and Roel Spilker, 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="Constructor.html">Previous feature (@<em>X</em>Constructor)</a> | <a href="Cleanup.html">Next feature (@Cleanup)</a><br />
<a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright &copy; 2009-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>
Expand Down
2 changes: 1 addition & 1 deletion website/features/EqualsAndHashCode.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ <h3>Small print</h3><div class="smallprint">
</div>
</div>
<div class="footer">
<a href="index.html">Back to features</a> | <a href="ToString.html">Previous feature (@ToString)</a> | <a href="Data.html">Next feature (@Data)</a><br />
<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 &copy; 2009 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>
Expand Down
8 changes: 7 additions & 1 deletion website/features/GetterSetter.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,12 @@ <h3>Overview</h3>
</p><p>
The generated getter/setter method will be <code>public</code> unless you explicitly specify an <code>AccessLevel</code>, as shown in the example above.
Legal access levels are <code>PUBLIC</code>, <code>PROTECTED</code>, <code>PACKAGE</code>, and <code>PRIVATE</code>.
</p><p>
You can also put a <code>@Getter</code> and/or <code>@Setter</code> annotation on a class. In that case, it's as if you annotate all the non-static fields in that
class with the annotation.
</p><p>
You can always manually disable getter/setter generation for any field by using the special <code>AccessLevel.NONE</code> access level. This lets you override the
behaviour of a <code>@Getter</code>, <code>@Setter</code> or <code>@Data</code> annotation on a class.
</p>
</div>
<div class="snippets">
Expand Down Expand Up @@ -63,7 +69,7 @@ <h3>Small print</h3><div class="smallprint">
</div>
<div class="footer">
<a href="index.html">Back to features</a> | <span class="disabled">Previous feature</span> | <a href="ToString.html">Next feature (@ToString)</a><br />
<a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright &copy; 2009 Reinier Zwitserloot and Roel Spilker, 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 &copy; 2009-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>
Expand Down
7 changes: 4 additions & 3 deletions website/features/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,11 @@ <h1>Lombok features</h1>
<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>
<dd>Equality made easy: Generates <code>hashCode</code> and <code>equals</code> implementations from the fields of your object.</dd>
<dt><a href="Constructor.html"><code>@NoArgsConstructor</code>, <code>@RequiredArgsConstructor</code> and <code>@AllArgsConstructor</code></a></dt>
<dd>Constructors made to order: Generates constructors that take no arguments, one argument per final / non-null field, or one argument for every field.</dd>
<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. You even
get a free constructor to initialize your final fields!</dd>
<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>
Expand Down Expand Up @@ -50,7 +51,7 @@ <h1>Running delombok</h1>
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 &copy; 2009 Reinier Zwitserloot and Roel Spilker, 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 &copy; 2009-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>
Expand Down

0 comments on commit aaf8547

Please sign in to comment.