jdk8-mips64-public/jaxws: src/share/jaxws_classes/com/sun/xml/internal/bind/v2/model/nav/Navigator.java@9c07ef4934dd

     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.nav;

    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;

    34 import com.sun.xml.internal.bind.v2.runtime.Location;

    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);

    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);

    99     /**

   100      * Gets the fully-qualified name of the class.

   101      * ("java.lang.Object" for {@link Object})

   102      */

   103     String getClassName(C clazz);

   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);

   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);

   121     /**

   122      * Gets all the declared fields of the given class.

   123      */

   124     Collection<? extends F> getDeclaredFields(C clazz);

   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);

   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);

   150     /**

   151      * Gets the class that declares the given field.

   152      */

   153     C getDeclaringClassForField(F field);

   155     /**

   156      * Gets the class that declares the given method.

   157      */

   158     C getDeclaringClassForMethod(M method);

   160     /**

   161      * Gets the type of the field.

   162      */

   163     T getFieldType(F f);

   165     /**

   166      * Gets the name of the field.

   167      */

   168     String getFieldName(F field);

   170     /**

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

   172      */

   173     String getMethodName(M m);

   175     /**

   176      * Gets the return type of a method.

   177      */

   178     T getReturnType(M m);

   180     /**

   181      * Returns the list of parameters to the method.

   182      */

   183     T[] getMethodParameters(M method);

   185     /**

   186      * Returns true if the method is static.

   187      */

   188     boolean isStaticMethod(M method);

   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);

   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);

   206     /**

   207      * Gets the T for the given C.

   208      */

   209     T use(C c);

   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);

   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);

   229     /**

   230      * Checks if the type is an array type.

   231      */

   232     boolean isArray(T t);

   234     /**

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

   236      */

   237     boolean isArrayButNotByteArray(T t);

   239     /**

   240      * Gets the component type of the array.

   241      *

   242      * @param t

   243      *      must be an array.

   244      */

   245     T getComponentType(T t);

   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);

   261     /**

   262      * Returns true if t is a parameterized type.

   263      */

   264     boolean isParameterizedType(T t);

   266     /**

   267      * Checks if the given type is a primitive type.

   268      */

   269     boolean isPrimitive(T t);

   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);

   279     /**

   280      * Returns a location of the specified class.

   281      */

   282     Location getClassLocation(C clazz);

   284     Location getFieldLocation(F field);

   286     Location getMethodLocation(M getter);

   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);

   294     /**

   295      * Returns true if the field is static.

   296      */

   297     boolean isStaticField(F field);

   299     /**

   300      * Returns true if the method is public.

   301      */

   302     boolean isPublicMethod(M method);

   304     /**

   305      * Returns true if the method is final.

   306      */

   307     boolean isFinalMethod(M method);

   309     /**

   310      * Returns true if the field is public.

   311      */

   312     boolean isPublicField(F field);

   314     /**

   315      * Returns true if this is an enum class.

   316      */

   317     boolean isEnum(C clazz);

   319     /**

   320      * Computes the erasure

   321      */

   322     <P> T erasure(T contentInMemoryType);

   323     // This unused P is necessary to make ReflectionNavigator.erasure work nicely

   325     /**

   326      * Returns true if this is an abstract class.

   327      */

   328     boolean isAbstract(C clazz);

   330     /**

   331      * Returns true if this is a final class.

   332      */

   333     boolean isFinal(C clazz);

   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);

   346     /**

   347      * Gets the representation of the primitive "void" type.

   348      */

   349     T getVoidType();

   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);

   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);

   369     /**

   370      * Returns true if this method is a bridge method as defined in JLS.

   371      */

   372     boolean isBridgeMethod(M method);

   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);

   380     /**

   381      * Returns true if 'clazz' is an interface.

   382      */

   383     boolean isInterface(C clazz);

   385     /**

   386      * Returns true if the field is transient.

   387      */

   388     boolean isTransient(F f);

   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);

   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 }

Mercurial > jdk8-mips64-public > jaxws / file revision

src/share/jaxws_classes/com/sun/xml/internal/bind/v2/model/nav/Navigator.java@9c07ef4934dd

src/share/jaxws_classes/com/sun/xml/internal/bind/v2/model/nav/Navigator.java