From f8b3056dc4f61251aba7adf627c942c85e8618ca Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Sun, 1 Jun 2014 11:02:18 +0200 Subject: Fixed up and extended Tolerate with support for constructors, and added docs. --- doc/changelog.markdown | 3 ++ .../eclipse/handlers/EclipseHandlerUtil.java | 17 ++++++----- src/core/lombok/experimental/Tolerate.java | 7 +++-- .../lombok/javac/handlers/JavacHandlerUtil.java | 23 ++++++++------- website/features/Constructor.html | 4 +-- website/features/Data.html | 29 ++++-------------- website/features/EqualsAndHashCode.html | 34 +++++----------------- website/features/ToString.html | 16 ++++------ website/features/Value.html | 4 +-- 9 files changed, 50 insertions(+), 87 deletions(-) diff --git a/doc/changelog.markdown b/doc/changelog.markdown index 4f4cbca7..2a3a9577 100644 --- a/doc/changelog.markdown +++ b/doc/changelog.markdown @@ -2,6 +2,9 @@ Lombok Changelog ---------------- ### v1.14.1 "Edgy Guinea Pig" +* FEATURE: Added `@Tolerate`; put this annotation on any method or constructor and lombok will skip it when considering whether or not to generate a method or constructor. This is useful if the types of the parameters of your method do not clash with what lombok would generate. +* FEATURE: Added config key `lombok.getter.noIsPrefix`, which lets you disable use and generation of `isFoo()`, instead going with `getFoo()`, for {@code boolean} fields. +* BUGFIX: Errors in the eclipse log with `IndexOutOfBound: 2` in `ASTConverter.convertType`. [Issue #686](https://code.google.com/p/projectlombok/issues/detail?id=686) * BUGFIX-IN-PROGRESS: As yet unknown conditions in eclipse result in lots of `IllegalArgumentException` in the log with message "Path must include project and resource name". This edge release will no longer error out, but we need to know when or how this occurs, thus, warnings will appear instead in your log with information pertinent to solving this issue. Please report these warnings back to us. [Issue #682](https://code.google.com/p/projectlombok/issues/detail?id=682) * BUGFIX: mvn builds fail with a 'URI not absolute' exception. [Issue #683](https://code.google.com/p/projectlombok/issues/detail?id=683) diff --git a/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java b/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java index 11f31c9d..b37dbd81 100644 --- a/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java +++ b/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java @@ -1203,7 +1203,7 @@ public class EclipseHandlerUtil { if (node != null && node.get() instanceof TypeDeclaration) { TypeDeclaration typeDecl = (TypeDeclaration)node.get(); - if (typeDecl.methods != null) for (AbstractMethodDeclaration def : typeDecl.methods) { + if (typeDecl.methods != null) top: for (AbstractMethodDeclaration def : typeDecl.methods) { if (def instanceof MethodDeclaration) { char[] mName = def.selector; if (mName == null) continue; @@ -1225,13 +1225,9 @@ public class EclipseHandlerUtil { if (params < minArgs || params > maxArgs) continue; } - boolean tolerate = false; - if (def.annotations != null) { - for (Annotation anno : def.annotations) { - tolerate |= typeMatches(Tolerate.class, node, anno.type); - } + if (def.annotations != null) for (Annotation anno : def.annotations) { + if (typeMatches(Tolerate.class, node, anno.type)) continue top; } - if (tolerate) continue; return getGeneratedBy(def) == null ? MemberExistsResult.EXISTS_BY_USER : MemberExistsResult.EXISTS_BY_LOMBOK; } @@ -1255,9 +1251,14 @@ public class EclipseHandlerUtil { if (node != null && node.get() instanceof TypeDeclaration) { TypeDeclaration typeDecl = (TypeDeclaration)node.get(); - if (typeDecl.methods != null) for (AbstractMethodDeclaration def : typeDecl.methods) { + if (typeDecl.methods != null) top: for (AbstractMethodDeclaration def : typeDecl.methods) { if (def instanceof ConstructorDeclaration) { if ((def.bits & ASTNode.IsDefaultConstructor) != 0) continue; + + if (def.annotations != null) for (Annotation anno : def.annotations) { + if (typeMatches(Tolerate.class, node, anno.type)) continue top; + } + return getGeneratedBy(def) == null ? MemberExistsResult.EXISTS_BY_USER : MemberExistsResult.EXISTS_BY_LOMBOK; } } diff --git a/src/core/lombok/experimental/Tolerate.java b/src/core/lombok/experimental/Tolerate.java index 626a5890..4bc04b8b 100644 --- a/src/core/lombok/experimental/Tolerate.java +++ b/src/core/lombok/experimental/Tolerate.java @@ -1,5 +1,5 @@ /* - * Copyright (C) 2009-2013 The Project Lombok Authors. + * Copyright (C) 2014 The Project Lombok Authors. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -27,9 +27,10 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Put on any method to make lombok pretend it doesn't exist, i.e., to generate a method which would otherwise be skipped due to possible conflicts. + * Put on any method or constructor to make lombok pretend it doesn't exist, + * i.e., to generate a method which would otherwise be skipped due to possible conflicts. */ -@Target({ElementType.METHOD}) +@Target({ElementType.METHOD, ElementType.CONSTRUCTOR}) @Retention(RetentionPolicy.SOURCE) public @interface Tolerate { } diff --git a/src/core/lombok/javac/handlers/JavacHandlerUtil.java b/src/core/lombok/javac/handlers/JavacHandlerUtil.java index 474c5faa..25b95590 100644 --- a/src/core/lombok/javac/handlers/JavacHandlerUtil.java +++ b/src/core/lombok/javac/handlers/JavacHandlerUtil.java @@ -570,7 +570,7 @@ public class JavacHandlerUtil { node = upToTypeNode(node); if (node != null && node.get() instanceof JCClassDecl) { - for (JCTree def : ((JCClassDecl)node.get()).defs) { + top: for (JCTree def : ((JCClassDecl)node.get()).defs) { if (def instanceof JCMethodDecl) { JCMethodDecl md = (JCMethodDecl) def; String name = md.name.toString(); @@ -592,15 +592,11 @@ public class JavacHandlerUtil { if (params < minArgs || params > maxArgs) continue; } - - boolean tolerate = false; + List annotations = md.getModifiers().getAnnotations(); - if (annotations != null) { - for (JCAnnotation anno : annotations) { - tolerate |= typeMatches(Tolerate.class, node, anno.getAnnotationType()); - } + if (annotations != null) for (JCAnnotation anno : annotations) { + if (typeMatches(Tolerate.class, node, anno.getAnnotationType())) continue top; } - if (tolerate) continue; return getGeneratedBy(def) == null ? MemberExistsResult.EXISTS_BY_USER : MemberExistsResult.EXISTS_BY_LOMBOK; } @@ -621,10 +617,15 @@ public class JavacHandlerUtil { node = upToTypeNode(node); if (node != null && node.get() instanceof JCClassDecl) { - for (JCTree def : ((JCClassDecl)node.get()).defs) { + top: for (JCTree def : ((JCClassDecl)node.get()).defs) { if (def instanceof JCMethodDecl) { - if (((JCMethodDecl)def).name.contentEquals("")) { - if ((((JCMethodDecl)def).mods.flags & Flags.GENERATEDCONSTR) != 0) continue; + JCMethodDecl md = (JCMethodDecl) def; + if (md.name.contentEquals("")) { + if ((md.mods.flags & Flags.GENERATEDCONSTR) != 0) continue; + List annotations = md.getModifiers().getAnnotations(); + if (annotations != null) for (JCAnnotation anno : annotations) { + if (typeMatches(Tolerate.class, node, anno.getAnnotationType())) continue top; + } return getGeneratedBy(def) == null ? MemberExistsResult.EXISTS_BY_USER : MemberExistsResult.EXISTS_BY_LOMBOK; } } diff --git a/website/features/Constructor.html b/website/features/Constructor.html index a3163bfa..6dbbc0de 100644 --- a/website/features/Constructor.html +++ b/website/features/Constructor.html @@ -43,9 +43,7 @@ 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. + 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.

