/* * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package com.sun.xml.internal.bind.v2.model.nav; import java.util.Collection; import com.sun.xml.internal.bind.v2.runtime.Location; /** * Provides unified view of the underlying reflection library, * such as {@code java.lang.reflect} and/or Annotation Processing. * *
* This interface provides navigation over the reflection model * to decouple the caller from any particular implementation. * This allows the JAXB RI to reuse much of the code between * the compile time (which works on top of Annotation Processing) and the run-time * (which works on top of {@code java.lang.reflect}) * *
* {@link Navigator} instances are stateless and immutable. * * *
* A Java class declaration (not an interface, a class and an enum.) * *
* A Java type. This includs declaration, but also includes such
* things like arrays, primitive types, parameterized types, and etc.
*
* @author Kohsuke Kawaguchi (kk@kohsuke.org)
*/
public interface Navigator
* For example, given the following
*
* Note that this method does not list methods declared on base classes.
*
* @return
* can be empty but always non-null.
*/
Collection extends M> getDeclaredMethods(C clazz);
/**
* Gets the class that declares the given field.
*/
C getDeclaringClassForField(F field);
/**
* Gets the class that declares the given method.
*/
C getDeclaringClassForMethod(M method);
/**
* Gets the type of the field.
*/
T getFieldType(F f);
/**
* Gets the name of the field.
*/
String getFieldName(F field);
/**
* Gets the name of the method, such as "toString" or "equals".
*/
String getMethodName(M m);
/**
* Gets the return type of a method.
*/
T getReturnType(M m);
/**
* Returns the list of parameters to the method.
*/
T[] getMethodParameters(M method);
/**
* Returns true if the method is static.
*/
boolean isStaticMethod(M method);
/**
* Checks if {@code sub} is a sub-type of {@code sup}.
*
* TODO: should this method take T or C?
*/
boolean isSubClassOf(T sub, T sup);
/**
* Gets the representation of the given Java type in {@code T}.
*
* @param c
* can be a primitive, array, class, or anything.
* (therefore the return type has to be T, not C)
*/
T ref(Class c);
/**
* Gets the T for the given C.
*/
T use(C c);
/**
* If the given type is an use of class declaration,
* returns the type casted as {@code C}.
* Otherwise null.
*
*
* TODO: define the exact semantics.
*/
C asDecl(T type);
/**
* Gets the {@code C} representation for the given class.
*
* The behavior is undefined if the class object represents
* primitives, arrays, and other types that are not class declaration.
*/
C asDecl(Class c);
/**
* Checks if the type is an array type.
*/
boolean isArray(T t);
/**
* Checks if the type is an array type but not byte[].
*/
boolean isArrayButNotByteArray(T t);
/**
* Gets the component type of the array.
*
* @param t
* must be an array.
*/
T getComponentType(T t);
/**
* Gets the i-th type argument from a parameterized type.
*
* For example, {@code getTypeArgument([Map T erasure(T contentInMemoryType);
// This unused P is necessary to make ReflectionNavigator.erasure work nicely
/**
* Returns true if this is an abstract class.
*/
boolean isAbstract(C clazz);
/**
* Returns true if this is a final class.
*/
boolean isFinal(C clazz);
/**
* Gets the enumeration constants from an enum class.
*
* @param clazz
* must derive from {@link Enum}.
*
* @return
* can be empty but never null.
*/
F[] getEnumConstants(C clazz);
/**
* Gets the representation of the primitive "void" type.
*/
T getVoidType();
/**
* Gets the package name of the given class.
*
* @return
* i.e. "", "java.lang" but not null.
*/
String getPackageName(C clazz);
/**
* Finds ObjectFactory for the given referencePoint.
*
* @param referencePoint
* The class that refers to the specified class.
* @return
* null if not found.
*/
C loadObjectFactory(C referencePoint, String packageName);
/**
* Returns true if this method is a bridge method as defined in JLS.
*/
boolean isBridgeMethod(M method);
/**
* Returns true if the given method is overriding another one
* defined in the base class 'base' or its ancestors.
*/
boolean isOverriding(M method, C base);
/**
* Returns true if 'clazz' is an interface.
*/
boolean isInterface(C clazz);
/**
* Returns true if the field is transient.
*/
boolean isTransient(F f);
/**
* Returns true if the given class is an inner class.
*
* This is only used to improve the error diagnostics, so
* it's OK to fail to detect some inner classes as such.
*
* Note that this method should return false for nested classes
* (static classes.)
*/
boolean isInnerClass(C clazz);
/**
* Checks if types are the same
* @param t1 type
* @param t2 type
* @return true if types are the same
*/
boolean isSameType(T t1, T t2);
}
{@code
* interface Foo
* This method works like this:
* > {}
* interface Bar extends Foo
{@code
* getBaseClass( Bar, List ) = List
*
* @param type
* The type that derives from {@code baseType}
* @param baseType
* The class whose parameterization we are interested in.
* @return
* The use of {@code baseType} in {@code type}.
* or null if the type is not assignable to the base type.
*/
T getBaseClass(T type, C baseType);
/**
* Gets the fully-qualified name of the class.
* ("java.lang.Object" for {@link Object})
*/
String getClassName(C clazz);
/**
* Gets the display name of the type object
*
* @return
* a human-readable name that the type represents.
*/
String getTypeName(T rawType);
/**
* Gets the short name of the class ("Object" for {@link Object}.)
*
* For nested classes, this method should just return the inner name.
* (for example "Inner" for "com.acme.Outer$Inner".
*/
String getClassShortName(C clazz);
/**
* Gets all the declared fields of the given class.
*/
Collection extends F> getDeclaredFields(C clazz);
/**
* Gets the named field declared on the given class.
*
* This method doesn't visit ancestors, but does recognize
* non-public fields.
*
* @return
* null if not found
*/
F getDeclaredField(C clazz, String fieldName);
/**
* Gets all the declared methods of the given class
* (regardless of their access modifiers, regardless
* of whether they override methods of the base classes.)
*
* >
* getBaseClass( Bar, Foo ) = Foo
>
* getBaseClass( ArrayList extends BigInteger>, List ) = List extends BigInteger>
* }