View Javadoc
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   */
25  
26  package com.sun.xml.internal.bind.v2.model.nav;
27  
28  import java.lang.reflect.Field;
29  import java.lang.reflect.Method;
30  import java.lang.reflect.Proxy;
31  import java.lang.reflect.Type;
32  import java.util.Collection;
33  
34  import com.sun.xml.internal.bind.v2.runtime.Location;
35  
36  /**
37   * Provides unified view of the underlying reflection library,
38   * such as {@code java.lang.reflect} and/or Annotation Processing.
39   *
40   * <p>
41   * This interface provides navigation over the reflection model
42   * to decouple the caller from any particular implementation.
43   * This allows the JAXB RI to reuse much of the code between
44   * the compile time (which works on top of Annotation Processing) and the run-time
45   * (which works on top of {@code java.lang.reflect})
46   *
47   * <p>
48   * {@link Navigator} instances are stateless and immutable.
49   *
50   *
51   * <h2>Parameterization</h2>
52   * <h3>C</h3>
53   * <p>
54   * A Java class declaration (not an interface, a class and an enum.)
55   *
56   * <h3>T</h3>
57   * <p>
58   * A Java type. This includs declaration, but also includes such
59   * things like arrays, primitive types, parameterized types, and etc.
60   *
61   * @author Kohsuke Kawaguchi (kk@kohsuke.org)
62   */
63  public interface Navigator<T,C,F,M> {
64      /**
65       * Gets the base class of the specified class.
66       *
67       * @return
68       *      null if the parameter represents {@link Object}.
69       */
70      C getSuperClass(C clazz);
71  
72      /**
73       * Gets the parameterization of the given base type.
74       *
75       * <p>
76       * For example, given the following
77       * <pre><xmp>
78       * interface Foo<T> extends List<List<T>> {}
79       * interface Bar extends Foo<String> {}
80       * </xmp></pre>
81       * This method works like this:
82       * <pre><xmp>
83       * getBaseClass( Bar, List ) = List<List<String>
84       * getBaseClass( Bar, Foo  ) = Foo<String>
85       * getBaseClass( Foo<? extends Number>, Collection ) = Collection<List<? extends Number>>
86       * getBaseClass( ArrayList<? extends BigInteger>, List ) = List<? extends BigInteger>
87       * </xmp></pre>
88       *
89       * @param type
90       *      The type that derives from {@code baseType}
91       * @param baseType
92       *      The class whose parameterization we are interested in.
93       * @return
94       *      The use of {@code baseType} in {@code type}.
95       *      or null if the type is not assignable to the base type.
96       */
97      T getBaseClass(T type, C baseType);
98  
99      /**
100      * Gets the fully-qualified name of the class.
101      * ("java.lang.Object" for {@link Object})
102      */
103     String getClassName(C clazz);
104 
105     /**
106      * Gets the display name of the type object
107      *
108      * @return
109      *      a human-readable name that the type represents.
110      */
111     String getTypeName(T rawType);
112 
113     /**
114      * Gets the short name of the class ("Object" for {@link Object}.)
115      *
116      * For nested classes, this method should just return the inner name.
117      * (for example "Inner" for "com.acme.Outer$Inner".
118      */
119     String getClassShortName(C clazz);
120 
121     /**
122      * Gets all the declared fields of the given class.
123      */
124     Collection<? extends F> getDeclaredFields(C clazz);
125 
126     /**
127      * Gets the named field declared on the given class.
128      *
129      * This method doesn't visit ancestors, but does recognize
130      * non-public fields.
131      *
132      * @return
133      *      null if not found
134      */
135     F getDeclaredField(C clazz, String fieldName);
136 
137     /**
138      * Gets all the declared methods of the given class
139      * (regardless of their access modifiers, regardless
140      * of whether they override methods of the base classes.)
141      *
142      * <p>
143      * Note that this method does not list methods declared on base classes.
144      *
145      * @return
146      *      can be empty but always non-null.
147      */
148     Collection<? extends M> getDeclaredMethods(C clazz);
149 
150     /**
151      * Gets the class that declares the given field.
152      */
153     C getDeclaringClassForField(F field);
154 
155     /**
156      * Gets the class that declares the given method.
157      */
158     C getDeclaringClassForMethod(M method);
159 
160     /**
161      * Gets the type of the field.
162      */
163     T getFieldType(F f);
164 
165     /**
166      * Gets the name of the field.
167      */
168     String getFieldName(F field);
169 
170     /**
171      * Gets the name of the method, such as "toString" or "equals".
172      */
173     String getMethodName(M m);
174 
175     /**
176      * Gets the return type of a method.
177      */
178     T getReturnType(M m);
179 
180     /**
181      * Returns the list of parameters to the method.
182      */
183     T[] getMethodParameters(M method);
184 
185     /**
186      * Returns true if the method is static.
187      */
188     boolean isStaticMethod(M method);
189 
190     /**
191      * Checks if {@code sub} is a sub-type of {@code sup}.
192      *
193      * TODO: should this method take T or C?
194      */
195     boolean isSubClassOf(T sub, T sup);
196 
197     /**
198      * Gets the representation of the given Java type in {@code T}.
199      *
200      * @param c
201      *      can be a primitive, array, class, or anything.
202      *      (therefore the return type has to be T, not C)
203      */
204     T ref(Class c);
205 
206     /**
207      * Gets the T for the given C.
208      */
209     T use(C c);
210 
211     /**
212      * If the given type is an use of class declaration,
213      * returns the type casted as {@code C}.
214      * Otherwise null.
215      *
216      * <p>
217      * TODO: define the exact semantics.
218      */
219     C asDecl(T type);
220 
221     /**
222      * Gets the {@code C} representation for the given class.
223      *
224      * The behavior is undefined if the class object represents
225      * primitives, arrays, and other types that are not class declaration.
226      */
227     C asDecl(Class c);
228 
229     /**
230      * Checks if the type is an array type.
231      */
232     boolean isArray(T t);
233 
234     /**
235      * Checks if the type is an array type but not byte[].
236      */
237     boolean isArrayButNotByteArray(T t);
238 
239     /**
240      * Gets the component type of the array.
241      *
242      * @param t
243      *      must be an array.
244      */
245     T getComponentType(T t);
246 
247     /**
248      * Gets the i-th type argument from a parameterized type.
249      *
250      * For example, {@code getTypeArgument([Map<Integer,String>],0)=Integer}
251      *
252      * @throws IllegalArgumentException
253      *      If t is not a parameterized type
254      * @throws IndexOutOfBoundsException
255      *      If i is out of range.
256      *
257      * @see #isParameterizedType(Object)
258      */
259     T getTypeArgument(T t, int i);
260 
261     /**
262      * Returns true if t is a parameterized type.
263      */
264     boolean isParameterizedType(T t);
265 
266     /**
267      * Checks if the given type is a primitive type.
268      */
269     boolean isPrimitive(T t);
270 
271     /**
272      * Returns the representation for the given primitive type.
273      *
274      * @param primitiveType
275      *      must be Class objects like {@link Integer#TYPE}.
276      */
277     T getPrimitive(Class primitiveType);
278 
279     /**
280      * Returns a location of the specified class.
281      */
282     Location getClassLocation(C clazz);
283 
284     Location getFieldLocation(F field);
285 
286     Location getMethodLocation(M getter);
287 
288     /**
289      * Returns true if the given class has a no-arg default constructor.
290      * The constructor does not need to be public.
291      */
292     boolean hasDefaultConstructor(C clazz);
293 
294     /**
295      * Returns true if the field is static.
296      */
297     boolean isStaticField(F field);
298 
299     /**
300      * Returns true if the method is public.
301      */
302     boolean isPublicMethod(M method);
303 
304     /**
305      * Returns true if the method is final.
306      */
307     boolean isFinalMethod(M method);
308 
309     /**
310      * Returns true if the field is public.
311      */
312     boolean isPublicField(F field);
313 
314     /**
315      * Returns true if this is an enum class.
316      */
317     boolean isEnum(C clazz);
318 
319     /**
320      * Computes the erasure
321      */
322     <P> T erasure(T contentInMemoryType);
323     // This unused P is necessary to make ReflectionNavigator.erasure work nicely
324 
325     /**
326      * Returns true if this is an abstract class.
327      */
328     boolean isAbstract(C clazz);
329 
330     /**
331      * Returns true if this is a final class.
332      */
333     boolean isFinal(C clazz);
334 
335     /**
336      * Gets the enumeration constants from an enum class.
337      *
338      * @param clazz
339      *      must derive from {@link Enum}.
340      *
341      * @return
342      *      can be empty but never null.
343      */
344     F[] getEnumConstants(C clazz);
345 
346     /**
347      * Gets the representation of the primitive "void" type.
348      */
349     T getVoidType();
350 
351     /**
352      * Gets the package name of the given class.
353      *
354      * @return
355      *      i.e. "", "java.lang" but not null.
356      */
357     String getPackageName(C clazz);
358 
359     /**
360      * Finds ObjectFactory for the given referencePoint.
361      *
362      * @param referencePoint
363      *      The class that refers to the specified class.
364      * @return
365      *      null if not found.
366      */
367     C loadObjectFactory(C referencePoint, String packageName);
368 
369     /**
370      * Returns true if this method is a bridge method as defined in JLS.
371      */
372     boolean isBridgeMethod(M method);
373 
374     /**
375      * Returns true if the given method is overriding another one
376      * defined in the base class 'base' or its ancestors.
377      */
378     boolean isOverriding(M method, C base);
379 
380     /**
381      * Returns true if 'clazz' is an interface.
382      */
383     boolean isInterface(C clazz);
384 
385     /**
386      * Returns true if the field is transient.
387      */
388     boolean isTransient(F f);
389 
390     /**
391      * Returns true if the given class is an inner class.
392      *
393      * This is only used to improve the error diagnostics, so
394      * it's OK to fail to detect some inner classes as such.
395      *
396      * Note that this method should return false for nested classes
397      * (static classes.)
398      */
399     boolean isInnerClass(C clazz);
400 
401     /**
402      * Checks if types are the same
403      * @param t1 type
404      * @param t2 type
405      * @return true if types are the same
406      */
407     boolean isSameType(T t1, T t2);
408 }