diff options
18 files changed, 479 insertions, 51 deletions
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. <antcall target="-integrateSnippet"> <param name="transformationName" value="experimental/onX" /> </antcall> + <antcall target="-integrateSnippet"> + <param name="transformationName" value="experimental/UtilityClass" /> + </antcall> </target> <target name="-website-dist"> 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<UtilityClass> { + @Override public void handle(AnnotationValues<UtilityClass> 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. - * <p> - * 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:<ul> + * <li>It is marked final.</li> + * <li>If any constructors are declared in it, an error is generated. Otherwise, a private no-args constructor is generated; it throws a {@code UnsupportedOperationException}.</li> + * <li>All methods, inner classes, and fields in the class are marked static.</li> + * </ul> */ @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<UtilityClass> { - +@ProviderFor(JavacAnnotationHandler.class) +public class HandleUtilityClass extends JavacAnnotationHandler<UtilityClass> { @Override public void handle(AnnotationValues<UtilityClass> 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("<init>")) { - 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.<JCAnnotation>nil()); @@ -125,8 +136,10 @@ import com.sun.tools.javac.util.Name; private List<JCStatement> createThrowStatement(JavacNode typeNode, JavacTreeMaker maker) { ListBuffer<JCStatement> statements = new ListBuffer<JCStatement>(); - JCExpression exceptionType = genTypeRef(typeNode, "java.lang.RuntimeException"); - JCExpression exceptionInstance = maker.NewClass(null, List.<JCExpression>nil(), exceptionType, List.<JCExpression>of(maker.Literal("Should not be instanciated!")), null); + JCExpression exceptionType = genTypeRef(typeNode, "java.lang.UnsupportedOperationException"); + List<JCExpression> 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 { + <clinit>() { + } + 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 @@ +<!DOCTYPE html> +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + <link rel="stylesheet" type="text/css" href="../../logi/reset.css" /> + <link rel="stylesheet" type="text/css" href="../features.css" /> + <link rel="shortcut icon" href="../../favicon.ico" type="image/x-icon" /> + <meta name="description" content="Spice up your java" /> + <title>@UtilityClass</title> +</head><body><div id="pepper"> + <div class="minimumHeight"></div> + <div class="meat"> + <div class="header"><a href="../../index.html">Project Lombok</a></div> + <h1>@UtilityClass</h1> + <div class="byline">Utility, metility, wetility! Utility classes for the masses.</div> + <div class="since"> + <h3>Since</h3> + <p> + <code>@UtilityClass</code> was introduced as an experimental feature in lombok v1.16.2. + </p> + </div> + <div class="experimental"> + <h3>Experimental</h3> + <p> + Experimental because: + <ul> + <li>Some debate as to whether its common enough to count as boilerplate.</li> + </ul> + Current status: <em>positive</em> - Currently we feel this feature may move out of experimental status with no or minor changes soon. + </div> + <div class="overview"> + <h3>Overview</h3> + <p> + 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, <code>java.lang.Math</code> and <code>java.util.Collections</code> are well known utility classes. This annotation automatically turns the annotated class into one. + </p><p> + A utility class cannot be instantiated. By marking your class with <code>@UtilityClass</code>, lombok will automatically + generate a private constructor that throws an exception, flags as error any explicit constructors you add, and marks + the class <code>final</code>. If the class is an inner class, the class is also marked <code>static</code>. + </p><p> + <em>All</em> members of a utility class are automatically marked as <code>static</code>. Even fields and inner classes. + </p> + </div> + <div class="snippets"> + <div class="pre"> + <h3>With Lombok</h3> + <div class="snippet">@HTML_PRE@</div> + </div> + <div class="sep"></div> + <div class="post"> + <h3>Vanilla Java</h3> + <div class="snippet">@HTML_POST@</div> + </div> + </div> + <div style="clear: left;"></div> + <div class="overview"> + <h3>Small print</h3><div class="smallprint"> + <p> + 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, <code>@UtilityClass</code> cannot be used. + </p> + </div> + </div> + <div class="footer"> + <a href="index.html">Back to experimental features</a> | <a href="onX.html">Previous feature (onX)</a> | <span class="disabled">Next feature</span><br /> + <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> + </div> + <div style="clear: both;"></div> + </div> +</div> +<script type="text/javascript"> + var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); + document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); +</script> +<script type="text/javascript"> + try { + var pageTracker = _gat._getTracker("UA-9884254-1"); + pageTracker._trackPageview(); + } catch(err) {} +</script> +</body></html> 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 @@ <dd>Immutable 'setters' - methods that create a clone but with one changed field.</dd> <dt><a href="onX.html"><code>onMethod= / onConstructor= / onParam=</code></a></dt> <dd>Sup dawg, we heard you like annotations, so we put annotations in your annotations so you can annotate while you're annotating.</dd> + <dt><a href="UtilityClass.html"><code>@UtilityClass</code></a></dt> + <dd>Utility, metility, wetility! Utility classes for the masses.</dd> </dl> </div> <div class="overview confKeys"> 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 @@ </div> </div> <div class="footer"> - <a href="index.html">Back to experimental features</a> | <a href="Wither.html">Previous feature (@Wither)</a> | <span class="disabled">Next feature</span><br /> + <a href="index.html">Back to experimental features</a> | <a href="Wither.html">Previous feature (@Wither)</a> | <a href="UtilityClass.html">Next feature (@UtilityClass)</a><br /> <a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright © 2009-2015 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span> </div> <div style="clear: both;"></div> |