diff --git a/website/features/Data.html b/website/features/Data.html index 3ae03df1..c3d0a644 100644 --- a/website/features/Data.html +++ b/website/features/Data.html @@ -16,35 +16,18 @@

Overview

- @Data is a convenient shortcut annotation that bundles the features of @ToString, - @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, - in order to ensure the field is never null. + @Data is a convenient shortcut annotation that bundles the features of @ToString, @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, in order to ensure the field is never null.

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

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

- 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 (any explicit constructor will prevent @Data from generating one), - toString, equals, and all getters and setters. + If the class already contains a method with the same name and parameter count 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 equals(AnyType param), no equals method will be generated, even though technically it might be an entirely different method due to having different parameter types. The same rule applies to the constructor (any explicit constructor will prevent @Data from generating one), as well as toString, equals, and all getters and setters. You can mark any constructor or method with @lombok.experimental.Tolerate to hide them from lombok.

@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 - instance. This way, javac will infer the variable name. Thus, by declaring like so: @Data(staticConstructor="of") class Foo<T> { private T x;} - you can create new instances of Foo by writing: Foo.of(5); instead of having to write: new Foo<Integer>(5);. + generics, you can use the staticConstructor parameter to generate a private constructor, as well as a static method that returns a new instance. This way, javac will infer the variable name. Thus, by declaring like so: @Data(staticConstructor="of") class Foo<T> { private T x;} you can create new instances of Foo by writing: Foo.of(5); instead of having to write: new Foo<Integer>(5);.

