TypeUtils
Date: 2017-02-08

org.apache.commons.lang3.reflect

## Class TypeUtils

- java.lang.Object
- - org.apache.commons.lang3.reflect.TypeUtils

-     public class TypeUtils
      extends java.lang.Object

  Utility methods focusing on type inspection, particularly with regard to generics.

  Since:
    3.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `TypeUtils.WildcardTypeBuilder` `WildcardType` builder.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.reflect.WildcardType` | `WILDCARD_ALL` A wildcard instance matching `?`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TypeUtils()` `TypeUtils` instances should NOT be constructed in standard programming.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `containsTypeVariables(java.lang.reflect.Type type)` Learn, recursively, whether any of the type parameters associated with `type` are bound to variables.
    `static java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type>` | `determineTypeArguments(java.lang.Class<?> cls, java.lang.reflect.ParameterizedType superType)` Tries to determine the type arguments of a class/interface based on a super parameterized type's type arguments.
    `static boolean` | `equals(java.lang.reflect.Type t1, java.lang.reflect.Type t2)` Check equality of types.
    `static java.lang.reflect.GenericArrayType` | `genericArrayType(java.lang.reflect.Type componentType)` Create a generic array type instance.
    `static java.lang.reflect.Type` | `getArrayComponentType(java.lang.reflect.Type type)` Get the array component type of `type`.
    `static java.lang.reflect.Type[]` | `getImplicitBounds(java.lang.reflect.TypeVariable<?> typeVariable)` Returns an array containing the sole type of `Object` if `TypeVariable.getBounds()` returns an empty array.
    `static java.lang.reflect.Type[]` | `getImplicitLowerBounds(java.lang.reflect.WildcardType wildcardType)` Returns an array containing a single value of `null` if `WildcardType.getLowerBounds()` returns an empty array.
    `static java.lang.reflect.Type[]` | `getImplicitUpperBounds(java.lang.reflect.WildcardType wildcardType)` Returns an array containing the sole value of `Object` if `WildcardType.getUpperBounds()` returns an empty array.
    `static java.lang.Class<?>` | `getRawType(java.lang.reflect.Type type, java.lang.reflect.Type assigningType)` Get the raw type of a Java type, given its context.
    `static java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type>` | `getTypeArguments(java.lang.reflect.ParameterizedType type)` Retrieves all the type arguments for this parameterized type including owner hierarchy arguments such as `Outer<K,V>.Inner<T>.DeepInner<E>` .
    `static java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type>` | `getTypeArguments(java.lang.reflect.Type type, java.lang.Class<?> toClass)` Gets the type arguments of a class/interface based on a subtype.
    `static boolean` | `isArrayType(java.lang.reflect.Type type)` Learn whether the specified type denotes an array type.
    `static boolean` | `isAssignable(java.lang.reflect.Type type, java.lang.reflect.Type toType)` Checks if the subject type may be implicitly cast to the target type following the Java generics rules.
    `static boolean` | `isInstance(java.lang.Object value, java.lang.reflect.Type type)` Checks if the given value can be assigned to the target type following the Java generics rules.
    `static java.lang.reflect.Type[]` | `normalizeUpperBounds(java.lang.reflect.Type[] bounds)` This method strips out the redundant upper bound types in type variable types and wildcard types (or it would with wildcard types if multiple upper bounds were allowed).
    `static java.lang.reflect.ParameterizedType` | `parameterize(java.lang.Class<?> raw, java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type> typeArgMappings)` Create a parameterized type instance.
    `static java.lang.reflect.ParameterizedType` | `parameterize(java.lang.Class<?> raw, java.lang.reflect.Type... typeArguments)` Create a parameterized type instance.
    `static java.lang.reflect.ParameterizedType` | `parameterizeWithOwner(java.lang.reflect.Type owner, java.lang.Class<?> raw, java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type> typeArgMappings)` Create a parameterized type instance.
    `static java.lang.reflect.ParameterizedType` | `parameterizeWithOwner(java.lang.reflect.Type owner, java.lang.Class<?> raw, java.lang.reflect.Type... typeArguments)` Create a parameterized type instance.
    `static java.lang.String` | `toLongString(java.lang.reflect.TypeVariable<?> var)` Format a `TypeVariable` including its `GenericDeclaration`.
    `static java.lang.String` | `toString(java.lang.reflect.Type type)` Present a given type as a Java-esque String.
    `static boolean` | `typesSatisfyVariables(java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type> typeVarAssigns)` Determines whether or not specified types satisfy the bounds of their mapped type variables.
    `static java.lang.reflect.Type` | `unrollVariables(java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type> typeArguments, java.lang.reflect.Type type)` Get a type representing `type` with variable assignments "unrolled."
    `static TypeUtils.WildcardTypeBuilder` | `wildcardType()` Get a `TypeUtils.WildcardTypeBuilder`.
    `static <T> Typed<T>` | `wrap(java.lang.Class<T> type)` Wrap the specified `Class` in a `Typed` wrapper.
    `static <T> Typed<T>` | `wrap(java.lang.reflect.Type type)` Wrap the specified `Type` in a `Typed` wrapper.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### WILDCARD_ALL

          public static final java.lang.reflect.WildcardType WILDCARD_ALL

      A wildcard instance matching `?`.
      Since:
        3.2

  - ### Constructor Detail

    - #### TypeUtils

          public TypeUtils()

      `TypeUtils` instances should NOT be constructed in standard programming. Instead, the class should be used as `TypeUtils.isAssignable(cls, toClass)`.

      This constructor is public to permit tools that require a JavaBean instance to operate.

  - ### Method Detail

    - #### isAssignable

          public static boolean isAssignable(java.lang.reflect.Type type,
                             java.lang.reflect.Type toType)

      Checks if the subject type may be implicitly cast to the target type following the Java generics rules. If both types are `Class` objects, the method returns the result of `ClassUtils.isAssignable(Class, Class)`.

      Parameters:
        `type` - the subject type to be assigned to the target type
        `toType` - the target type
      Returns:
        `true` if `type` is assignable to `toType`.

    - #### getTypeArguments

          public static java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type> getTypeArguments(java.lang.reflect.ParameterizedType type)

      Retrieves all the type arguments for this parameterized type including owner hierarchy arguments such as `Outer<K,V>.Inner<T>.DeepInner<E>` . The arguments are returned in a `Map` specifying the argument type for each `TypeVariable`.

      Parameters:
        `type` - specifies the subject parameterized type from which to harvest the parameters.
      Returns:
        a `Map` of the type arguments to their respective type variables.

    - #### getTypeArguments

          public static java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type> getTypeArguments(java.lang.reflect.Type type,
                                                                                                 java.lang.Class<?> toClass)

      Gets the type arguments of a class/interface based on a subtype. For instance, this method will determine that both of the parameters for the interface `Map` are `Object` for the subtype `Properties` even though the subtype does not directly implement the `Map` interface.

      This method returns `null` if `type` is not assignable to `toClass`. It returns an empty map if none of the classes or interfaces in its inheritance hierarchy specify any type arguments.

      A side effect of this method is that it also retrieves the type arguments for the classes and interfaces that are part of the hierarchy between `type` and `toClass`. So with the above example, this method will also determine that the type arguments for `Hashtable` are also both `Object`. In cases where the interface specified by `toClass` is (indirectly) implemented more than once (e.g. where `toClass` specifies the interface `Iterable` and `type` specifies a parameterized type that implements both `Set` and `Collection`), this method will look at the inheritance hierarchy of only one of the implementations/subclasses; the first interface encountered that isn't a subinterface to one of the others in the `type` to `toClass` hierarchy.

      Parameters:
        `type` - the type from which to determine the type parameters of `toClass`
        `toClass` - the class whose type parameters are to be determined based on the subtype `type`
      Returns:
        a `Map` of the type assignments for the type variables in each type in the inheritance hierarchy from `type` to `toClass` inclusive.

    - #### determineTypeArguments

          public static java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type> determineTypeArguments(java.lang.Class<?> cls,
                                                                                                       java.lang.reflect.ParameterizedType superType)

      Tries to determine the type arguments of a class/interface based on a super parameterized type's type arguments. This method is the inverse of `getTypeArguments(Type, Class)` which gets a class/interface's type arguments based on a subtype. It is far more limited in determining the type arguments for the subject class's type variables in that it can only determine those parameters that map from the subject `Class` object to the supertype.

      Example: `TreeSet` sets its parameter as the parameter for `NavigableSet`, which in turn sets the parameter of `SortedSet`, which in turn sets the parameter of `Set`, which in turn sets the parameter of `Collection`, which in turn sets the parameter of `Iterable`. Since `TreeSet`'s parameter maps (indirectly) to `Iterable`'s parameter, it will be able to determine that based on the super type `Iterable<? extends Map<Integer, ? extends Collection<?>>>`, the parameter of `TreeSet` is `? extends Map<Integer, ? extends Collection<?>>`.

      Parameters:
        `cls` - the class whose type parameters are to be determined, not `null`
        `superType` - the super type from which `cls`'s type arguments are to be determined, not `null`
      Returns:
        a `Map` of the type assignments that could be determined for the type variables in each type in the inheritance hierarchy from `type` to `toClass` inclusive.

    - #### isInstance

          public static boolean isInstance(java.lang.Object value,
                           java.lang.reflect.Type type)

      Checks if the given value can be assigned to the target type following the Java generics rules.

      Parameters:
        `value` - the value to be checked
        `type` - the target type
      Returns:
        `true` if `value` is an instance of `type`.

    - #### normalizeUpperBounds

          public static java.lang.reflect.Type[] normalizeUpperBounds(java.lang.reflect.Type[] bounds)

      This method strips out the redundant upper bound types in type variable types and wildcard types (or it would with wildcard types if multiple upper bounds were allowed).

      Example, with the variable type declaration:

          <K extends java.util.Collection<String> &
           java.util.List<String>>

      since `List` is a subinterface of `Collection`, this method will return the bounds as if the declaration had been:

          <K extends java.util.List<String>>

      Parameters:
        `bounds` - an array of types representing the upper bounds of either `WildcardType` or `TypeVariable`, not `null`.
      Returns:
        an array containing the values from `bounds` minus the redundant types.

    - #### getImplicitBounds

          public static java.lang.reflect.Type[] getImplicitBounds(java.lang.reflect.TypeVariable<?> typeVariable)

      Returns an array containing the sole type of `Object` if `TypeVariable.getBounds()` returns an empty array. Otherwise, it returns the result of `TypeVariable.getBounds()` passed into `normalizeUpperBounds(java.lang.reflect.Type[])`.

      Parameters:
        `typeVariable` - the subject type variable, not `null`
      Returns:
        a non-empty array containing the bounds of the type variable.

    - #### getImplicitUpperBounds

          public static java.lang.reflect.Type[] getImplicitUpperBounds(java.lang.reflect.WildcardType wildcardType)

      Returns an array containing the sole value of `Object` if `WildcardType.getUpperBounds()` returns an empty array. Otherwise, it returns the result of `WildcardType.getUpperBounds()` passed into `normalizeUpperBounds(java.lang.reflect.Type[])`.

      Parameters:
        `wildcardType` - the subject wildcard type, not `null`
      Returns:
        a non-empty array containing the upper bounds of the wildcard type.

    - #### getImplicitLowerBounds

          public static java.lang.reflect.Type[] getImplicitLowerBounds(java.lang.reflect.WildcardType wildcardType)

      Returns an array containing a single value of `null` if `WildcardType.getLowerBounds()` returns an empty array. Otherwise, it returns the result of `WildcardType.getLowerBounds()`.

      Parameters:
        `wildcardType` - the subject wildcard type, not `null`
      Returns:
        a non-empty array containing the lower bounds of the wildcard type.

    - #### typesSatisfyVariables

          public static boolean typesSatisfyVariables(java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type> typeVarAssigns)

      Determines whether or not specified types satisfy the bounds of their mapped type variables. When a type parameter extends another (such as `<T, S extends T>`), uses another as a type parameter (such as `<T, S extends Comparable>>`), or otherwise depends on another type variable to be specified, the dependencies must be included in `typeVarAssigns`.

      Parameters:
        `typeVarAssigns` - specifies the potential types to be assigned to the type variables, not `null`.
      Returns:
        whether or not the types can be assigned to their respective type variables.

    - #### getRawType

          public static java.lang.Class<?> getRawType(java.lang.reflect.Type type,
                                      java.lang.reflect.Type assigningType)

      Get the raw type of a Java type, given its context. Primarily for use with `TypeVariable`s and `GenericArrayType`s, or when you do not know the runtime type of `type`: if you know you have a `Class` instance, it is already raw; if you know you have a `ParameterizedType`, its raw type is only a method call away.

      Parameters:
        `type` - to resolve
        `assigningType` - type to be resolved against
      Returns:
        the resolved `Class` object or `null` if the type could not be resolved

    - #### isArrayType

          public static boolean isArrayType(java.lang.reflect.Type type)

      Learn whether the specified type denotes an array type.
      Parameters:
        `type` - the type to be checked
      Returns:
        `true` if `type` is an array class or a `GenericArrayType`.

    - #### getArrayComponentType

          public static java.lang.reflect.Type getArrayComponentType(java.lang.reflect.Type type)

      Get the array component type of `type`.
      Parameters:
        `type` - the type to be checked
      Returns:
        component type or null if type is not an array type

    - #### unrollVariables

          public static java.lang.reflect.Type unrollVariables(java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type> typeArguments,
                                               java.lang.reflect.Type type)

      Get a type representing `type` with variable assignments "unrolled."
      Parameters:
        `typeArguments` - as from `getTypeArguments(Type, Class)`
        `type` - the type to unroll variable assignments for
      Returns:
        Type
      Since:
        3.2

    - #### containsTypeVariables

          public static boolean containsTypeVariables(java.lang.reflect.Type type)

      Learn, recursively, whether any of the type parameters associated with `type` are bound to variables.
      Parameters:
        `type` - the type to check for type variables
      Returns:
        boolean
      Since:
        3.2

    - #### parameterize

          public static final java.lang.reflect.ParameterizedType parameterize(java.lang.Class<?> raw,
                                                         java.lang.reflect.Type... typeArguments)

      Create a parameterized type instance.
      Parameters:
        `raw` - the raw class to create a parameterized type instance for
        `typeArguments` - the types used for parameterization
      Returns:
        `ParameterizedType`
      Since:
        3.2

    - #### parameterize

          public static final java.lang.reflect.ParameterizedType parameterize(java.lang.Class<?> raw,
                                                         java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type> typeArgMappings)

      Create a parameterized type instance.
      Parameters:
        `raw` - the raw class to create a parameterized type instance for
        `typeArgMappings` - the mapping used for parameterization
      Returns:
        `ParameterizedType`
      Since:
        3.2

    - #### parameterizeWithOwner

          public static final java.lang.reflect.ParameterizedType parameterizeWithOwner(java.lang.reflect.Type owner,
                                                                  java.lang.Class<?> raw,
                                                                  java.lang.reflect.Type... typeArguments)

      Create a parameterized type instance.
      Parameters:
        `owner` - the owning type
        `raw` - the raw class to create a parameterized type instance for
        `typeArguments` - the types used for parameterization
      Returns:
        `ParameterizedType`
      Since:
        3.2

    - #### parameterizeWithOwner

          public static final java.lang.reflect.ParameterizedType parameterizeWithOwner(java.lang.reflect.Type owner,
                                                                  java.lang.Class<?> raw,
                                                                  java.util.Map<java.lang.reflect.TypeVariable<?>,java.lang.reflect.Type> typeArgMappings)

      Create a parameterized type instance.
      Parameters:
        `owner` - the owning type
        `raw` - the raw class to create a parameterized type instance for
        `typeArgMappings` - the mapping used for parameterization
      Returns:
        `ParameterizedType`
      Since:
        3.2

    - #### wildcardType

          public static TypeUtils.WildcardTypeBuilder wildcardType()

      Get a `TypeUtils.WildcardTypeBuilder`.
      Returns:
        `TypeUtils.WildcardTypeBuilder`
      Since:
        3.2

    - #### genericArrayType

          public static java.lang.reflect.GenericArrayType genericArrayType(java.lang.reflect.Type componentType)

      Create a generic array type instance.
      Parameters:
        `componentType` - the type of the elements of the array. For example the component type of `boolean[]` is `boolean`
      Returns:
        `GenericArrayType`
      Since:
        3.2

    - #### equals

          public static boolean equals(java.lang.reflect.Type t1,
                       java.lang.reflect.Type t2)

      Check equality of types.
      Parameters:
        `t1` - the first type
        `t2` - the second type
      Returns:
        boolean
      Since:
        3.2

    - #### toString

          public static java.lang.String toString(java.lang.reflect.Type type)

      Present a given type as a Java-esque String.
      Parameters:
        `type` - the type to create a String representation for, not `null`
      Returns:
        String
      Since:
        3.2

    - #### toLongString

          public static java.lang.String toLongString(java.lang.reflect.TypeVariable<?> var)

      Format a `TypeVariable` including its `GenericDeclaration`.
      Parameters:
        `var` - the type variable to create a String representation for, not `null`
      Returns:
        String
      Since:
        3.2

    - #### wrap

          public static <T> Typed<T> wrap(java.lang.reflect.Type type)

      Wrap the specified `Type` in a `Typed` wrapper.
      Type Parameters:
        `T` - inferred generic type
      Parameters:
        `type` - to wrap
      Returns:
        Typed<T>
      Since:
        3.2

    - #### wrap

          public static <T> Typed<T> wrap(java.lang.Class<T> type)

      Wrap the specified `Class` in a `Typed` wrapper.
      Type Parameters:
        `T` - generic type
      Parameters:
        `type` - to wrap
      Returns:
        Typed<T>
      Since:
        3.2