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.
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
parent: f17ba28daa683a4ef9f7743a1ccdde8f8632cb94 (diff)
download: lombok-aaf8547d91a540334419f2faebb897b327d535d8.tar.gz
lombok-aaf8547d91a540334419f2faebb897b327d535d8.tar.bz2
lombok-aaf8547d91a540334419f2faebb897b327d535d8.zip
8 files changed, 164 insertions, 20 deletions
diff --git a/buildScripts/website.ant.xml b/buildScripts/website.ant.xml
index b33eebf2..73700a82 100644
--- a/buildScripts/website.ant.xml
+++ b/buildScripts/website.ant.xml
@@ -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">
@@ -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>
diff --git a/usage_examples/ConstructorExample_post.jpage b/usage_examples/ConstructorExample_post.jpage
new file mode 100644
index 00000000..5f4aa987
--- /dev/null
+++ b/usage_examples/ConstructorExample_post.jpage
@@ -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() {
+		}
+	}
+}
diff --git a/usage_examples/ConstructorExample_pre.jpage b/usage_examples/ConstructorExample_pre.jpage
new file mode 100644
index 00000000..ac0d3c28
--- /dev/null
+++ b/usage_examples/ConstructorExample_pre.jpage
@@ -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;
+	}
+}
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&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>
diff --git a/website/features/Data.html b/website/features/Data.html
index 8e33be8f..45b28403 100644
--- a/website/features/Data.html
+++ b/website/features/Data.html
@@ -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>
@@ -62,8 +61,8 @@
 		<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
@@ -76,8 +75,8 @@
 			</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>
diff --git a/website/features/EqualsAndHashCode.html b/website/features/EqualsAndHashCode.html
index d2575244..15d15050 100644
--- a/website/features/EqualsAndHashCode.html
+++ b/website/features/EqualsAndHashCode.html
@@ -74,7 +74,7 @@
 			</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>
diff --git a/website/features/GetterSetter.html b/website/features/GetterSetter.html
index 5b70aaf4..0e9481a4 100644
--- a/website/features/GetterSetter.html
+++ b/website/features/GetterSetter.html
@@ -22,6 +22,12 @@
 			</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">
@@ -63,7 +69,7 @@
 		</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>
diff --git a/website/features/index.html b/website/features/index.html
index 9157f503..869bbe89 100644
--- a/website/features/index.html
+++ b/website/features/index.html
@@ -19,10 +19,11 @@
 				<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>
@@ -50,7 +51,7 @@
 				your source files for source-level tools such as javadoc and GWT. More information about how to run delombok, including instructions for build tools
 				can be found at the <a href="delombok.html">delombok page</a>.</div>
 		<div class="footer">
-			<a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright &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>
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
parent	f17ba28daa683a4ef9f7743a1ccdde8f8632cb94 (diff)
download	lombok-aaf8547d91a540334419f2faebb897b327d535d8.tar.gz lombok-aaf8547d91a540334419f2faebb897b327d535d8.tar.bz2 lombok-aaf8547d91a540334419f2faebb897b327d535d8.zip