Date: Tue, 28 Jul 2009 17:38:26 +0200 Subject: Added website feature documentation for @ToString and @EqualsAndHashCode, and modified the docs for @Data to refer to the docs of these new annotations. The build script for the website has been updated to clean out the website build dir first, so files that used to exist but have now been tossed are no longer there. There's also a special website-no-videos target which builds a website deployable without the videos. This makes the upload a lot faster if the videos haven't changed. --- website/features/Data.html | 44 ++++++++--------- website/features/EqualsAndHashCode.html | 88 +++++++++++++++++++++++++++++++++ website/features/GetterSetter.html | 2 +- website/features/ToString.html | 78 +++++++++++++++++++++++++++++ website/features/index.html | 9 +++- 5 files changed, 196 insertions(+), 25 deletions(-) create mode 100644 website/features/EqualsAndHashCode.html create mode 100644 website/features/ToString.html (limited to 'website') diff --git a/website/features/Data.html b/website/features/Data.html index b6f0cc85..ee81405a 100644 --- a/website/features/Data.html +++ b/website/features/Data.html @@ -11,31 +11,34 @@

@Data

'struct' for java: Automatically generate toString, hashCode, equals, a constructor, and getters and setters - from just the fields in your class.

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!

Overview

- Any class definition may be annotated with @Data to let lombok generate all the boilerplate that is associated with simple POJOs - (Plain Old Java Objects) and beans: getters for all fields, setters for all non-final fields, a useful toString, and implementations - of hashCode and equals which consider any two objects of this type with the same values for each field as equal. A - constructor is also generated containing 1 parameter for each final field, in the order the fields are defined. This constructor simply assigns - each parameter to the appropriate field. -

- To override the access level of any getter/setter for any field, annotate the field with a @Setter or @Getter annotation - with the appropriate AccessLevel value. See the example below. For more information on how the getters/setters are generated, - see the documentation for @Getter and @Setter. + @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 + initialized all final fields. +

