https://openjdk.java.net/ 
/*
 * 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 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 java.lang.reflect) 
 Navigator instances are stateless and immutable. 
Parameterization


C



A Java class declaration (not an interface, a class and an enum.)

T



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)
/**
 * Provides unified view of the underlying reflection library,
 * such as {@code java.lang.reflect} and/or Annotation Processing.
 *
 * <p>
 * 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})
 *
 * <p>
 * {@link Navigator} instances are stateless and immutable.
 *
 *
 * <h2>Parameterization</h2>
 * <h3>C</h3>
 * <p>
 * A Java class declaration (not an interface, a class and an enum.)
 *
 * <h3>T</h3>
 * <p>
 * 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<T,C,F,M> {
    
Gets the base class of the specified class.

Returns: null if the parameter represents Object.
/**
     * Gets the base class of the specified class.
     *
     * @return
     *      null if the parameter represents {@link Object}.
     */
    C getSuperClass(C clazz);

    
Gets the parameterization of the given base type.


For example, given the following


interface Foo<T> extends List<List<T>> {}
interface Bar extends Foo<String> {}


This method works like this:


getBaseClass( Bar, List ) = List<List<String>>
getBaseClass( Bar, Foo  ) = Foo<String>
getBaseClass( Foo<? extends Number>, Collection ) = Collection<List<? extends Number>>
getBaseClass( ArrayList<? extends BigInteger>, List ) = List<? extends BigInteger>



Params:
  • type –  The type that derives from baseType
  • baseType – 
     The class whose parameterization we are interested in.
Returns: The use of baseType in type. or null if the type is not assignable to the base type.
/**
     * Gets the parameterization of the given base type.
     *
     * <p>
     * For example, given the following
     * <pre>{@code
     * interface Foo<T> extends List<List<T>> {}
     * interface Bar extends Foo<String> {}
     * }</pre>
     * This method works like this:
     * <pre>{@code
     * getBaseClass( Bar, List ) = List<List<String>>
     * getBaseClass( Bar, Foo  ) = Foo<String>
     * getBaseClass( Foo<? extends Number>, Collection ) = Collection<List<? extends Number>>
     * getBaseClass( ArrayList<? extends BigInteger>, List ) = List<? extends BigInteger>
     * }</pre>
     *
     * @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 Object) 
/**
     * 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

Returns:
     a human-readable name that the type represents.
/**
     * 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 Object.) For nested classes, this method should just return the inner name. (for example "Inner" for "com.acme.Outer$Inner". 
/**
     * 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.

/**
     * 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.

Returns:
     null if not found
/**
     * 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.)


Note that this method does not list methods declared on base classes.

Returns:
     can be empty but always non-null.
/**
     * Gets all the declared methods of the given class
     * (regardless of their access modifiers, regardless
     * of whether they override methods of the base classes.)
     *
     * <p>
     * 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.

/**
     * Gets the class that declares the given field.
     */
    C getDeclaringClassForField(F field);

    
Gets the class that declares the given method.

/**
     * Gets the class that declares the given method.
     */
    C getDeclaringClassForMethod(M method);

    
Gets the type of the field.

/**
     * Gets the type of the field.
     */
    T getFieldType(F f);

    
Gets the name of the field.

/**
     * Gets the name of the field.
     */
    String getFieldName(F field);

    
Gets the name of the method, such as "toString" or "equals".

/**
     * Gets the name of the method, such as "toString" or "equals".
     */
    String getMethodName(M m);

    
Gets the return type of a method.

/**
     * Gets the return type of a method.
     */
    T getReturnType(M m);

    
Returns the list of parameters to the method.

/**
     * Returns the list of parameters to the method.
     */
    T[] getMethodParameters(M method);

    
Returns true if the method is static.

/**
     * Returns true if the method is static.
     */
    boolean isStaticMethod(M method);

    