diff --git a/website/features/EqualsAndHashCode.html b/website/features/EqualsAndHashCode.html index 89d71502..32dcb6c3 100644 --- a/website/features/EqualsAndHashCode.html +++ b/website/features/EqualsAndHashCode.html @@ -15,22 +15,11 @@

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

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

NEW in Lombok 0.10: Unless your class is final and extends java.lang.Object, lombok generates a canEqual method @@ -66,22 +55,15 @@

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. + 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. + 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. + 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 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. + 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. You therefore don't have to worry about typos.

Having both exclude and of generates a warning; the exclude parameter will be ignored in that case.

diff --git a/website/features/ToString.html b/website/features/ToString.html index 6cdd8453..57bbd0f0 100644 --- a/website/features/ToString.html +++ b/website/features/ToString.html @@ -15,18 +15,13 @@

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

@@ -55,8 +50,7 @@

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. + If there is any method named toString with no arguments, regardless of return type, no method will be generated, and instead a warning is emitted explaining that your @ToString annotation is doing nothing. You can mark any method with @lombok.experimental.Tolerate to hide them from lombok.

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. diff --git a/website/features/Value.html b/website/features/Value.html index 09557c6a..50309689 100644 --- a/website/features/Value.html +++ b/website/features/Value.html @@ -27,11 +27,11 @@ @Value is the immutable variant of @Data; all fields are made private and final by default, and setters are not generated. The class itself is also made final by default, because immutability is not something that can be forced onto a subclass. Like @Data, useful toString(), equals() and hashCode() methods are also generated, each field gets a getter method, and a constructor that covers every argument (except final fields that are initialized in the field declaration) is also generated.

- In practice, @Value is shorthand for: final @ToString @EqualsAndHashCode @AllArgsConstructor @FieldDefaults(makeFinal = true, level = AccessLevel.PRIVATE) @Getter, except that explicitly including an implementation of any of the relevant methods simply means that part won't be generated and no warning will be emitted. For example, if you write your own toString, no error occurs, and lombok will not generate a toString. Also, any explicit constructor, no matter the arguments list, implies lombok will not generate a constructor. If you do want lombok to generate the all-args constructor, add @AllArgsConstructor to the class. + In practice, @Value is shorthand for: final @ToString @EqualsAndHashCode @AllArgsConstructor @FieldDefaults(makeFinal = true, level = AccessLevel.PRIVATE) @Getter, except that explicitly including an implementation of any of the relevant methods simply means that part won't be generated and no warning will be emitted. For example, if you write your own toString, no error occurs, and lombok will not generate a toString. Also, any explicit constructor, no matter the arguments list, implies lombok will not generate a constructor. If you do want lombok to generate the all-args constructor, add @AllArgsConstructor to the class. You can mark any constructor or method with @lombok.experimental.Tolerate to hide them from lombok.

It is possible to override the final-by-default and private-by-default behaviour using either an explicit access level on a field, or by using the @NonFinal or @PackagePrivate annotations.
It is possible to override any default behaviour for any of the 'parts' that make up @Value by explicitly using that annotation. -

+

-- cgit