001: /*
002: * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.xml.internal.bind.v2.model.annotation;
027:
028: import java.lang.annotation.Annotation;
029: import java.lang.reflect.Field;
030: import java.lang.reflect.Method;
031:
032: import com.sun.xml.internal.bind.v2.model.core.ErrorHandler;
033:
034: /**
035: * Reads annotations for the given property.
036: *
037: * <p>
038: * This is the lowest abstraction that encapsulates the difference
039: * between reading inline annotations and external binding files.
040: *
041: * <p>
042: * Because the former operates on a {@link Field} and {@link Method}
043: * while the latter operates on a "property", the methods defined
044: * on this interface takes both, and the callee gets to choose which
045: * to use.
046: *
047: * <p>
048: * Most of the get method takes {@link Locatable}, which points to
049: * the place/context in which the annotation is read. The returned
050: * annotation also implements {@link Locatable} (so that it can
051: * point to the place where the annotation is placed), and its
052: * {@link Locatable#getUpstream()} will return the given
053: * {@link Locatable}.
054: *
055: *
056: * <p>
057: * Errors found during reading annotations are reported through the error handler.
058: * A valid {@link ErrorHandler} must be registered before the {@link AnnotationReader}
059: * is used.
060: *
061: * @author Kohsuke Kawaguchi (kk@kohsuke.org)
062: */
063: public interface AnnotationReader<T, C, F, M> {
064:
065: /**
066: * Sets the error handler that receives errors found
067: * during reading annotations.
068: *
069: * @param errorHandler
070: * must not be null.
071: */
072: void setErrorHandler(ErrorHandler errorHandler);
073:
074: /**
075: * Reads an annotation on a property that consists of a field.
076: */
077: <A extends Annotation> A getFieldAnnotation(Class<A> annotation,
078: F field, Locatable srcpos);
079:
080: /**
081: * Checks if the given field has an annotation.
082: */
083: boolean hasFieldAnnotation(
084: Class<? extends Annotation> annotationType, F field);
085:
086: /**
087: * Gets all the annotations on a field.
088: */
089: Annotation[] getAllFieldAnnotations(F field, Locatable srcPos);
090:
091: /**
092: * Reads an annotation on a property that consists of a getter and a setter.
093: *
094: */
095: <A extends Annotation> A getMethodAnnotation(Class<A> annotation,
096: M getter, M setter, Locatable srcpos);
097:
098: /**
099: * Checks if the given method has an annotation.
100: */
101: boolean hasMethodAnnotation(Class<? extends Annotation> annotation,
102: String propertyName, M getter, M setter, Locatable srcPos);
103:
104: /**
105: * Gets all the annotations on a method.
106: *
107: * @param srcPos
108: * the location from which this annotation is read.
109: */
110: Annotation[] getAllMethodAnnotations(M method, Locatable srcPos);
111:
112: // TODO: we do need this to read certain annotations,
113: // but that shows inconsistency wrt the spec. consult the spec team about the abstraction.
114: <A extends Annotation> A getMethodAnnotation(Class<A> annotation,
115: M method, Locatable srcpos);
116:
117: boolean hasMethodAnnotation(Class<? extends Annotation> annotation,
118: M method);
119:
120: /**
121: * Reads an annotation on a parameter of the method.
122: *
123: * @return null
124: * if the annotation was not found.
125: */
126: <A extends Annotation> A getMethodParameterAnnotation(
127: Class<A> annotation, M method, int paramIndex,
128: Locatable srcPos);
129:
130: /**
131: * Reads an annotation on a class.
132: */
133: <A extends Annotation> A getClassAnnotation(Class<A> annotation,
134: C clazz, Locatable srcpos);
135:
136: /**
137: * Reads an annotation on the package that the given class belongs to.
138: */
139: <A extends Annotation> A getPackageAnnotation(Class<A> annotation,
140: C clazz, Locatable srcpos);
141:
142: /**
143: * Reads a value of an annotation that returns a Class object.
144: *
145: * <p>
146: * Depending on the underlying reflection library, you can't always
147: * obtain the {@link Class} object directly (see the APT MirrorTypeException
148: * for example), so use this method to avoid that.
149: *
150: * @param name
151: * The name of the annotation parameter to be read.
152: */
153: T getClassValue(Annotation a, String name);
154: }
|