From aaf8547d91a540334419f2faebb897b327d535d8 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Tue, 20 Jul 2010 07:43:02 +0200 Subject: [PATCH] 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. --- buildScripts/website.ant.xml | 6 +- usage_examples/ConstructorExample_post.jpage | 30 +++++++ usage_examples/ConstructorExample_pre.jpage | 16 ++++ website/features/Constructor.html | 90 ++++++++++++++++++++ website/features/Data.html | 25 +++--- website/features/EqualsAndHashCode.html | 2 +- website/features/GetterSetter.html | 8 +- website/features/index.html | 7 +- 8 files changed, 164 insertions(+), 20 deletions(-) create mode 100644 usage_examples/ConstructorExample_post.jpage create mode 100644 usage_examples/ConstructorExample_pre.jpage create mode 100644 website/features/Constructor.html diff --git a/buildScripts/website.ant.xml b/buildScripts/website.ant.xml index b33eebf22e..73700a82c0 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. + + + @@ -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. ]]> - - +
Lombok - ]]>v${lombok.version}
Copyright © 2009 Reinier Zwitserloot and Roel Spilker, licensed under the MIT licence.]]> diff --git a/usage_examples/ConstructorExample_post.jpage b/usage_examples/ConstructorExample_post.jpage new file mode 100644 index 0000000000..5f4aa98791 --- /dev/null +++ b/usage_examples/ConstructorExample_post.jpage @@ -0,0 +1,30 @@ +@RequiredArgsConstructor(staticName = "of") +@AllArgsConstructor(access = AccessLevel.PROTECTED) +public class ConstructorExample { + private int x, y; + @NonNull private T description; + + private ConstructorExample(T description) { + if (description == null) throw new NullPointerException("description"); + this.description = description; + } + + public static ConstructorExample of(T description) { + return new ConstructorExample(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 0000000000..ac0d3c28f9 --- /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 { + 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 0000000000..f8a6a2003b --- /dev/null +++ b/website/features/Constructor.html @@ -0,0 +1,90 @@ + + + + + + + + @Data +
+
+
+
Project Lombok
+

@NoArgsConstructor, @RequiredArgsConstructor, @AllArgsConstructor

+
Constructors made to order: Generates constructors that take no arguments, one argument per final / non-null field, or one argument for every field.
+
+

Overview

+

+ This set of 3 annotations generate a constructor that will accept 1 parameter for certain fields, and simply assigns this parameter to the field. +

+ @NoArgsConstructor 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 @NonNull fields, no 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 @Data or one of the other constructor generating annotations. +

+ @RequiredArgsConstructor generates a constructor with 1 parameter for each field that requires special handling. All final fields get a parameter, + as well as any fields that are marked as @NonNull that aren't initialized where they are declared. For those fields marked with @NonNull, an explicit + null check is also generated. The constructor will throw a NullPointerException if any of the parameters intended for the fields marked with @NonNull + contain null. The order of the parameters match the order in which the fields appear in your class. +

+ @AllArgsConstructor generates a constructor with 1 parameter for each field in your class. Fields marked with @NonNull result in null checks on + those parameters. +

+ 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 staticName value for the annotation, like so: @RequiredArgsConstructor(staticName = "of"). + Such a static factory method will infer generics, unlike a normal constructor. This means your API users get write MapEntry.of("foo", 5) instead of the much longer + new MapEntry<String, Integer>("foo", 5). +

+ Static fields are skipped by these annotations. Also, a @java.beans.ConstructorProperties annotation is added for all constructors with at least 1 argument, + which allows bean editor tools to call the generated constructors. @ConstructorProperties 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. Running on a JVM 1.5 should be no problem (the annotation will be ignored). To suppress the generation of + the @ConstructorProperties annotation, add a parameter to your annotation: @AllArgsConstructor(suppressConstructorProperties=true). 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. +

+ 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. +

+
+
+
+

With Lombok

+
@HTML_PRE@
+
+
+
+

Vanilla Java

+
@HTML_POST@
+
+
+
+
+

Small print

+

+ Even if a field is explicitly initialized with null, lombok will consider the requirement to avoid null as fulfilled, and will NOT consider + the field as a 'required' argument. The assumption is that if you explicitly assign null to a field that you've also marked as @NonNull + signals you must know what you're doing. +

+ The @java.beans.ConstructorProperties annotation is never generated for a constructor with no arguments. This also explains why @NoArgsConstructor + lacks the suppressConstructorProperties annotation method. The @ConstructorProperties annotation is also omitted for private constructors. +

+
+
+
+ Back to features | Previous feature (@EqualsAndHashCode) | Next feature (@Data)
+ credits | Copyright © 2010 Reinier Zwitserloot and Roel Spilker, licensed under the MIT license. +
+
+
+
+ + + diff --git a/website/features/Data.html b/website/features/Data.html index 8e33be8f4d..45b28403b4 100644 --- a/website/features/Data.html +++ b/website/features/Data.html @@ -12,25 +12,24 @@
Project Lombok

@Data

All together now: A shortcut for @ToString, @EqualsAndHashCode, - @Getter on all fields, and @Setter on all non-final fields. You even - get a free constructor to initialize your final fields!
+ @Getter on all fields, @Setter on all non-final fields, and @RequiredArgsConstructor!

Overview

@Data is a convenient shortcut annotation that bundles the features of @ToString, - @EqualsAndHashCode and @Getter / @Setter - together: In other words, @Data generates all 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 toString, equals - and hashCode implementations that involve the fields of the class. In addition, @Data generates a constructor that + @EqualsAndHashCode, @Getter / @Setter + and @RequiredArgsConstructor together: In other words, @Data generates all 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 toString, equals and hashCode 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 @NonNull or @NotNull, in order to ensure the field is never null.

- @Data is like having implicit @ToString and @EqualsAndHashCode annotations on the class. - However, the parameters of @ToString and @EqualsAndHashCode (such as callSuper, includeFieldNames and + @Data is like having implicit @Getter, @Setter, @ToString, @EqualsAndHashCode and @RequiredArgsConstructor + annotations on the class. However, the parameters of these annotations (such as callSuper, includeFieldNames and exclude) cannot be set with @Data. If you need to set non-default values for any of these parameters, just add those annotations explicitly; @Data is smart enough to defer to those annotations.

- All generated getters and setters will be public. To override the access level, annotate the field with an explicit @Setter and/or + All generated getters and setters will be public. To override the access level, annotate the field or class with an explicit @Setter and/or @Getter annotation. You can also use this annotation (by combining it with AccessLevel.NONE) to suppress generating a getter and/or setter altogether.

@@ -62,8 +61,8 @@

Vanilla Java

Small print

-

See the small print of @ToString, @EqualsAndHashCode and - @Getter / @Setter. +

See the small print of @ToString, @EqualsAndHashCode, + @Getter / @Setter and @RequiredArgsConstructor.

Any annotations named @NonNull (case insensitive) on a field are interpreted as: This field must not ever hold null. Therefore, these annotations result in an explicit null check in the generated constructor for the provided field. Also, these @@ -76,8 +75,8 @@

Small print

- Back to features | Previous feature (@EqualsAndHashCode) | Next feature (@Cleanup)
- credits | Copyright © 2009 Reinier Zwitserloot and Roel Spilker, licensed under the MIT license. + Back to features | Previous feature (@XConstructor) | Next feature (@Cleanup)
+ credits | Copyright © 2009-2010 Reinier Zwitserloot and Roel Spilker, licensed under the MIT license.
diff --git a/website/features/EqualsAndHashCode.html b/website/features/EqualsAndHashCode.html index d2575244a9..15d150502a 100644 --- a/website/features/EqualsAndHashCode.html +++ b/website/features/EqualsAndHashCode.html @@ -74,7 +74,7 @@

Small print

- Back to features | Previous feature (@ToString) | Next feature (@Data)
+ Back to features | Previous feature (@ToString) | Next feature (@XConstructor)
credits | Copyright © 2009 Reinier Zwitserloot and Roel Spilker, licensed under the MIT license.
diff --git a/website/features/GetterSetter.html b/website/features/GetterSetter.html index 5b70aaf4e0..0e9481a494 100644 --- a/website/features/GetterSetter.html +++ b/website/features/GetterSetter.html @@ -22,6 +22,12 @@

Overview

The generated getter/setter method will be public unless you explicitly specify an AccessLevel, as shown in the example above. Legal access levels are PUBLIC, PROTECTED, PACKAGE, and PRIVATE. +

+ You can also put a @Getter and/or @Setter annotation on a class. In that case, it's as if you annotate all the non-static fields in that + class with the annotation. +

+ You can always manually disable getter/setter generation for any field by using the special AccessLevel.NONE access level. This lets you override the + behaviour of a @Getter, @Setter or @Data annotation on a class.

@@ -63,7 +69,7 @@

Small print

Back to features | Previous feature | Next feature (@ToString)
- credits | Copyright © 2009 Reinier Zwitserloot and Roel Spilker, licensed under the MIT license. + credits | Copyright © 2009-2010 Reinier Zwitserloot and Roel Spilker, licensed under the MIT license.
diff --git a/website/features/index.html b/website/features/index.html index 9157f50319..869bbe895f 100644 --- a/website/features/index.html +++ b/website/features/index.html @@ -19,10 +19,11 @@

Lombok features

No need to start a debugger to see your fields: Just let lombok generate a toString for you!
@EqualsAndHashCode
Equality made easy: Generates hashCode and equals implementations from the fields of your object.
+
@NoArgsConstructor, @RequiredArgsConstructor and @AllArgsConstructor
+
Constructors made to order: Generates constructors that take no arguments, one argument per final / non-null field, or one argument for every field.
@Data
All together now: A shortcut for @ToString, @EqualsAndHashCode, - @Getter on all fields, and @Setter on all non-final fields. You even - get a free constructor to initialize your final fields!
+ @Getter on all fields, and @Setter on all non-final fields, and @RequiredArgsConstructor!
@Cleanup
Automatic resource management: Call your close() methods safely with no hassle.
@Synchronized
@@ -50,7 +51,7 @@

Running delombok

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 delombok page.
- credits | Copyright © 2009 Reinier Zwitserloot and Roel Spilker, licensed under the MIT license. + credits | Copyright © 2009-2010 Reinier Zwitserloot and Roel Spilker, licensed under the MIT license.