Date: Tue, 20 Jul 2010 07:43:02 +0200 Subject: 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. --- 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 +-- 5 files changed, 114 insertions(+), 18 deletions(-) create mode 100644 website/features/Constructor.html (limited to 'website') 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 @@ + + + + + + + + @Data +

+ +

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

+ +

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

@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 @@

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 @@

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 @@

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 @@

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 @@

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 @@

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

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

-- cgit