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.nav;
027:
028: import java.util.Collection;
029:
030: import com.sun.xml.internal.bind.v2.runtime.Location;
031:
032: /**
033: * Provides unified view of the underlying reflection library,
034: * such as {@code java.lang.reflect} and/or APT.
035: *
036: * <p>
037: * This interface provides navigation over the reflection model
038: * to decouple the caller from any particular implementation.
039: * This allows the JAXB RI to reuse much of the code between
040: * the compile time (which works on top of APT) and the run-time
041: * (which works on top of {@code java.lang.reflect})
042: *
043: * <p>
044: * {@link Navigator} instances are stateless and immutable.
045: *
046: *
047: * <h2>Parameterization</h2>
048: * <h3>C</h3>
049: * <p>
050: * A Java class declaration (not an interface, a class and an enum.)
051: *
052: * <h3>T</h3>
053: * <p>
054: * A Java type. This includs declaration, but also includes such
055: * things like arrays, primitive types, parameterized types, and etc.
056: *
057: * @author Kohsuke Kawaguchi (kk@kohsuke.org)
058: */
059: public interface Navigator<T, C, F, M> {
060: /**
061: * Gets the base class of the specified class.
062: *
063: * @return
064: * null if the parameter represents {@link Object}.
065: */
066: C getSuperClass(C clazz);
067:
068: /**
069: * Gets the parameterization of the given base type.
070: *
071: * <p>
072: * For example, given the following
073: * <pre><xmp>
074: * interface Foo<T> extends List<List<T>> {}
075: * interface Bar extends Foo<String> {}
076: * </xmp></pre>
077: * This method works like this:
078: * <pre><xmp>
079: * getBaseClass( Bar, List ) = List<List<String>
080: * getBaseClass( Bar, Foo ) = Foo<String>
081: * getBaseClass( Foo<? extends Number>, Collection ) = Collection<List<? extends Number>>
082: * getBaseClass( ArrayList<? extends BigInteger>, List ) = List<? extends BigInteger>
083: * </xmp></pre>
084: *
085: * @param type
086: * The type that derives from {@code baseType}
087: * @param baseType
088: * The class whose parameterization we are interested in.
089: * @return
090: * The use of {@code baseType} in {@code type}.
091: * or null if the type is not assignable to the base type.
092: */
093: T getBaseClass(T type, C baseType);
094:
095: /**
096: * Gets the fully-qualified name of the class.
097: * ("java.lang.Object" for {@link Object})
098: */
099: String getClassName(C clazz);
100:
101: /**
102: * Gets the display name of the type object
103: *
104: * @return
105: * a human-readable name that the type represents.
106: */
107: String getTypeName(T rawType);
108:
109: /**
110: * Gets the short name of the class ("Object" for {@link Object}.)
111: *
112: * For nested classes, this method should just return the inner name.
113: * (for example "Inner" for "com.acme.Outer$Inner".
114: */
115: String getClassShortName(C clazz);
116:
117: /**
118: * Gets all the declared fields of the given class.
119: */
120: Collection<? extends F> getDeclaredFields(C clazz);
121:
122: /**
123: * Gets the named field declared on the given class.
124: *
125: * This method doesn't visit ancestors, but does recognize
126: * non-public fields.
127: *
128: * @return
129: * null if not found
130: */
131: F getDeclaredField(C clazz, String fieldName);
132:
133: /**
134: * Gets all the declared methods of the given class
135: * (regardless of their access modifiers, regardless
136: * of whether they override methods of the base classes.)
137: *
138: * <p>
139: * Note that this method does not list methods declared on base classes.
140: *
141: * @return
142: * can be empty but always non-null.
143: */
144: Collection<? extends M> getDeclaredMethods(C clazz);
145:
146: /**
147: * Gets the class that declares the given field.
148: */
149: C getDeclaringClassForField(F field);
150:
151: /**
152: * Gets the class that declares the given method.
153: */
154: C getDeclaringClassForMethod(M method);
155:
156: /**
157: * Gets the type of the field.
158: */
159: T getFieldType(F f);
160:
161: /**
162: * Gets the name of the field.
163: */
164: String getFieldName(F field);
165:
166: /**
167: * Gets the name of the method, such as "toString" or "equals".
168: */
169: String getMethodName(M m);
170:
171: /**
172: * Gets the return type of a method.
173: */
174: T getReturnType(M m);
175:
176: /**
177: * Returns the list of parameters to the method.
178: */
179: T[] getMethodParameters(M method);
180:
181: /**
182: * Returns true if the method is static.
183: */
184: boolean isStaticMethod(M method);
185:
186: /**
187: * Checks if {@code sub} is a sub-type of {@code sup}.
188: *
189: * TODO: should this method take T or C?
190: */
191: boolean isSubClassOf(T sub, T sup);
192:
193: /**
194: * Gets the representation of the given Java type in {@code T}.
195: *
196: * @param c
197: * can be a primitive, array, class, or anything.
198: * (therefore the return type has to be T, not C)
199: */
200: T ref(Class c);
201:
202: /**
203: * Gets the T for the given C.
204: */
205: T use(C c);
206:
207: /**
208: * If the given type is an use of class declaration,
209: * returns the type casted as {@code C}.
210: * Otherwise null.
211: *
212: * <p>
213: * TODO: define the exact semantics.
214: */
215: C asDecl(T type);
216:
217: /**
218: * Gets the {@code C} representation for the given class.
219: *
220: * The behavior is undefined if the class object represents
221: * primitives, arrays, and other types that are not class declaration.
222: */
223: C asDecl(Class c);
224:
225: /**
226: * Checks if the type is an array type.
227: */
228: boolean isArray(T t);
229:
230: /**
231: * Checks if the type is an array type but not byte[].
232: */
233: boolean isArrayButNotByteArray(T t);
234:
235: /**
236: * Gets the component type of the array.
237: *
238: * @param t
239: * must be an array.
240: */
241: T getComponentType(T t);
242:
243: /** The singleton instance. */
244: public static final ReflectionNavigator REFLECTION = new ReflectionNavigator();
245:
246: /**
247: * Gets the i-th type argument from a parameterized type.
248: *
249: * For example, {@code getTypeArgument([Map<Integer,String>],0)=Integer}
250: *
251: * @throws IllegalArgumentException
252: * If t is not a parameterized type
253: * @throws IndexOutOfBoundsException
254: * If i is out of range.
255: *
256: * @see #isParameterizedType(Object)
257: */
258: T getTypeArgument(T t, int i);
259:
260: /**
261: * Returns true if t is a parameterized type.
262: */
263: boolean isParameterizedType(T t);
264:
265: /**
266: * Checks if the given type is a primitive type.
267: */
268: boolean isPrimitive(T t);
269:
270: /**
271: * Returns the representation for the given primitive type.
272: *
273: * @param primitiveType
274: * must be Class objects like {@link Integer#TYPE}.
275: */
276: T getPrimitive(Class primitiveType);
277:
278: /**
279: * Returns a location of the specified class.
280: */
281: Location getClassLocation(C clazz);
282:
283: Location getFieldLocation(F field);
284:
285: Location getMethodLocation(M getter);
286:
287: /**
288: * Returns true if the given class has a no-arg default constructor.
289: * The constructor does not need to be public.
290: */
291: boolean hasDefaultConstructor(C clazz);
292:
293: /**
294: * Returns true if the field is static.
295: */
296: boolean isStaticField(F field);
297:
298: /**
299: * Returns true if the method is public.
300: */
301: boolean isPublicMethod(M method);
302:
303: /**
304: * Returns true if the field is public.
305: */
306: boolean isPublicField(F field);
307:
308: /**
309: * Returns true if this is an enum class.
310: */
311: boolean isEnum(C clazz);
312:
313: /**
314: * Computes the erasure
315: */
316: <P> T erasure(T contentInMemoryType);
317:
318: // This unused P is necessary to make ReflectionNavigator.erasure work nicely
319:
320: /**
321: * Returns true if this is an abstract class.
322: */
323: boolean isAbstract(C clazz);
324:
325: /**
326: * Returns true if this is a final class.
327: */
328: boolean isFinal(C clazz);
329:
330: /**
331: * Gets the enumeration constants from an enum class.
332: *
333: * @param clazz
334: * must derive from {@link Enum}.
335: *
336: * @return
337: * can be empty but never null.
338: */
339: F[] getEnumConstants(C clazz);
340:
341: /**
342: * Gets the representation of the primitive "void" type.
343: */
344: T getVoidType();
345:
346: /**
347: * Gets the package name of the given class.
348: *
349: * @return
350: * i.e. "", "java.lang" but not null.
351: */
352: String getPackageName(C clazz);
353:
354: /**
355: * Finds the class/interface/enum/annotation of the given name.
356: *
357: * @param referencePoint
358: * The class that refers to the specified class.
359: * @return
360: * null if not found.
361: */
362: C findClass(String className, C referencePoint);
363:
364: /**
365: * Returns true if this method is a bridge method as defined in JLS.
366: */
367: boolean isBridgeMethod(M method);
368:
369: /**
370: * Returns true if the given method is overriding another one
371: * defined in the base class.
372: */
373: boolean isOverriding(M method);
374:
375: /**
376: * Returns true if 'clazz' is an interface.
377: */
378: boolean isInterface(C clazz);
379:
380: /**
381: * Returns true if the field is transient.
382: */
383: boolean isTransient(F f);
384: }
|