TypeToken
Date: 2016-05-24

com.google.common.reflect

## Class TypeToken<T>

- java.lang.Object
- - com.google.common.reflect.TypeToken<T>

- All Implemented Interfaces:
    java.io.Serializable

      @Beta
      public abstract class TypeToken<T>
      extends java.lang.Object
      implements java.io.Serializable

  A `Type` with generics.

  Operations that are otherwise only available in `Class` are implemented to support `Type`, for example `isSubtypeOf(com.google.common.reflect.TypeToken<?>)`, `isArray()` and `getComponentType()`. It also provides additional utilities such as `getTypes()`, `resolveType(java.lang.reflect.Type)`, etc.

  There are three ways to get a `TypeToken` instance:

  - Wrap a `Type` obtained via reflection. For example: `TypeToken.of(method.getGenericReturnType())`.
  - Capture a generic type with a (usually anonymous) subclass. For example:

           new TypeToken<List<String>>() {}

    Note that it's critical that the actual type argument is carried by a subclass. The following code is wrong because it only captures the `<T>` type variable of the `listType()` method signature; while `<String>` is lost in erasure:

           class Util {
             static <T> TypeToken<List<T>> listType() {
               return new TypeToken<List<T>>() {};
             }
           }

           TypeToken<List<String>> stringListType = Util.<String>listType();

  - Capture a generic type with a (usually anonymous) subclass and resolve it against a context class that knows what the type parameters are. For example:

           abstract class IKnowMyType<T> {
             TypeToken<T> type = new TypeToken<T>(getClass()) {};
           }
           new IKnowMyType<String>() {}.type => String

  `TypeToken` is serializable when no type variable is contained in the type.

  Note to Guice users: `` TypeToken is similar to Guice's `TypeLiteral` class except that it is serializable and offers numerous additional utility methods.

  Since:
    12.0
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `TypeToken.TypeSet` The set of interfaces and classes that `T` is or is a subtype of.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `TypeToken()` Constructs a new type token of `T`.
    `protected` | `TypeToken(java.lang.Class<?> declaringClass)` Constructs a new type token of `T` while resolving free type variables in the context of `declaringClass`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Invokable<T,T>` | `constructor(java.lang.reflect.Constructor<?> constructor)` Returns the `Invokable` for `constructor`, which must be a member of `T`.
    `boolean` | `equals(java.lang.Object o)` Returns true if `o` is another `TypeToken` that represents the same `Type`.
    `TypeToken<?>` | `getComponentType()` Returns the array component type if this type represents an array (`int[]`, `T[]`, `<? extends Map<String, Integer>[]>` etc.), or else `null` is returned.
    `java.lang.Class<? super T>` | `getRawType()` Returns the raw type of `T`.
    `TypeToken<? extends T>` | `getSubtype(java.lang.Class<?> subclass)` Returns subtype of `this` with `subclass` as the raw class.
    `TypeToken<? super T>` | `getSupertype(java.lang.Class<? super T> superclass)` Returns the generic form of `superclass`.
    `java.lang.reflect.Type` | `getType()` Returns the represented type.
    `TypeToken.TypeSet` | `getTypes()` Returns the set of interfaces and classes that this type is or is a subtype of.
    `int` | `hashCode()`
    `boolean` | `isArray()` Returns true if this type is known to be an array type, such as `int[]`, `T[]`, `<? extends Map<String, Integer>[]>` etc.
    `boolean` | `isAssignableFrom(java.lang.reflect.Type type)` Deprecated. Use the method under its new name, `isSupertypeOf(Type)`. This method will be removed in Guava release 20.0.
    `boolean` | `isAssignableFrom(TypeToken<?> type)` Deprecated. Use the method under its new name, `isSupertypeOf(TypeToken)`. This method will be removed in Guava release 20.0.
    `boolean` | `isPrimitive()` Returns true if this type is one of the nine primitive types (including `void`).
    `boolean` | `isSubtypeOf(java.lang.reflect.Type supertype)` Returns true if this type is a subtype of the given `type`.
    `boolean` | `isSubtypeOf(TypeToken<?> type)` Returns true if this type is a subtype of the given `type`.
    `boolean` | `isSupertypeOf(java.lang.reflect.Type type)` Returns true if this type is a supertype of the given `type`.
    `boolean` | `isSupertypeOf(TypeToken<?> type)` Returns true if this type is a supertype of the given `type`.
    `Invokable<T,java.lang.Object>` | `method(java.lang.reflect.Method method)` Returns the `Invokable` for `method`, which must be a member of `T`.
    `static <T> TypeToken<T>` | `of(java.lang.Class<T> type)` Returns an instance of type token that wraps `type`.
    `static TypeToken<?>` | `of(java.lang.reflect.Type type)` Returns an instance of type token that wraps `type`.
    `TypeToken<?>` | `resolveType(java.lang.reflect.Type type)` Resolves the given `type` against the type context represented by this type.
    `java.lang.String` | `toString()`
    `TypeToken<T>` | `unwrap()` Returns the corresponding primitive type if this is a wrapper type; otherwise returns `this` itself.
    `<X> TypeToken<T>` | `where(TypeParameter<X> typeParam, java.lang.Class<X> typeArg)` Returns a new `TypeToken` where type variables represented by `typeParam` are substituted by `typeArg`.
    `<X> TypeToken<T>` | `where(TypeParameter<X> typeParam, TypeToken<X> typeArg)` Returns a new `TypeToken` where type variables represented by `typeParam` are substituted by `typeArg`.
    `TypeToken<T>` | `wrap()` Returns the corresponding wrapper type if this is a primitive type; otherwise returns `this` itself.
    `protected java.lang.Object` | `writeReplace()` Implemented to support serialization of subclasses.

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### TypeToken

          protected TypeToken()

      Constructs a new type token of `T`.

      Clients create an empty anonymous subclass. Doing so embeds the type parameter in the anonymous class's type hierarchy so we can reconstitute it at runtime despite erasure.

      For example:

             TypeToken<List<String>> t = new TypeToken<List<String>>() {};

    - #### TypeToken

          protected TypeToken(java.lang.Class<?> declaringClass)

      Constructs a new type token of `T` while resolving free type variables in the context of `declaringClass`.

      Clients create an empty anonymous subclass. Doing so embeds the type parameter in the anonymous class's type hierarchy so we can reconstitute it at runtime despite erasure.

      For example:

             abstract class IKnowMyType<T> {
               TypeToken<T> getMyType() {
                 return new TypeToken<T>(getClass()) {};
               }
             }

             new IKnowMyType<String>() {}.getMyType() => String

  - ### Method Detail

    - #### of

          public static <T> TypeToken<T> of(java.lang.Class<T> type)

      Returns an instance of type token that wraps `type`.

    - #### of

          public static TypeToken<?> of(java.lang.reflect.Type type)

      Returns an instance of type token that wraps `type`.

    - #### getRawType

          public final java.lang.Class<? super T> getRawType()

      Returns the raw type of `T`. Formally speaking, if `T` is returned by `Method.getGenericReturnType()`, the raw type is what's returned by `Method.getReturnType()` of the same method object. Specifically:
      - If `T` is a `Class` itself, `T` itself is returned.
      - If `T` is a `ParameterizedType`, the raw type of the parameterized type is returned.
      - If `T` is a `GenericArrayType`, the returned type is the corresponding array class. For example: `List<Integer>[] => List[]`.
      - If `T` is a type variable or a wildcard type, the raw type of the first upper bound is returned. For example: `<X extends Foo> => Foo`.

    - #### getType

          public final java.lang.reflect.Type getType()

      Returns the represented type.

    - #### where

          public final <X> TypeToken<T> where(TypeParameter<X> typeParam,
                               TypeToken<X> typeArg)

      Returns a new `TypeToken` where type variables represented by `typeParam` are substituted by `typeArg`. For example, it can be used to construct `Map<K, V>` for any `K` and `V` type:

             static <K, V> TypeToken<Map<K, V>> mapOf(
                 TypeToken<K> keyType, TypeToken<V> valueType) {
               return new TypeToken<Map<K, V>>() {}
                   .where(new TypeParameter<K>() {}, keyType)
                   .where(new TypeParameter<V>() {}, valueType);
             }

      Type Parameters:
        `X` - The parameter type
      Parameters:
        `typeParam` - the parameter type variable
        `typeArg` - the actual type to substitute

    - #### where

          public final <X> TypeToken<T> where(TypeParameter<X> typeParam,
                               java.lang.Class<X> typeArg)

      Returns a new `TypeToken` where type variables represented by `typeParam` are substituted by `typeArg`. For example, it can be used to construct `Map<K, V>` for any `K` and `V` type:

             static <K, V> TypeToken<Map<K, V>> mapOf(
                 Class<K> keyType, Class<V> valueType) {
               return new TypeToken<Map<K, V>>() {}
                   .where(new TypeParameter<K>() {}, keyType)
                   .where(new TypeParameter<V>() {}, valueType);
             }

      Type Parameters:
        `X` - The parameter type
      Parameters:
        `typeParam` - the parameter type variable
        `typeArg` - the actual type to substitute

    - #### resolveType

          public final TypeToken<?> resolveType(java.lang.reflect.Type type)

      Resolves the given `type` against the type context represented by this type. For example:

             new TypeToken<List<String>>() {}.resolveType(
                 List.class.getMethod("get", int.class).getGenericReturnType())
             => String.class

    - #### getTypes

          public final TypeToken.TypeSet getTypes()

      Returns the set of interfaces and classes that this type is or is a subtype of. The returned types are parameterized with proper type arguments.

      Subtypes are always listed before supertypes. But the reverse is not true. A type isn't necessarily a subtype of all the types following. Order between types without subtype relationship is arbitrary and not guaranteed.

      If this type is a type variable or wildcard, upper bounds that are themselves type variables aren't included (their super interfaces and superclasses are).

    - #### getSupertype

          public final TypeToken<? super T> getSupertype(java.lang.Class<? super T> superclass)

      Returns the generic form of `superclass`. For example, if this is `ArrayList<String>`, `Iterable<String>` is returned given the input `Iterable.class`.

    - #### getSubtype

          public final TypeToken<? extends T> getSubtype(java.lang.Class<?> subclass)

      Returns subtype of `this` with `subclass` as the raw class. For example, if this is `Iterable<String>` and `subclass` is `List`, `List<String>` is returned.

    - #### isAssignableFrom

          @Deprecated
          public final boolean isAssignableFrom(TypeToken<?> type)

      Deprecated. Use the method under its new name, `isSupertypeOf(TypeToken)`. This method will be removed in Guava release 20.0.
      Returns true if this type is a supertype of the given `type`. "Supertype" is defined according to the rules for type arguments introduced with Java generics.

    - #### isAssignableFrom

          @Deprecated
          public final boolean isAssignableFrom(java.lang.reflect.Type type)

      Deprecated. Use the method under its new name, `isSupertypeOf(Type)`. This method will be removed in Guava release 20.0.
      Returns true if this type is a supertype of the given `type`. "Supertype" is defined according to the rules for type arguments introduced with Java generics.

    - #### isSupertypeOf

          public final boolean isSupertypeOf(TypeToken<?> type)

      Returns true if this type is a supertype of the given `type`. "Supertype" is defined according to the rules for type arguments introduced with Java generics.
      Since:
        19.0

    - #### isSupertypeOf

          public final boolean isSupertypeOf(java.lang.reflect.Type type)

      Returns true if this type is a supertype of the given `type`. "Supertype" is defined according to the rules for type arguments introduced with Java generics.
      Since:
        19.0

    - #### isSubtypeOf

          public final boolean isSubtypeOf(TypeToken<?> type)

      Returns true if this type is a subtype of the given `type`. "Subtype" is defined according to the rules for type arguments introduced with Java generics.
      Since:
        19.0

    - #### isSubtypeOf

          public final boolean isSubtypeOf(java.lang.reflect.Type supertype)

      Returns true if this type is a subtype of the given `type`. "Subtype" is defined according to the rules for type arguments introduced with Java generics.
      Since:
        19.0

    - #### isArray

          public final boolean isArray()

      Returns true if this type is known to be an array type, such as `int[]`, `T[]`, `<? extends Map<String, Integer>[]>` etc.

    - #### isPrimitive

          public final boolean isPrimitive()

      Returns true if this type is one of the nine primitive types (including `void`).
      Since:
        15.0

    - #### wrap

          public final TypeToken<T> wrap()

      Returns the corresponding wrapper type if this is a primitive type; otherwise returns `this` itself. Idempotent.
      Since:
        15.0

    - #### unwrap

          public final TypeToken<T> unwrap()

      Returns the corresponding primitive type if this is a wrapper type; otherwise returns `this` itself. Idempotent.
      Since:
        15.0

    - #### getComponentType

          @Nullable
          public final TypeToken<?> getComponentType()

      Returns the array component type if this type represents an array (`int[]`, `T[]`, `<? extends Map<String, Integer>[]>` etc.), or else `null` is returned.

    - #### method

          public final Invokable<T,java.lang.Object> method(java.lang.reflect.Method method)

      Returns the `Invokable` for `method`, which must be a member of `T`.
      Since:
        14.0

    - #### constructor

          public final Invokable<T,T> constructor(java.lang.reflect.Constructor<?> constructor)

      Returns the `Invokable` for `constructor`, which must be a member of `T`.
      Since:
        14.0

    - #### equals

          public boolean equals(@Nullable
                       java.lang.Object o)

      Returns true if `o` is another `TypeToken` that represents the same `Type`.
      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### writeReplace

          protected java.lang.Object writeReplace()

      Implemented to support serialization of subclasses.