From 4fb9c6f7f82d020a9ebcae9816e911ecd4c047a4 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Tue, 15 May 2018 01:07:03 +0200 Subject: [documentation] documenting the new-style include/exclude of ToString and EqualsAndHashCode --- doc/changelog.markdown | 5 +++-- website/templates/features/EqualsAndHashCode.html | 10 ++++++---- website/templates/features/ToString.html | 14 ++++++++++---- website/usageExamples/EqualsAndHashCodeExample_pre.jpage | 6 +++--- website/usageExamples/ToStringExample_pre.jpage | 4 ++-- 5 files changed, 24 insertions(+), 15 deletions(-) diff --git a/doc/changelog.markdown b/doc/changelog.markdown index 55d83ace..d6e8af33 100644 --- a/doc/changelog.markdown +++ b/doc/changelog.markdown @@ -3,9 +3,10 @@ Lombok Changelog ### v1.16.21 "Edgy Guinea Pig" * v1.16.20 is the latest stable release of Project Lombok. -* PLATFORM: lombok now counts as an _incremental annotation processor_ for gradle. Should speed up your gradle builds considerably! [Issue #1580](https://github.com/rzwitserloot/lombok/issues/1580) +* FEATURE: Methods can now be marked for inclusion in `toString`, `equals`, and `hashCode` generation. There is a new mechanism to mark which fields (and now, methods) are to be included or excluded for the generation of these methods: mark the relevant member with for example `@ToString.Include` or `@EqualsAndHashCode.Exclude`. [ToString documentation](https://projectlombok.org/features/ToString) [EqualsAndHashCode documentation](https://projectlombok.org/features/EqualsAndHashCode) * FEATURE: `@Getter` and `@Setter` also allow `onMethod` and `onParam` when put on a type. [Issue #1653](https://github.com/rzwitserloot/lombok/issues/1653) -* FEATURE: `@FieldNameConstants` is an new feature that generates string constants for your field names. [Docs on @FieldNameConstants](https://projectlombok.org/features/experimental/FieldNameConstants). +* FEATURE: `@FieldNameConstants` is a new feature that generates string constants for your field names. [Docs on @FieldNameConstants](https://projectlombok.org/features/experimental/FieldNameConstants). +* PLATFORM: lombok now counts as an _incremental annotation processor_ for gradle. Should speed up your gradle builds considerably! [Issue #1580](https://github.com/rzwitserloot/lombok/issues/1580) * PLATFORM: Fix for using lombok together with JDK9's new `module-info.java` feature. [Issue #985](https://github.com/rzwitserloot/lombok/issues/985) * PLATFORM: Some initial work on supporting JDK10 and JDK11. * BUGFIX: Solved some issues in eclipse that resulted in error 'A save participant caused problems'. [Issue #879](https://github.com/rzwitserloot/lombok/issues/879) diff --git a/website/templates/features/EqualsAndHashCode.html b/website/templates/features/EqualsAndHashCode.html index 3c11367f..5a7b8166 100644 --- a/website/templates/features/EqualsAndHashCode.html +++ b/website/templates/features/EqualsAndHashCode.html @@ -3,7 +3,7 @@ <@f.scaffold title="@EqualsAndHashCode" logline="Equality made easy: Generates hashCode and equals implementations from the fields of your object."> <@f.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. Alternatively, you can specify exactly which fields you wish to be used by naming them in the of parameter. + 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 modify which fields are used (and even specify that the output of various methods is to be used) by marking type members with @EqualsAndHashCode.Include or @EqualsAndHashCode.Exclude. Alternatively, you can specify exactly which fields or methods you wish to be used by marking them with @EqualsAndHashCode.Include and using @EqualsAndHashCode(onlyExplicitlyIncluded = true).

If applying @EqualsAndHashCode to a class that extends another, this feature gets a bit trickier. Normally, auto-generating an equals and hashCode method for such classes is a bad idea, as the superclass also defines fields, which also need equals/hashCode code but this code will not be generated. 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 forequals, 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. If you have an explicit superclass you are forced to supply some value for callSuper to acknowledge that you've considered it; failure to do so results in a warning.

@@ -43,11 +43,13 @@

If there is any method named either hashCode or equals, regardless of return type, no methods will be generated, and a warning is emitted instead. These 2 methods need to be in sync with each other, which lombok cannot guarantee unless it generates all the methods, hence you always get a warning if one or both of the methods already exist. You can mark any method with @lombok.experimental.Tolerate to hide them from lombok.

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

