From 527b992a074c1c65727bc52c820d40340f074a6b Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Mon, 6 Jul 2009 05:48:42 +0200 Subject: Last massive documentation dump. All basic javadoc is now done, though especially the docs on the lombok annotations in the lombok package need far more massaging. Also added a feature to HandleSynchronized to not auto-generate the locker fields if a specific name is provided (because, imagine you typoed those. You'd never find it!) --- src/lombok/core/AnnotationValues.java | 95 ++++++++++++++++++++++++++++++++--- 1 file changed, 87 insertions(+), 8 deletions(-) (limited to 'src/lombok/core/AnnotationValues.java') diff --git a/src/lombok/core/AnnotationValues.java b/src/lombok/core/AnnotationValues.java index 432d507f..ee434f1f 100644 --- a/src/lombok/core/AnnotationValues.java +++ b/src/lombok/core/AnnotationValues.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.core; import java.lang.annotation.Annotation; @@ -10,13 +31,23 @@ import java.util.Collections; import java.util.List; import java.util.Map; +/** + * Represents a single annotation in a source file and can be used to query the parameters present on it. + */ public class AnnotationValues { private final Class type; private final Map values; private final AST.Node ast; - + + /** + * Represents a single method on the annotation class. For example, the value() method on the Getter annotation. + */ public static class AnnotationValue { + /** A list of the raw expressions. List is size 1 unless an array is provided. */ public final List raws; + + /** Guesses for each raw expression. If the raw expression is a literal expression, the guess will + * likely be right. If not, it'll be wrong. */ public final List valueGuesses; private final AST.Node node; @@ -33,7 +64,9 @@ public class AnnotationValues { this.valueGuesses = Collections.singletonList(valueGuess); } - /** When the value is an array type. */ + /** + * Like the other constructor, but used for when the annotation method is initialized with an array value. + */ public AnnotationValue(AST.Node node, List raws, List valueGuesses) { this.node = node; this.raws = raws; @@ -52,21 +85,39 @@ public class AnnotationValues { node.addError(message); } + /** {@inheritDoc} */ @Override public String toString() { return "raws: " + raws + " valueGuesses: " + valueGuesses; } } + /** + * Creates a new AnnotationValues. + * + * @param type The annotation type. For example, "Getter.class" + * @param values a Map of method names to AnnotationValue instances, for example 'value -> annotationValue instance'. + * @param ast The Annotation node. + */ public AnnotationValues(Class type, Map values, AST.Node ast) { this.type = type; this.values = values; this.ast = ast; } + /** + * Thrown on the fly if an actual annotation instance procured via the {@link #getInstance()} method is queried + * for a method for which this AnnotationValues instance either doesn't have a guess or can't manage to fit + * the guess into the required data type. + */ public static class AnnotationValueDecodeFail extends RuntimeException { private static final long serialVersionUID = 1L; + /** The index into an array initializer (e.g. if the second value in an array initializer is + * an integer constant expression like '5+SomeOtherClass.CONSTANT', this exception will be thrown, + * and you'll get a '1' for idx. */ public final int idx; + + /** The AnnotationValue object that goes with the annotation method for which the failure occurred. */ public final AnnotationValue owner; public AnnotationValueDecodeFail(AnnotationValue owner, String msg, int idx) { @@ -83,8 +134,15 @@ public class AnnotationValues { private A cachedInstance = null; + /** + * Creates an actual annotation instance. You can use this to query any annotation methods, except for + * those annotation methods with class literals, as those can most likely not be turned into Class objects. + * + * If some of the methods cannot be implemented, this method still works; it's only when you call a method + * that has a problematic value that an AnnotationValueDecodeFail exception occurs. + */ @SuppressWarnings("unchecked") - public A getInstance() throws AnnotationValueDecodeFail { + public A getInstance() { if ( cachedInstance != null ) return cachedInstance; InvocationHandler invocations = new InvocationHandler() { public Object invoke(Object proxy, Method method, Object[] args) throws Throwable { @@ -217,16 +275,32 @@ public class AnnotationValues { "Can't translate a " + guess.getClass() + " to the expected " + expected, pos); } + /** + * Returns the raw expressions used for the provided annotationMethodName. + * + * You should use this method for annotation methods that return Class objects. Remember that + * class literals end in ".class" which you probably want to strip off. + */ public List getRawExpressions(String annotationMethodName) { AnnotationValue v = values.get(annotationMethodName); return v == null ? Collections.emptyList() : v.raws; } + /** + * Convenience method to return the first result in a {@link getRawExpressions(String)} call. + * + * You should use this method if the annotation method is not an array type. + */ public String getRawExpression(String annotationMethodName) { List l = getRawExpressions(annotationMethodName); return l.isEmpty() ? null : l.get(0); } + /** + * Attempts to translate class literals to their fully qualified names, such as 'Throwable.class' to 'java.lang.Throwable'. + * + * This process is at best a guess, but it will take into account import statements. + */ public List getProbableFQTypes(String annotationMethodName) { List result = new ArrayList(); AnnotationValue v = values.get(annotationMethodName); @@ -236,6 +310,16 @@ public class AnnotationValues { return result; } + /** + * Convenience method to return the first result in a {@link getProbableFQType(String)} call. + * + * You should use this method if the annotation method is not an array type. + */ + public String getProbableFQType(String annotationMethodName) { + List l = getProbableFQTypes(annotationMethodName); + return l.isEmpty() ? null : l.get(0); + } + private String toFQ(String typeName) { Class c; boolean fqn = typeName.indexOf('.') > -1; @@ -279,9 +363,4 @@ public class AnnotationValues { return null; } } - - public String getProbableFQType(String annotationMethodName) { - List l = getProbableFQTypes(annotationMethodName); - return l.isEmpty() ? null : l.get(0); - } } -- cgit