From d8da2b9438056e945ecc38d98fed413444c847b3 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Mon, 2 Feb 2015 04:47:21 +0100 Subject: added impl for @UtilityClass. --- buildScripts/website.ant.xml | 3 + doc/changelog.markdown | 3 +- .../eclipse/handlers/HandleUtilityClass.java | 173 +++++++++++++++++++++ src/core/lombok/experimental/UtilityClass.java | 12 +- .../lombok/javac/handlers/HandleUtilityClass.java | 103 ++++++------ .../resource/after-delombok/UtilityClass.java | 26 ++++ .../after-delombok/UtilityClassErrors.java | 12 ++ .../transform/resource/after-ecj/UtilityClass.java | 33 ++++ .../resource/after-ecj/UtilityClassErrors.java | 20 +++ test/transform/resource/before/UtilityClass.java | 20 +++ .../resource/before/UtilityClassErrors.java | 14 ++ .../UtilityClassErrors.java.messages | 3 + .../messages-ecj/UtilityClassErrors.java.messages | 3 + .../experimental/UtilityClassExample_post.jpage | 11 ++ .../experimental/UtilityClassExample_pre.jpage | 10 ++ website/features/experimental/UtilityClass.html | 80 ++++++++++ website/features/experimental/index.html | 2 + website/features/experimental/onX.html | 2 +- 18 files changed, 479 insertions(+), 51 deletions(-) create mode 100644 src/core/lombok/eclipse/handlers/HandleUtilityClass.java create mode 100644 test/transform/resource/after-delombok/UtilityClass.java create mode 100644 test/transform/resource/after-delombok/UtilityClassErrors.java create mode 100644 test/transform/resource/after-ecj/UtilityClass.java create mode 100644 test/transform/resource/after-ecj/UtilityClassErrors.java create mode 100644 test/transform/resource/before/UtilityClass.java create mode 100644 test/transform/resource/before/UtilityClassErrors.java create mode 100644 test/transform/resource/messages-delombok/UtilityClassErrors.java.messages create mode 100644 test/transform/resource/messages-ecj/UtilityClassErrors.java.messages create mode 100644 usage_examples/experimental/UtilityClassExample_post.jpage create mode 100644 usage_examples/experimental/UtilityClassExample_pre.jpage create mode 100644 website/features/experimental/UtilityClass.html diff --git a/buildScripts/website.ant.xml b/buildScripts/website.ant.xml index b7a86cf3..4b64da85 100644 --- a/buildScripts/website.ant.xml +++ b/buildScripts/website.ant.xml @@ -172,6 +172,9 @@ such as converting the changelog into HTML, and creating javadoc. + + + diff --git a/doc/changelog.markdown b/doc/changelog.markdown index 4243a9be..319c8399 100644 --- a/doc/changelog.markdown +++ b/doc/changelog.markdown @@ -2,9 +2,10 @@ Lombok Changelog ---------------- ### v1.16.1 "Edgy Guinea Pig" +* FEATURE: The config key `lombok.extern.findbugs.addSuppressFBWarnings` can now be used to add findbugs suppress warnings annotations to all code lombok generates. This addresses feature request [Issue #702](https://code.google.com/p/projectlombok/issues/detail?id=702). +* FEATURE: New lombok annotation: `@UtilityClass`, for making utility classes (not instantiable, contains only static 'function' methods). See the [feature documentation](http://projectlombok.org/features/experimental/UtilityClass.html) for more information. * BUGFIX: The ant `delombok` task was broken starting with v1.16.0. Note that the task def class has been changed; taskdef `lombok.delombok.ant.Tasks$Delombok` instead of the old `lombok.delombok.ant.DelombokTask`. [Issue #775](https://code.google.com/p/projectlombok/issues/detail?id=775). * BUGFIX: `val` in javac would occasionally fail if used inside inner classes. This is (probably) fixed. [Issue #694](https://code.google.com/p/projectlombok/issues/detail?id=694). -* FEATURE: The config key `lombok.extern.findbugs.addSuppressFBWarnings` can now be used to add findbugs suppress warnings annotations to all code lombok generates. This addresses feature request [Issue #702](https://code.google.com/p/projectlombok/issues/detail?id=702). ### v1.16.0 "Candid Duck" (January 26th, 2015) * BUGFIX: `@ExtensionMethod` was broken in Eclipse using java 8. [Issue #742](https://code.google.com/p/projectlombok/issues/detail?id=742), [Issue #747](https://code.google.com/p/projectlombok/issues/detail?id=747) diff --git a/src/core/lombok/eclipse/handlers/HandleUtilityClass.java b/src/core/lombok/eclipse/handlers/HandleUtilityClass.java new file mode 100644 index 00000000..36a7dc9c --- /dev/null +++ b/src/core/lombok/eclipse/handlers/HandleUtilityClass.java @@ -0,0 +1,173 @@ +/* + * Copyright (C) 2015 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 + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package lombok.eclipse.handlers; + +import static lombok.core.handlers.HandlerUtil.*; +import static lombok.eclipse.Eclipse.*; +import static lombok.eclipse.handlers.EclipseHandlerUtil.*; + +import java.util.Arrays; + +import org.eclipse.jdt.internal.compiler.ast.ASTNode; +import org.eclipse.jdt.internal.compiler.ast.AbstractMethodDeclaration; +import org.eclipse.jdt.internal.compiler.ast.AllocationExpression; +import org.eclipse.jdt.internal.compiler.ast.Annotation; +import org.eclipse.jdt.internal.compiler.ast.CompilationUnitDeclaration; +import org.eclipse.jdt.internal.compiler.ast.ConstructorDeclaration; +import org.eclipse.jdt.internal.compiler.ast.ExplicitConstructorCall; +import org.eclipse.jdt.internal.compiler.ast.Expression; +import org.eclipse.jdt.internal.compiler.ast.FieldDeclaration; +import org.eclipse.jdt.internal.compiler.ast.MethodDeclaration; +import org.eclipse.jdt.internal.compiler.ast.QualifiedTypeReference; +import org.eclipse.jdt.internal.compiler.ast.Statement; +import org.eclipse.jdt.internal.compiler.ast.StringLiteral; +import org.eclipse.jdt.internal.compiler.ast.ThrowStatement; +import org.eclipse.jdt.internal.compiler.ast.TypeDeclaration; +import org.eclipse.jdt.internal.compiler.classfmt.ClassFileConstants; +import org.eclipse.jdt.internal.compiler.lookup.TypeConstants; +import org.mangosdk.spi.ProviderFor; + +import lombok.ConfigurationKeys; +import lombok.core.AnnotationValues; +import lombok.core.AST.Kind; +import lombok.eclipse.EclipseAnnotationHandler; +import lombok.eclipse.EclipseNode; +import lombok.experimental.UtilityClass; + +/** + * Handles the {@code lombok.experimental.UtilityClass} annotation for eclipse. + */ +@ProviderFor(EclipseAnnotationHandler.class) +public class HandleUtilityClass extends EclipseAnnotationHandler { + @Override public void handle(AnnotationValues annotation, Annotation ast, EclipseNode annotationNode) { + handleFlagUsage(annotationNode, ConfigurationKeys.UTLITY_CLASS_FLAG_USAGE, "@UtilityClass"); + + EclipseNode typeNode = annotationNode.up(); + if (!checkLegality(typeNode, annotationNode)) return; + changeModifiersAndGenerateConstructor(annotationNode.up(), annotationNode); + } + + private static boolean checkLegality(EclipseNode typeNode, EclipseNode errorNode) { + TypeDeclaration typeDecl = null; + if (typeNode.get() instanceof TypeDeclaration) typeDecl = (TypeDeclaration) typeNode.get(); + int modifiers = typeDecl == null ? 0 : typeDecl.modifiers; + boolean notAClass = (modifiers & (ClassFileConstants.AccInterface | ClassFileConstants.AccAnnotation | ClassFileConstants.AccEnum)) != 0; + + if (typeDecl == null || notAClass) { + errorNode.addError("@UtilityClass is only supported on a class (can't be an interface, enum, or annotation)."); + return false; + } + + // It might be an inner class. This is okay, but only if it is / can be a static inner class. Thus, all of its parents have to be static inner classes until the top-level. + EclipseNode typeWalk = typeNode; + while (true) { + typeWalk = typeWalk.up(); + switch (typeWalk.getKind()) { + case TYPE: + if ((((TypeDeclaration) typeWalk.get()).modifiers & ClassFileConstants.AccStatic) != 0) continue; + if (typeWalk.up().getKind() == Kind.COMPILATION_UNIT) return true; + case COMPILATION_UNIT: + return true; + default: + errorNode.addError("@UtilityClass cannot be placed on a method local or anonymous inner class, or any class nested in such a class."); + return false; + } + } + } + + private void changeModifiersAndGenerateConstructor(EclipseNode typeNode, EclipseNode annotationNode) { + TypeDeclaration classDecl = (TypeDeclaration) typeNode.get(); + + boolean makeConstructor = true; + + classDecl.modifiers |= ClassFileConstants.AccFinal; + + if (typeNode.up().getKind() != Kind.COMPILATION_UNIT) classDecl.modifiers |= ClassFileConstants.AccStatic; + + for (EclipseNode element : typeNode.down()) { + if (element.getKind() == Kind.FIELD) { + FieldDeclaration fieldDecl = (FieldDeclaration) element.get(); + fieldDecl.modifiers |= ClassFileConstants.AccStatic; + } else if (element.getKind() == Kind.METHOD) { + AbstractMethodDeclaration amd = (AbstractMethodDeclaration) element.get(); + if (amd instanceof ConstructorDeclaration) { + ConstructorDeclaration constrDecl = (ConstructorDeclaration) element.get(); + if (getGeneratedBy(constrDecl) == null && (constrDecl.bits & ASTNode.IsDefaultConstructor) == 0) { + element.addError("@UtilityClasses cannot have declared constructors."); + makeConstructor = false; + continue; + } + } else if (amd instanceof MethodDeclaration) { + amd.modifiers |= ClassFileConstants.AccStatic; + } + } else if (element.getKind() == Kind.TYPE) { + ((TypeDeclaration) element.get()).modifiers |= ClassFileConstants.AccStatic; + } + } + + if (makeConstructor) createPrivateDefaultConstructor(typeNode, annotationNode); + } + + private static final char[][] JAVA_LANG_UNSUPPORTED_OPERATION_EXCEPTION = new char[][] { + TypeConstants.JAVA, TypeConstants.LANG, "UnsupportedOperationException".toCharArray() + }; + + private static final char[] UNSUPPORTED_MESSAGE = "This is a utility class and cannot be instantiated".toCharArray(); + + private void createPrivateDefaultConstructor(EclipseNode typeNode, EclipseNode sourceNode) { + ASTNode source = sourceNode.get(); + + TypeDeclaration typeDeclaration = ((TypeDeclaration) typeNode.get()); + long p = (long) source.sourceStart << 32 | source.sourceEnd; + + ConstructorDeclaration constructor = new ConstructorDeclaration(((CompilationUnitDeclaration) typeNode.top().get()).compilationResult); + + constructor.modifiers = ClassFileConstants.AccPrivate; + constructor.selector = typeDeclaration.name; + constructor.constructorCall = new ExplicitConstructorCall(ExplicitConstructorCall.ImplicitSuper); + constructor.constructorCall.sourceStart = source.sourceStart; + constructor.constructorCall.sourceEnd = source.sourceEnd; + constructor.thrownExceptions = null; + constructor.typeParameters = null; + constructor.bits |= ECLIPSE_DO_NOT_TOUCH_FLAG; + constructor.bodyStart = constructor.declarationSourceStart = constructor.sourceStart = source.sourceStart; + constructor.bodyEnd = constructor.declarationSourceEnd = constructor.sourceEnd = source.sourceEnd; + constructor.arguments = null; + + AllocationExpression exception = new AllocationExpression(); + setGeneratedBy(exception, source); + long[] ps = new long[3]; + Arrays.fill(ps, p); + exception.type = new QualifiedTypeReference(JAVA_LANG_UNSUPPORTED_OPERATION_EXCEPTION, ps); + setGeneratedBy(exception.type, source); + exception.arguments = new Expression[] { + new StringLiteral(UNSUPPORTED_MESSAGE, source.sourceStart, source.sourceEnd, 0) + }; + setGeneratedBy(exception.arguments[0], source); + ThrowStatement throwStatement = new ThrowStatement(exception, source.sourceStart, source.sourceEnd); + setGeneratedBy(throwStatement, source); + + constructor.statements = new Statement[] {throwStatement}; + + injectMethod(typeNode, constructor); + } +} diff --git a/src/core/lombok/experimental/UtilityClass.java b/src/core/lombok/experimental/UtilityClass.java index 778cfb80..80f3eee9 100644 --- a/src/core/lombok/experimental/UtilityClass.java +++ b/src/core/lombok/experimental/UtilityClass.java @@ -1,5 +1,5 @@ /* - * Copyright (C) 2012-2013 The Project Lombok Authors. + * Copyright (C) 2015 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,13 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * A helper to create utilities classes. - *