+ @Data is like having implicit @ToString and @EqualsAndHashCode annotations on the class. + However, the parameters of @ToString and @EqualsAndHashCode (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 + @Getter annotation.

All fields marked as transient will not be considered for hashCode and equals. All static fields will be skipped entirely (not considered for any of the generated methods, and no setter/getter will be made for them). - The generated getter/setter method will be public unless you explicitly specify an AccessLevel, as shown in the example below. - Legal access levels are PUBLIC, PROTECTED, PACKAGE, and PRIVATE.

- If any method that would normally be generated exists in name that method will not be generated, and no warning or error is emitted. For example, - if you already have a method with signature void hashCode(int a, int b, int c), no int hashCode() method will be generated, - even though technically int hashCode() is an entirely different method. The same rule applies to the constructor, toString, - hashCode, and all getters and setters. + If the class already contains a method with the same name as any method that would normally be generated, that method is not generated, and no warning or + error is emitted. For example, if you already have a method with signature void hashCode(int a, int b, int c), no int hashCode() + method will be generated, even though technically int hashCode() is an entirely different method. The same rule applies to the constructor, + toString, equals, and all getters and setters.

@Data can handle generics parameters for fields just fine. In order to reduce the boilerplate when constructing objects for classes with generics, you can use the staticConstructor parameter to generate a private constructor, as well as a static method that returns a new @@ -61,9 +64,6 @@ Arrays are 'deep' compared/printed/hashCoded, which means that arrays that contain themselves will result in StackOverflowErrors. However, this behaviour is no different from e.g. ArrayList.

- You may safely presume that the hashCode implementation used will not change between versions of lombok, however this guarantee is not set in stone; - if there's a significant performance improvement to be gained from using an alternate hash algorithm, that will be substituted in a future version. -

For a general idea of how lombok generated the equals, hashCode, and toString methods, check the example after.

For the purposes of equality, 2 NaN (not a number) values for floats and doubles are considered equal, eventhough 'NaN == NaN' would @@ -73,7 +73,7 @@

diff --git a/website/features/EqualsAndHashCode.html b/website/features/EqualsAndHashCode.html new file mode 100644 index 00000000..3e19814c --- /dev/null +++ b/website/features/EqualsAndHashCode.html @@ -0,0 +1,88 @@ + + + + + + + + @Data +

+ +

@EqualsAndHashCode

Equality made easy: Generates hashCode and equals implementations from the fields of your object.

Overview

+ Any class definition may be annotated with @EqualsAndHashCode to let lombok generate implementations of the + equals(Object other) and hashCode() methods. By default, it'll use all non-static, non-transient + fields, but you can exclude more fields by naming them in the optional exclude parameter to the annotation. +

+ By setting callSuper to true, you can include the equals and hashCode methods of your superclass in the generated methods. + For hashCode, the result of super.hashCode() is included in the hash algorithm, and for equals, the generated method will return + false if the super implementation thinks it is not equal to the passed in object. Be aware that not all equals implementations handle this situation properly. + However, lombok-generated equals implementations do handle this situation properly, so you can safely call your superclass equals if it, too, + has a lombok-generated equals method.
+

+ Setting callSuper to true when you don't extend anything (you extend java.lang.Object) is a compile-time error, because it would turn + the generated equals() and hashCode() implementations into having the same behaviour as simply inheriting these methods from java.lang.Object: + only the same object will be equal to each other and will have the same hashCode. Obviously, inheriting java.lang.Object is the right strategy if you want this behaviour. + Not setting callSuper to true when you extend another class generates a warning, because unless the superclass has no (equality-important) fields, lombok + cannot generate an implementation for you that takes into account the fields declared by your superclasses. You'll need to write your own implementations, or rely on the + callSuper chaining facility. +

With Lombok

@HTML_PRE@

Vanilla Java

@HTML_POST@

Small print

+ Arrays are 'deep' compared/hashCoded, which means that arrays that contain themselves will result in StackOverflowErrors. However, + this behaviour is no different from e.g. ArrayList. +

+ You may safely presume that the hashCode implementation used will not change between versions of lombok, however this guarantee is not set in stone; + if there's a significant performance improvement to be gained from using an alternate hash algorithm, that will be substituted in a future version. +

+ For the purposes of equality, 2 NaN (not a number) values for floats and doubles are considered equal, eventhough 'NaN == NaN' would + return false. This is analogous to java.lang.Double's equals method, and is in fact required to ensure that comparing an object + to an exact copy of itself returns true for equality. +

+ If there is any method named either hashCode or equals, regardless of parameters or return type, + that method will not be generated, and a warning is emitted instead. hashCode and equals need to be in sync with + each other, which lombok cannot guarantee if it is only generating one of the two methods, hence you always get a warning if one or both + of the methods already exist. +

+ Attempting to exclude fields that don't exist or would have been excluded anyway (because they are static) results in warnings on the named fields. + You therefore don't have to worry about typos. +

+ +

+ + + diff --git a/website/features/GetterSetter.html b/website/features/GetterSetter.html index b9844aad..8b42146f 100644 --- a/website/features/GetterSetter.html +++ b/website/features/GetterSetter.html @@ -52,7 +52,7 @@

diff --git a/website/features/ToString.html b/website/features/ToString.html new file mode 100644 index 00000000..e970d88c --- /dev/null +++ b/website/features/ToString.html @@ -0,0 +1,78 @@ + + + + + + + + @Data +

+ +

@ToString

No need to start a debugger to see your fields: Just let lombok generate a toString for you!

Overview

+ Any class definition may be annotated with @ToString to let lombok generate an implementation of the + toString() method. By default, it'll print your class name, along with each field, in order, separated by commas. +

+ By setting the includeFieldNames parameter to true you can add some clarity (but also quite some length) to + the output of the toString() method. +

+ All non-static fields will be printed. If you want to skip some fields, you can name them in the exclude parameter; each named + field will not be printed at all. +

+ By setting callSuper to true, you can include the output of the superclass implementation of toString to the + output. Be aware that the default implementation of toString() in java.lang.Object is pretty much meaningless, so you + probably don't want to do this unless you are extending another class. +

With Lombok

@HTML_PRE@

Vanilla Java

@HTML_POST@

Small print

+ If there is any method named toString regardless of parameters or return type, no method will be generated, and instead + a warning is emitted explaining that your @ToString annotation is doing nothing. +

+ Arrays are printed via Arrays.deepToString, which means that arrays that contain themselves will result in StackOverflowErrors. However, + this behaviour is no different from e.g. ArrayList. +

+ We don't promise to keep the output of the generated toString() methods the same between lombok versions. You should never design your API so that + other code is forced to parse your toString() output anyway! +

+ +

+ + + diff --git a/website/features/index.html b/website/features/index.html index 921e1d94..5a5387b9 100644 --- a/website/features/index.html +++ b/website/features/index.html @@ -15,9 +15,14 @@

@Getter / @Setter: Never write public int getFoo() {return foo;} again.
@ToString: 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.
@Data: 'struct' for java: Automatically generate toString, hashCode, equals, a constructor, and getters and setters - from just the fields in your class.; 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!
@Cleanup: Automatic resource management: Call your close() methods safely with no hassle.
@Synchronized