- Having both exclude and of generates a warning; the exclude parameter will be ignored in that case. + If a method is marked for inclusion and it has the same name as a field, it replaces the field (the method is included, the field is excluded).

- By default, any variables that start with a $ symbol are excluded automatically. You can onlyinclude them by using the 'of' parameter. + Prior to lombok 1.16.22, inclusion/exclusion could be done with the of and exclude parameters of the @EqualsAndHashCode annotation. This old-style inclusion mechanism is still supported but will be deprecated in the future. +

+ By default, any variables that start with a $ symbol are excluded automatically. You can only include them by marking them with @EqualsAndHashCode.Include.

If a getter exists for a field to be included, it is called instead of using a direct field reference. This behaviour can be suppressed:
@EqualsAndHashCode(doNotUseGetters = true) diff --git a/website/templates/features/ToString.html b/website/templates/features/ToString.html index 6f230561..d31cf35d 100644 --- a/website/templates/features/ToString.html +++ b/website/templates/features/ToString.html @@ -7,9 +7,13 @@

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

- By default, 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. Alternatively, you can specify exactly which fields you wish to be used by naming them in the of parameter. + By default, all non-static fields will be printed. If you want to skip some fields, you can annotate these fields with @ToString.Exclude. Alternatively, you can specify exactly which fields you wish to be used by using @ToString(onlyExplicitlyIncluded = true), then marking each field you want to include with @ToString.Include.

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

+ You can also include the output of a method call in your toString. Only instance (non-static) methods that take no arguments can be included. To do so, mark the method with @ToString.Include. +

+ You can change the name used to identify the member with @ToString.Include(name = "some other name"), and you can change the order in which the members are printed via @ToString.Include(rank = -1). Members without a rank are considered to have rank 0, members of a higher rank are printed first, and members of the same rank are printed in the same order they appear in the source file.

@@ -37,13 +41,15 @@

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.

- 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. + If a method is marked for inclusion and it has the same name as a field, it replaces the toString output for that field (the method is included, the field is excluded, and the method's output is printed in the place the field would be printed). +

+ Prior to lombok 1.16.22, inclusion/exclusion could be done with the of and exclude parameters of the @ToString annotation. This old-style inclusion mechanism is still supported but will be deprecated in the future.

- Having both exclude and of generates a warning; the exclude parameter will be ignored in that case. + Having both @ToString.Exclude and @ToString.Include on a member generates a warning; the member will be excluded in this case.

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!

- By default, any variables that start with a $ symbol are excluded automatically. You can only include them by using the 'of' parameter. + By default, any variables that start with a $ symbol are excluded automatically. You can only include them by using the @ToString.Include annotation.

If a getter exists for a field to be included, it is called instead of using a direct field reference. This behaviour can be suppressed:
@ToString(doNotUseGetters = true) diff --git a/website/usageExamples/EqualsAndHashCodeExample_pre.jpage b/website/usageExamples/EqualsAndHashCodeExample_pre.jpage index 64faf59f..cf235917 100644 --- a/website/usageExamples/EqualsAndHashCodeExample_pre.jpage +++ b/website/usageExamples/EqualsAndHashCodeExample_pre.jpage @@ -1,13 +1,13 @@ import lombok.EqualsAndHashCode; -@EqualsAndHashCode(exclude={"id", "shape"}) +@EqualsAndHashCode public class EqualsAndHashCodeExample { private transient int transientVar = 10; private String name; private double score; - private Shape shape = new Square(5, 10); + @EqualsAndHashCode.Exclude private Shape shape = new Square(5, 10); private String[] tags; - private int id; + @EqualsAndHashCode.Exclude private int id; public String getName() { return this.name; diff --git a/website/usageExamples/ToStringExample_pre.jpage b/website/usageExamples/ToStringExample_pre.jpage index 39b25892..1b6b58e0 100644 --- a/website/usageExamples/ToStringExample_pre.jpage +++ b/website/usageExamples/ToStringExample_pre.jpage @@ -1,12 +1,12 @@ import lombok.ToString; -@ToString(exclude="id") +@ToString public class ToStringExample { private static final int STATIC_VAR = 10; private String name; private Shape shape = new Square(5, 10); private String[] tags; - private int id; + @ToString.Exclude private int id; public String getName() { return this.name; -- cgit