- * It makes the class final, makes all its methods static, creates a private default constructor that throws a RuntimeException when called and yields an error when other constructors are defined. + * An annotation to create utility classes. + * + * If a class is annotated with {@code @UtilityClass}, the following things happen to it:

It is marked final.
If any constructors are declared in it, an error is generated. Otherwise, a private no-args constructor is generated; it throws a {@code UnsupportedOperationException}.
All methods, inner classes, and fields in the class are marked static.

*/ @Target({ElementType.TYPE}) @Retention(RetentionPolicy.SOURCE) diff --git a/src/core/lombok/javac/handlers/HandleUtilityClass.java b/src/core/lombok/javac/handlers/HandleUtilityClass.java index 4ab3f8dc..9a37653e 100644 --- a/src/core/lombok/javac/handlers/HandleUtilityClass.java +++ b/src/core/lombok/javac/handlers/HandleUtilityClass.java @@ -1,5 +1,5 @@ /* - * Copyright (C) 2012-2014 The Project Lombok Authors. + * Copyright (C) 2015 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 @@ -21,7 +21,7 @@ */ package lombok.javac.handlers; -import static lombok.core.handlers.HandlerUtil.handleExperimentalFlagUsage; +import static lombok.core.handlers.HandlerUtil.*; import static lombok.javac.handlers.JavacHandlerUtil.*; import lombok.ConfigurationKeys; import lombok.core.AST.Kind; @@ -48,70 +48,81 @@ import com.sun.tools.javac.util.ListBuffer; import com.sun.tools.javac.util.Name; /** - * Handles the {@code lombok.experimental.UtilityClass} annotation for javac. + * Handles the {@code @UtilityClass} annotation for javac. */ -@ProviderFor(JavacAnnotationHandler.class) public class HandleUtilityClass extends JavacAnnotationHandler { - +@ProviderFor(JavacAnnotationHandler.class) +public class HandleUtilityClass extends JavacAnnotationHandler { @Override public void handle(AnnotationValues annotation, JCAnnotation ast, JavacNode annotationNode) { handleExperimentalFlagUsage(annotationNode, ConfigurationKeys.UTLITY_CLASS_FLAG_USAGE, "@UtilityClass"); + deleteAnnotationIfNeccessary(annotationNode, UtilityClass.class); - - parse(annotationNode.up(), annotationNode); + + JavacNode typeNode = annotationNode.up(); + if (!checkLegality(typeNode, annotationNode)) return; + changeModifiersAndGenerateConstructor(annotationNode.up(), annotationNode); } - - private JCClassDecl getClassDecl(JavacNode typeNode) { + + private static boolean checkLegality(JavacNode typeNode, JavacNode errorNode) { JCClassDecl typeDecl = null; - if (typeNode.get() instanceof JCClassDecl) { - typeDecl = (JCClassDecl) typeNode.get(); - } - + if (typeNode.get() instanceof JCClassDecl) typeDecl = (JCClassDecl) typeNode.get(); long modifiers = typeDecl == null ? 0 : typeDecl.mods.flags; boolean notAClass = (modifiers & (Flags.INTERFACE | Flags.ANNOTATION | Flags.ENUM)) != 0; - return notAClass ? null : typeDecl; - } - - public void parse(JavacNode typeNode, JavacNode errorNode) { - JCClassDecl classDecl = getClassDecl(typeNode); - if (classDecl == null) { - errorNode.addError("@UtilityClass is only supported on a class (can't be interface, enum or annotation)."); - return; + + if (typeDecl == null || notAClass) { + errorNode.addError("@UtilityClass is only supported on a class (can't be an interface, enum, or annotation)."); + return false; } - - if (!is(classDecl.getModifiers(), Flags.FINAL)) { - classDecl.mods.flags |= Flags.FINAL; + + // It might be an inner class. This is okay, but only if it is / can be a static inner class. Thus, all of its parents have to be static inner classes until the top-level. + JavacNode typeWalk = typeNode; + while (true) { + typeWalk = typeWalk.up(); + switch (typeWalk.getKind()) { + case TYPE: + if ((((JCClassDecl) typeWalk.get()).mods.flags & Flags.STATIC) != 0) continue; + if (typeWalk.up().getKind() == Kind.COMPILATION_UNIT) return true; + case COMPILATION_UNIT: + return true; + default: + errorNode.addError("@UtilityClass cannot be placed on a method local or anonymous inner class, or any class nested in such a class."); + return false; + } } - + } + + private void changeModifiersAndGenerateConstructor(JavacNode typeNode, JavacNode errorNode) { + JCClassDecl classDecl = (JCClassDecl) typeNode.get(); + + boolean makeConstructor = true; + + classDecl.mods.flags |= Flags.FINAL; + + if (typeNode.up().getKind() != Kind.COMPILATION_UNIT) classDecl.mods.flags |= Flags.STATIC; + for (JavacNode element : typeNode.down()) { if (element.getKind() == Kind.FIELD) { JCVariableDecl fieldDecl = (JCVariableDecl) element.get(); - if (!is(fieldDecl.mods, Flags.STATIC)) { - fieldDecl.mods.flags |= Flags.STATIC; - } + fieldDecl.mods.flags |= Flags.STATIC; } else if (element.getKind() == Kind.METHOD) { JCMethodDecl methodDecl = (JCMethodDecl) element.get(); if (methodDecl.name.contentEquals("")) { - if (!is(methodDecl.mods, Flags.GENERATEDCONSTR)) { - errorNode.addError("@UtilityClasses cannot have declared constructors."); + if (getGeneratedBy(methodDecl) == null && (methodDecl.mods.flags & Flags.GENERATEDCONSTR) == 0) { + element.addError("@UtilityClasses cannot have declared constructors."); + makeConstructor = false; continue; } - } else if (!is(methodDecl.mods, Flags.STATIC)) { - methodDecl.mods.flags |= Flags.STATIC; } + + methodDecl.mods.flags |= Flags.STATIC; } else if (element.getKind() == Kind.TYPE) { - JCClassDecl innerClassDecl = (JCClassDecl) typeNode.get(); - if (!is(innerClassDecl.mods, Flags.STATIC)) { - innerClassDecl.mods.flags |= Flags.STATIC; - } + JCClassDecl innerClassDecl = (JCClassDecl) element.get(); + innerClassDecl.mods.flags |= Flags.STATIC; } } - - createPrivateDefaultConstructor(typeNode); - } - - private static boolean is(JCModifiers mods, long f) { - return (mods.flags & f) != 0; + + if (makeConstructor) createPrivateDefaultConstructor(typeNode); } - + private void createPrivateDefaultConstructor(JavacNode typeNode) { JavacTreeMaker maker = typeNode.getTreeMaker(); JCModifiers mods = maker.Modifiers(Flags.PRIVATE, List.nil()); @@ -125,8 +136,10 @@ import com.sun.tools.javac.util.Name; private List createThrowStatement(JavacNode typeNode, JavacTreeMaker maker) { ListBuffer statements = new ListBuffer(); - JCExpression exceptionType = genTypeRef(typeNode, "java.lang.RuntimeException"); - JCExpression exceptionInstance = maker.NewClass(null, List.nil(), exceptionType, List.of(maker.Literal("Should not be instanciated!")), null); + JCExpression exceptionType = genTypeRef(typeNode, "java.lang.UnsupportedOperationException"); + List jceBlank = List.nil(); + JCExpression message = maker.Literal("This is a utility class and cannot be instantiated"); + JCExpression exceptionInstance = maker.NewClass(null, jceBlank, exceptionType, List.of(message), null); JCStatement throwStatement = maker.Throw(exceptionInstance); statements.add(throwStatement); return statements.toList(); diff --git a/test/transform/resource/after-delombok/UtilityClass.java b/test/transform/resource/after-delombok/UtilityClass.java new file mode 100644 index 00000000..f9fe02a0 --- /dev/null +++ b/test/transform/resource/after-delombok/UtilityClass.java @@ -0,0 +1,26 @@ +final class UtilityClass { + private static String someField; + static void someMethod() { + System.out.println(); + } + protected static class InnerClass { + private String innerInnerMember; + } + @java.lang.SuppressWarnings("all") + @javax.annotation.Generated("lombok") + private UtilityClass() { + throw new java.lang.UnsupportedOperationException("This is a utility class and cannot be instantiated"); + } +} +class UtilityInner { + static class InnerInner { + static final class InnerInnerInner { + static int member; + @java.lang.SuppressWarnings("all") + @javax.annotation.Generated("lombok") + private InnerInnerInner() { + throw new java.lang.UnsupportedOperationException("This is a utility class and cannot be instantiated"); + } + } + } +} \ No newline at end of file diff --git a/test/transform/resource/after-delombok/UtilityClassErrors.java b/test/transform/resource/after-delombok/UtilityClassErrors.java new file mode 100644 index 00000000..b19b4e72 --- /dev/null +++ b/test/transform/resource/after-delombok/UtilityClassErrors.java @@ -0,0 +1,12 @@ +final class UtilityClassErrors1 { + private static String someField; + protected UtilityClassErrors1() { + } + static void method() { + class MethodLocalClass { + } + } +} +enum UtilityClassErrors2 { +; +} \ No newline at end of file diff --git a/test/transform/resource/after-ecj/UtilityClass.java b/test/transform/resource/after-ecj/UtilityClass.java new file mode 100644 index 00000000..c3e06fbc --- /dev/null +++ b/test/transform/resource/after-ecj/UtilityClass.java @@ -0,0 +1,33 @@ +final @lombok.experimental.UtilityClass class UtilityClass { + protected static class InnerClass { + private String innerInnerMember; + protected InnerClass() { + super(); + } + } + private static String someField; + static void someMethod() { + System.out.println(); + } + private @java.lang.SuppressWarnings("all") @javax.annotation.Generated("lombok") UtilityClass() { + super(); + throw new java.lang.UnsupportedOperationException("This is a utility class and cannot be instantiated"); + } +} +class UtilityInner { + static class InnerInner { + static final @lombok.experimental.UtilityClass class InnerInnerInner { + static int member; + private @java.lang.SuppressWarnings("all") @javax.annotation.Generated("lombok") InnerInnerInner() { + super(); + throw new java.lang.UnsupportedOperationException("This is a utility class and cannot be instantiated"); + } + } + InnerInner() { + super(); + } + } + UtilityInner() { + super(); + } +} \ No newline at end of file diff --git a/test/transform/resource/after-ecj/UtilityClassErrors.java b/test/transform/resource/after-ecj/UtilityClassErrors.java new file mode 100644 index 00000000..03206592 --- /dev/null +++ b/test/transform/resource/after-ecj/UtilityClassErrors.java @@ -0,0 +1,20 @@ +final @lombok.experimental.UtilityClass class UtilityClassErrors1 { + private static String someField; + protected UtilityClassErrors1() { + super(); + } + static void method() { + @lombok.experimental.UtilityClass class MethodLocalClass { + MethodLocalClass() { + super(); + } + } + } +} +@lombok.experimental.UtilityClass enum UtilityClassErrors2 { + () { + } + UtilityClassErrors2() { + super(); + } +} diff --git a/test/transform/resource/before/UtilityClass.java b/test/transform/resource/before/UtilityClass.java new file mode 100644 index 00000000..ccfa43e1 --- /dev/null +++ b/test/transform/resource/before/UtilityClass.java @@ -0,0 +1,20 @@ +@lombok.experimental.UtilityClass +class UtilityClass { + private String someField; + + void someMethod() { + System.out.println(); + } + + protected class InnerClass { + private String innerInnerMember; + } +} +class UtilityInner { + static class InnerInner { + @lombok.experimental.UtilityClass + class InnerInnerInner { + int member; + } + } +} diff --git a/test/transform/resource/before/UtilityClassErrors.java b/test/transform/resource/before/UtilityClassErrors.java new file mode 100644 index 00000000..5f72274b --- /dev/null +++ b/test/transform/resource/before/UtilityClassErrors.java @@ -0,0 +1,14 @@ +@lombok.experimental.UtilityClass +class UtilityClassErrors1 { + private String someField; + protected UtilityClassErrors1() { + } + void method() { + @lombok.experimental.UtilityClass + class MethodLocalClass { + } + } +} +@lombok.experimental.UtilityClass +enum UtilityClassErrors2 { +} \ No newline at end of file diff --git a/test/transform/resource/messages-delombok/UtilityClassErrors.java.messages b/test/transform/resource/messages-delombok/UtilityClassErrors.java.messages new file mode 100644 index 00000000..230ba04f --- /dev/null +++ b/test/transform/resource/messages-delombok/UtilityClassErrors.java.messages @@ -0,0 +1,3 @@ +4 @UtilityClasses cannot have declared constructors. +7 @UtilityClass cannot be placed on a method local or anonymous inner class, or any class nested in such a class. +12 @UtilityClass is only supported on a class (can't be an interface, enum, or annotation). diff --git a/test/transform/resource/messages-ecj/UtilityClassErrors.java.messages b/test/transform/resource/messages-ecj/UtilityClassErrors.java.messages new file mode 100644 index 00000000..c80a18dc --- /dev/null +++ b/test/transform/resource/messages-ecj/UtilityClassErrors.java.messages @@ -0,0 +1,3 @@ +4 @UtilityClasses cannot have declared constructors. +7 @UtilityClass cannot be placed on a method local or anonymous inner class, or any class nested in such a class. +12 @UtilityClass is only supported on a class (can't be an interface, enum, or annotation) \ No newline at end of file diff --git a/usage_examples/experimental/UtilityClassExample_post.jpage b/usage_examples/experimental/UtilityClassExample_post.jpage new file mode 100644 index 00000000..70810230 --- /dev/null +++ b/usage_examples/experimental/UtilityClassExample_post.jpage @@ -0,0 +1,11 @@ +public final class UtilityClassExample { + private static final int CONSTANT = 5; + + private UtilityClassExample() { + throw new java.lang.UnsupportedOperationException("This is a utility class and cannot be instantiated"); + } + + public static void addSomething(int in) { + return in + CONSTANT; + } +} diff --git a/usage_examples/experimental/UtilityClassExample_pre.jpage b/usage_examples/experimental/UtilityClassExample_pre.jpage new file mode 100644 index 00000000..85731b81 --- /dev/null +++ b/usage_examples/experimental/UtilityClassExample_pre.jpage @@ -0,0 +1,10 @@ +import lombok.experimental.UtilityClass; + +@UtilityClass +public class UtilityClassExample { + private final int CONSTANT = 5; + + public void addSomething(int in) { + return in + CONSTANT; + } +} diff --git a/website/features/experimental/UtilityClass.html b/website/features/experimental/UtilityClass.html new file mode 100644 index 00000000..5526ec77 --- /dev/null +++ b/website/features/experimental/UtilityClass.html @@ -0,0 +1,80 @@ + + + + + + + + @UtilityClass +

+

+

+ +

@UtilityClass

+

Utility, metility, wetility! Utility classes for the masses.

+

+

Since

+

+ @UtilityClass was introduced as an experimental feature in lombok v1.16.2. +

+

+

+

Experimental

+

+ Experimental because: +

Some debate as to whether its common enough to count as boilerplate.

+ Current status: positive - Currently we feel this feature may move out of experimental status with no or minor changes soon. +

+

+

Overview

+

+ A utility class is a class that is just a namespace for functions. No instances of it can exist, and all its members + are static. For example, java.lang.Math and java.util.Collections are well known utility classes. This annotation automatically turns the annotated class into one. +

+ A utility class cannot be instantiated. By marking your class with @UtilityClass, lombok will automatically + generate a private constructor that throws an exception, flags as error any explicit constructors you add, and marks + the class final. If the class is an inner class, the class is also marked static. +

+ All members of a utility class are automatically marked as static. Even fields and inner classes. +

+

+

+

+

With Lombok

+

@HTML_PRE@

+

+

+

+

Vanilla Java

+

@HTML_POST@

+

+

+

+

+

Small print

+

+ There isn't currently any way to create non-static members, or to define your own constructor. If you want to instantiate + the utility class, even only as an internal implementation detail, @UtilityClass cannot be used. +

+

+

+ +

+

+

+ + + diff --git a/website/features/experimental/index.html b/website/features/experimental/index.html index a5932b73..3f2d2802 100644 --- a/website/features/experimental/index.html +++ b/website/features/experimental/index.html @@ -34,6 +34,8 @@

Immutable 'setters' - methods that create a clone but with one changed field.

onMethod= / onConstructor= / onParam=

Sup dawg, we heard you like annotations, so we put annotations in your annotations so you can annotate while you're annotating.

+

@UtilityClass

+

Utility, metility, wetility! Utility classes for the masses.

diff --git a/website/features/experimental/onX.html b/website/features/experimental/onX.html index 064db557..ced78dff 100644 --- a/website/features/experimental/onX.html +++ b/website/features/experimental/onX.html @@ -69,7 +69,7 @@

-- cgit