Checks if sub is a sub-type of sup. TODO: should this method take T or C? 
/**
     * 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 T. 
Params:
  • c – 
     can be a primitive, array, class, or anything.
     (therefore the return type has to be T, not C)
/**
     * 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.

/**
     * 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 C. Otherwise null. 

TODO: define the exact semantics.

/**
     * If the given type is an use of class declaration,
     * returns the type casted as {@code C}.
     * Otherwise null.
     *
     * <p>
     * TODO: define the exact semantics.
     */
    C asDecl(T type);

    
Gets the 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. 
/**
     * 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.

/**
     * Checks if the type is an array type.
     */
    boolean isArray(T t);

    
Checks if the type is an array type but not byte[].

/**
     * Checks if the type is an array type but not byte[].
     */
    boolean isArrayButNotByteArray(T t);

    
Gets the component type of the array.

Params:
  • t – 
     must be an array.
/**
     * 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, getTypeArgument([Map<Integer,String>],0)=Integer 
Throws:
See Also:
/**
     * Gets the i-th type argument from a parameterized type.
     *
     * For example, {@code getTypeArgument([Map<Integer,String>],0)=Integer}
     *
     * @throws IllegalArgumentException
     *      If t is not a parameterized type
     * @throws IndexOutOfBoundsException
     *      If i is out of range.
     *
     * @see #isParameterizedType(Object)
     */
    T getTypeArgument(T t, int i);

    
Returns true if t is a parameterized type.

/**
     * Returns true if t is a parameterized type.
     */
    boolean isParameterizedType(T t);

    
Checks if the given type is a primitive type.

/**
     * Checks if the given type is a primitive type.
     */
    boolean isPrimitive(T t);

    
Returns the representation for the given primitive type.

Params:
/**
     * Returns the representation for the given primitive type.
     *
     * @param primitiveType
     *      must be Class objects like {@link Integer#TYPE}.
     */
    T getPrimitive(Class primitiveType);

    
Returns a location of the specified class.

/**
     * Returns a location of the specified class.
     */
    Location getClassLocation(C clazz);

    Location getFieldLocation(F field);

    Location getMethodLocation(M getter);

    
Returns true if the given class has a no-arg default constructor.
The constructor does not need to be public.

/**
     * Returns true if the given class has a no-arg default constructor.
     * The constructor does not need to be public.
     */
    boolean hasDefaultConstructor(C clazz);

    
Returns true if the field is static.

/**
     * Returns true if the field is static.
     */
    boolean isStaticField(F field);

    
Returns true if the method is public.

/**
     * Returns true if the method is public.
     */
    boolean isPublicMethod(M method);

    
Returns true if the method is final.

/**
     * Returns true if the method is final.
     */
    boolean isFinalMethod(M method);

    
Returns true if the field is public.

/**
     * Returns true if the field is public.
     */
    boolean isPublicField(F field);

    
Returns true if this is an enum class.

/**
     * Returns true if this is an enum class.
     */
    boolean isEnum(C clazz);

    
Computes the erasure

/**
     * Computes the erasure
     */
    <P> T erasure(T contentInMemoryType);
    // This unused P is necessary to make ReflectionNavigator.erasure work nicely

    
Returns true if this is an abstract class.

/**
     * Returns true if this is an abstract class.
     */
    boolean isAbstract(C clazz);

    
Returns true if this is a final class.

/**
     * Returns true if this is a final class.
     */
    boolean isFinal(C clazz);

    
Gets the enumeration constants from an enum class.

Params:
  • clazz –  must derive from Enum.
Returns:
     can be empty but never null.
/**
     * 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.

/**
     * Gets the representation of the primitive "void" type.
     */
    T getVoidType();

    
Gets the package name of the given class.

Returns:
     i.e. "", "java.lang" but not null.
/**
     * 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.

Params:
  • referencePoint – 
     The class that refers to the specified class.
Returns:
     null if not found.
/**
     * 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.

/**
     * 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.

/**
     * 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.

/**
     * Returns true if 'clazz' is an interface.
     */
    boolean isInterface(C clazz);

    
Returns true if the field is transient.

/**
     * 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.)

/**
     * 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

Params:
  • t1 – type
  • t2 – type
Returns:true if types are the same
/**
     * 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);
}