Thu, 12 Oct 2017 19:44:07 +0800
merge
1 /*
2 * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
26 package com.sun.xml.internal.bind.v2.model.annotation;
28 import java.lang.annotation.Annotation;
29 import java.lang.reflect.Field;
30 import java.lang.reflect.Method;
32 import com.sun.istack.internal.Nullable;
33 import com.sun.xml.internal.bind.v2.model.core.ErrorHandler;
35 /**
36 * Reads annotations for the given property.
37 *
38 * <p>
39 * This is the lowest abstraction that encapsulates the difference
40 * between reading inline annotations and external binding files.
41 *
42 * <p>
43 * Because the former operates on a {@link Field} and {@link Method}
44 * while the latter operates on a "property", the methods defined
45 * on this interface takes both, and the callee gets to choose which
46 * to use.
47 *
48 * <p>
49 * Most of the get method takes {@link Locatable}, which points to
50 * the place/context in which the annotation is read. The returned
51 * annotation also implements {@link Locatable} (so that it can
52 * point to the place where the annotation is placed), and its
53 * {@link Locatable#getUpstream()} will return the given
54 * {@link Locatable}.
55 *
56 *
57 * <p>
58 * Errors found during reading annotations are reported through the error handler.
59 * A valid {@link ErrorHandler} must be registered before the {@link AnnotationReader}
60 * is used.
61 *
62 * @author Kohsuke Kawaguchi (kk@kohsuke.org)
63 */
64 public interface AnnotationReader<T,C,F,M> {
66 /**
67 * Sets the error handler that receives errors found
68 * during reading annotations.
69 *
70 * @param errorHandler
71 * must not be null.
72 */
73 void setErrorHandler(ErrorHandler errorHandler);
75 /**
76 * Reads an annotation on a property that consists of a field.
77 */
78 <A extends Annotation> A getFieldAnnotation(Class<A> annotation,
79 F field, Locatable srcpos);
81 /**
82 * Checks if the given field has an annotation.
83 */
84 boolean hasFieldAnnotation(Class<? extends Annotation> annotationType, F field);
86 /**
87 * Checks if a class has the annotation.
88 */
89 boolean hasClassAnnotation(C clazz, Class<? extends Annotation> annotationType);
91 /**
92 * Gets all the annotations on a field.
93 */
94 Annotation[] getAllFieldAnnotations(F field, Locatable srcPos);
96 /**
97 * Reads an annotation on a property that consists of a getter and a setter.
98 *
99 */
100 <A extends Annotation> A getMethodAnnotation(Class<A> annotation,
101 M getter, M setter, Locatable srcpos);
103 /**
104 * Checks if the given method has an annotation.
105 */
106 boolean hasMethodAnnotation(Class<? extends Annotation> annotation, String propertyName, M getter, M setter, Locatable srcPos);
108 /**
109 * Gets all the annotations on a method.
110 *
111 * @param srcPos
112 * the location from which this annotation is read.
113 */
114 Annotation[] getAllMethodAnnotations(M method, Locatable srcPos);
116 // TODO: we do need this to read certain annotations,
117 // but that shows inconsistency wrt the spec. consult the spec team about the abstraction.
118 <A extends Annotation> A getMethodAnnotation(Class<A> annotation, M method, Locatable srcpos );
120 boolean hasMethodAnnotation(Class<? extends Annotation> annotation, M method );
122 /**
123 * Reads an annotation on a parameter of the method.
124 *
125 * @return null
126 * if the annotation was not found.
127 */
128 @Nullable
129 <A extends Annotation> A getMethodParameterAnnotation(
130 Class<A> annotation, M method, int paramIndex, Locatable srcPos );
132 /**
133 * Reads an annotation on a class.
134 */
135 @Nullable
136 <A extends Annotation> A getClassAnnotation(Class<A> annotation, C clazz, Locatable srcpos) ;
138 /**
139 * Reads an annotation on the package that the given class belongs to.
140 */
141 @Nullable
142 <A extends Annotation> A getPackageAnnotation(Class<A> annotation, C clazz, Locatable srcpos);
144 /**
145 * Reads a value of an annotation that returns a Class object.
146 *
147 * <p>
148 * Depending on the underlying reflection library, you can't always
149 * obtain the {@link Class} object directly (see the Annotation Processing MirrorTypeException
150 * for example), so use this method to avoid that.
151 *
152 * @param name
153 * The name of the annotation parameter to be read.
154 */
155 T getClassValue( Annotation a, String name );
157 /**
158 * Similar to {@link #getClassValue(Annotation, String)} method but
159 * obtains an array parameter.
160 */
161 T[] getClassArrayValue( Annotation a, String name );
162 }