diff options
| -rw-r--r-- | src/lombok/javac/HandlerLibrary.java | 104 | ||||
| -rw-r--r-- | src/lombok/javac/Javac.java | 41 | ||||
| -rw-r--r-- | src/lombok/javac/JavacAnnotationHandler.java | 47 | ||||
| -rw-r--r-- | src/lombok/javac/apt/Processor.java | 31 |
4 files changed, 203 insertions, 20 deletions
diff --git a/src/lombok/javac/HandlerLibrary.java b/src/lombok/javac/HandlerLibrary.java index 20cfed21..f73b9930 100644 --- a/src/lombok/javac/HandlerLibrary.java +++ b/src/lombok/javac/HandlerLibrary.java @@ -1,3 +1,24 @@ +/* + * Copyright © 2009 Reinier Zwitserloot and Roel Spilker. + * + * 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.javac; import java.lang.annotation.Annotation; @@ -10,7 +31,6 @@ import java.util.ServiceConfigurationError; import java.util.ServiceLoader; import javax.annotation.processing.Messager; -import javax.lang.model.element.TypeElement; import javax.tools.Diagnostic; import lombok.core.PrintAST; @@ -22,7 +42,12 @@ import lombok.core.AnnotationValues.AnnotationValueDecodeFail; import com.sun.tools.javac.tree.JCTree.JCAnnotation; import com.sun.tools.javac.tree.JCTree.JCCompilationUnit; - +/** + * This class tracks 'handlers' and knows how to invoke them for any given AST node. + * + * This class can find the handlers (via SPI discovery) and will set up the given AST node, such as + * building an AnnotationValues instance. + */ public class HandlerLibrary { private final TypeLibrary typeLibrary = new TypeLibrary(); private final Map<String, AnnotationHandlerContainer<?>> annotationHandlers = new HashMap<String, AnnotationHandlerContainer<?>>(); @@ -30,6 +55,10 @@ public class HandlerLibrary { private final Messager messager; private boolean skipPrintAST = true; + /** + * Creates a new HandlerLibrary that will report any problems or errors to the provided messager. + * You probably want to use {@link #load(Messager)} instead. + */ public HandlerLibrary(Messager messager) { this.messager = messager; } @@ -48,6 +77,11 @@ public class HandlerLibrary { } } + /** + * Creates a new HandlerLibrary that will report any problems or errors to the provided messager, + * then uses SPI discovery to load all annotation and visitor based handlers so that future calls + * to the handle methods will defer to these handlers. + */ public static HandlerLibrary load(Messager messager) { HandlerLibrary library = new HandlerLibrary(messager); @@ -57,6 +91,7 @@ public class HandlerLibrary { return library; } + /** Uses SPI Discovery to find implementations of {@link JavacAnnotationHandler}. */ @SuppressWarnings("unchecked") private static void loadAnnotationHandlers(HandlerLibrary lib) { //No, that seemingly superfluous reference to JavacAnnotationHandler's classloader is not in fact superfluous! @@ -78,36 +113,58 @@ public class HandlerLibrary { } } + /** Uses SPI Discovery to find implementations of {@link JavacASTVisitor}. */ + private static void loadVisitorHandlers(HandlerLibrary lib) { + //No, that seemingly superfluous reference to JavacASTVisitor's classloader is not in fact superfluous! + Iterator<JavacASTVisitor> it = ServiceLoader.load(JavacASTVisitor.class, + JavacASTVisitor.class.getClassLoader()).iterator(); + while ( it.hasNext() ) { + try { + JavacASTVisitor handler = it.next(); + lib.visitorHandlers.add(handler); + } catch ( ServiceConfigurationError e ) { + lib.javacWarning("Can't load Lombok visitor handler for javac", e); + } + } + } + + /** Generates a warning in the Messager that was used to initialize this HandlerLibrary. */ public void javacWarning(String message) { javacWarning(message, null); } + /** Generates a warning in the Messager that was used to initialize this HandlerLibrary. */ public void javacWarning(String message, Throwable t) { messager.printMessage(Diagnostic.Kind.WARNING, message + (t == null ? "" : (": " + t))); } + /** Generates an error in the Messager that was used to initialize this HandlerLibrary. */ public void javacError(String message) { javacWarning(message, null); } + /** Generates an error in the Messager that was used to initialize this HandlerLibrary. */ public void javacError(String message, Throwable t) { messager.printMessage(Diagnostic.Kind.ERROR, message + (t == null ? "" : (": " + t))); } - private static void loadVisitorHandlers(HandlerLibrary lib) { - //No, that seemingly superfluous reference to JavacASTVisitor's classloader is not in fact superfluous! - Iterator<JavacASTVisitor> it = ServiceLoader.load(JavacASTVisitor.class, - JavacASTVisitor.class.getClassLoader()).iterator(); - while ( it.hasNext() ) { - try { - JavacASTVisitor handler = it.next(); - lib.visitorHandlers.add(handler); - } catch ( ServiceConfigurationError e ) { - lib.javacWarning("Can't load Lombok visitor handler for javac", e); - } - } - } - + /** + * Handles the provided annotation node by first finding a qualifying instance of + * {@link JavacAnnotationHandler} and if one exists, calling it with a freshly cooked up + * instance of {@link AnnotationValues}. + * + * Note that depending on the printASTOnly flag, the {@link lombok.core.PrintAST} annotation + * will either be silently skipped, or everything that isn't <code>PrintAST</code> will be skipped. + * + * The HandlerLibrary will attempt to guess if the given annotation node represents a lombok annotation. + * For example, if <code>lombok.*</code> is in the import list, then this method will guess that + * <code>Getter</code> refers to <code>lombok.Getter</code>, presuming that {@link lombok.javac.handlers.HandleGetter} + * has been loaded. + * + * @param unit The Compilation Unit that contains the Annotation AST Node. + * @param node The Lombok AST Node representing the Annotation AST Node. + * @param annotation 'node.get()' - convenience parameter. + */ public boolean handleAnnotation(JCCompilationUnit unit, JavacAST.Node node, JCAnnotation annotation) { TypeResolver resolver = new TypeResolver(typeLibrary, node.getPackageDeclaration(), node.getImportStatements()); String rawType = annotation.annotationType.toString(); @@ -130,6 +187,9 @@ public class HandlerLibrary { return handled; } + /** + * Will call all registered {@link JavacASTVisitor} instances. + */ public void callASTVisitors(JavacAST ast) { for ( JavacASTVisitor visitor : visitorHandlers ) try { ast.traverse(visitor); @@ -138,14 +198,18 @@ public class HandlerLibrary { } } - public boolean hasHandlerFor(TypeElement annotationType) { - return annotationHandlers.containsKey(annotationType.getQualifiedName().toString()); - } - + /** + * Lombok does not currently support triggering annotations in a specified order; the order is essentially + * random right now. This lack of order is particularly annoying for the <code>PrintAST</code> annotation, + * which is almost always intended to run last. Hence, this hack, which lets it in fact run last. + * + * {@see #skipAllButPrintAST} + */ public void skipPrintAST() { skipPrintAST = true; } + /** {@see #skipPrintAST} */ public void skipAllButPrintAST() { skipPrintAST = false; } diff --git a/src/lombok/javac/Javac.java b/src/lombok/javac/Javac.java index 90448e26..f80cca96 100644 --- a/src/lombok/javac/Javac.java +++ b/src/lombok/javac/Javac.java @@ -1,3 +1,24 @@ +/* + * Copyright © 2009 Reinier Zwitserloot and Roel Spilker. + * + * 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.javac; import java.lang.annotation.Annotation; @@ -25,11 +46,20 @@ import com.sun.tools.javac.tree.JCTree.JCLiteral; import com.sun.tools.javac.tree.JCTree.JCNewArray; import com.sun.tools.javac.util.JCDiagnostic.DiagnosticPosition; +/** + * Container for static utility methods relevant to lombok's operation on javac. + */ public class Javac { private Javac() { //prevent instantiation } + /** + * Checks if the Annotation AST Node provided is likely to be an instance of the provided annotation type. + * + * @param type An actual annotation type, such as <code>lombok.Getter.class</code>. + * @param node A Lombok AST node representing an annotation in source code. + */ public static boolean annotationTypeMatches(Class<? extends Annotation> type, Node node) { if ( node.getKind() != Kind.ANNOTATION ) return false; String typeName = ((JCAnnotation)node.get()).annotationType.toString(); @@ -46,6 +76,12 @@ public class Javac { return false; } + /** + * Creates an instance of <code>AnnotationValues</code> for the provided AST Node. + * + * @param type An annotation class type, such as <code>lombok.Getter.class</code>. + * @param node A Lombok AST node representing an annotation in source code. + */ public static <A extends Annotation> AnnotationValues<A> createAnnotation(Class<A> type, final Node node) { Map<String, AnnotationValue> values = new HashMap<String, AnnotationValue>(); JCAnnotation anno = (JCAnnotation) node.get(); @@ -86,6 +122,11 @@ public class Javac { return new AnnotationValues<A>(type, values, node); } + /** + * Turns an expression into a guessed intended literal. Only works for literals, as you can imagine. + * + * Will for example turn a TrueLiteral into 'Boolean.valueOf(true)'. + */ private static Object calculateGuess(JCExpression expr) { if ( expr instanceof JCLiteral ) { JCLiteral lit = (JCLiteral)expr; diff --git a/src/lombok/javac/JavacAnnotationHandler.java b/src/lombok/javac/JavacAnnotationHandler.java index 58308de1..65832eab 100644 --- a/src/lombok/javac/JavacAnnotationHandler.java +++ b/src/lombok/javac/JavacAnnotationHandler.java @@ -1,3 +1,24 @@ +/* + * Copyright © 2009 Reinier Zwitserloot and Roel Spilker. + * + * 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.javac; import java.lang.annotation.Annotation; @@ -6,6 +27,32 @@ import lombok.core.AnnotationValues; import com.sun.tools.javac.tree.JCTree.JCAnnotation; +/** + * Implement this interface if you want to be triggered for a specific annotation. + * + * You MUST replace 'T' with a specific annotation type, such as: + * + * <code>public class HandleGetter implements JavacAnnotationHandler<<b>Getter</b>></code> + * + * Because this generics parameter is inspected to figure out which class you're interested in. + * + * You also need to register yourself via SPI discovery as being an implementation of <code>JavacAnnotationHandler</code>. + */ public interface JavacAnnotationHandler<T extends Annotation> { + /** + * Called when an annotation is found that is likely to match the annotation you're interested in. + * + * Be aware that you'll be called for ANY annotation node in the source that looks like a match. There is, + * for example, no guarantee that the annotation node belongs to a method, even if you set your + * TargetType in the annotation to methods only. + * + * @param annotation The actual annotation - use this object to retrieve the annotation parameters. + * @param ast The javac AST node representing the annotation. + * @param annotationNode The Lombok AST wrapper around the 'ast' parameter. You can use this object + * to travel back up the chain (something javac AST can't do) to the parent of the annotation, as well + * as access useful methods such as generating warnings or errors focussed on the annotation. + * @return <code>true</code> if you don't want to be called again about this annotation during this + * compile session (you've handled it), or <code>false</code> to indicate you aren't done yet. + */ boolean handle(AnnotationValues<T> annotation, JCAnnotation ast, JavacAST.Node annotationNode); } diff --git a/src/lombok/javac/apt/Processor.java b/src/lombok/javac/apt/Processor.java index 52b3703a..7bffd33e 100644 --- a/src/lombok/javac/apt/Processor.java +++ b/src/lombok/javac/apt/Processor.java @@ -1,3 +1,24 @@ +/* + * Copyright © 2009 Reinier Zwitserloot and Roel Spilker. + * + * 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.javac.apt; import java.util.ArrayList; @@ -28,6 +49,16 @@ import com.sun.tools.javac.tree.JCTree.JCMethodDecl; import com.sun.tools.javac.tree.JCTree.JCVariableDecl; +/** + * This Annotation Processor is the standard injection mechanism for lombok-enabling the javac compiler. + * + * Due to lots of changes in the core javac code, as well as lombok's heavy usage of non-public API, this + * code only works for the javac v1.6 compiler; it definitely won't work for javac v1.5, and it probably + * won't work for javac v1.7 without modifications. + * + * To actually enable lombok in a javac compilation run, this class should be in the classpath when + * running javac; that's the only requirement. + */ @SupportedAnnotationTypes("*") @SupportedSourceVersion(SourceVersion.RELEASE_6) public class Processor extends AbstractProcessor { |