JavaType (Jackson JSON Processor)
Date: 2013-07-14

org.codehaus.jackson.type

## Class JavaType

- java.lang.Object
- - org.codehaus.jackson.type.JavaType

- Direct Known Subclasses:
    TypeBase

      public abstract class JavaType
      extends Object

  Base class for type token classes used both to contain information and as keys for deserializers.

  Instances can (only) be constructed by `TypeFactory`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Class<?>` | `_class` This is the nominal type-erased Class that would be close to the type represented (but not exactly type, due to type erasure: type instance may have more information on this).
    `protected int` | `_hashCode`
    `protected Object` | `_typeHandler` Optional handler that can be attached to indicate how to handle additional type metadata associated with this type.
    `protected Object` | `_valueHandler` Optional handler (codec) that can be attached to indicate what to use for handling (serializing, deserializing) values of this specific type.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `JavaType(Class<?> raw, int additionalHash)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `_assertSubclass(Class<?> subclass, Class<?> superClass)`
    `protected abstract JavaType` | `_narrow(Class<?> subclass)`
    `protected JavaType` | `_widen(Class<?> superclass)` Default implementation is just to call `_narrow(java.lang.Class<?>)`, since underlying type construction is usually identical
    `JavaType` | `containedType(int index)` Method for accessing definitions of contained ("child") types.
    `int` | `containedTypeCount()` Method for checking how many contained types this type has.
    `String` | `containedTypeName(int index)` Method for accessing name of type variable in indicated position.
    `abstract boolean` | `equals(Object o)`
    `JavaType` | `forcedNarrowBy(Class<?> subclass)` More efficient version of `narrowBy(java.lang.Class<?>)`, called by internal framework in cases where compatibility checks are to be skipped.
    `JavaType` | `getContentType()` Method for accessing content type of this type, if type has such a thing: simple types do not, structured types do (like arrays, Collections and Maps)
    `String` | `getErasedSignature()` Method for accessing signature without generic type information, in form compatible with all versions of JVM, and specifically used for type descriptions when generating byte code.
    `abstract StringBuilder` | `getErasedSignature(StringBuilder sb)` Method for accessing signature without generic type information, in form compatible with all versions of JVM, and specifically used for type descriptions when generating byte code.
    `String` | `getGenericSignature()` Method for accessing signature that contains generic type information, in form compatible with JVM 1.5 as per JLS.
    `abstract StringBuilder` | `getGenericSignature(StringBuilder sb)`
    `JavaType` | `getKeyType()` Method for accessing key type for this type, assuming type has such a concept (only Map types do)
    `Class<?>` | `getRawClass()`
    `<T> T` | `getTypeHandler()` Method for accessing type handler associated with this type, if any
    `<T> T` | `getValueHandler()` Method for accessing value handler associated with this type, if any
    `boolean` | `hasGenericTypes()` Method that can be used to find out if the type directly declares generic parameters (for its direct super-class and/or super-interfaces).
    `int` | `hashCode()`
    `boolean` | `hasRawClass(Class<?> clz)` Method that can be used to check whether this type has specified Class as its type erasure.
    `boolean` | `isAbstract()`
    `boolean` | `isArrayType()`
    `boolean` | `isCollectionLikeType()`
    `boolean` | `isConcrete()`
    `abstract boolean` | `isContainerType()`
    `boolean` | `isEnumType()`
    `boolean` | `isFinal()`
    `boolean` | `isInterface()`
    `boolean` | `isMapLikeType()`
    `boolean` | `isPrimitive()`
    `boolean` | `isThrowable()`
    `JavaType` | `narrowBy(Class<?> subclass)` Method that can be called to do a "narrowing" conversions; that is, to return a type with a raw class that is assignable to the raw class of this type.
    `abstract JavaType` | `narrowContentsBy(Class<?> contentClass)`
    `void` | `setValueHandler(Object h)` Deprecated. Since 1.9, should not be used; instead, use `withContentTypeHandler` and `withContentValueHandler` methods.
    `abstract String` | `toCanonical()` Method that can be used to serialize type into form from which it can be fully deserialized from at a later point (using `TypeFactory` from mapper package).
    `abstract String` | `toString()`
    `JavaType` | `widenBy(Class<?> superclass)` Method that can be called to do a "widening" conversions; that is, to return a type with a raw class that could be assigned from this type.
    `abstract JavaType` | `widenContentsBy(Class<?> contentClass)`
    `abstract JavaType` | `withContentTypeHandler(Object h)` "Copy method" that will construct a new instance that is identical to this instance, except that its content type will have specified type handler assigned.
    `JavaType` | `withContentValueHandler(Object h)`
    `abstract JavaType` | `withTypeHandler(Object h)` "Copy method" that will construct a new instance that is identical to this instance, except that it will have specified type handler assigned.
    `JavaType` | `withValueHandler(Object h)`

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

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

- - ### Field Detail

    - #### _class

          protected final Class<?> _class

      This is the nominal type-erased Class that would be close to the type represented (but not exactly type, due to type erasure: type instance may have more information on this). May be an interface or abstract class, so instantiation may not be possible.

    - #### _hashCode

          protected final int _hashCode

    - #### _valueHandler

          protected Object _valueHandler

      Optional handler (codec) that can be attached to indicate what to use for handling (serializing, deserializing) values of this specific type.

      Note: untyped (i.e. caller has to cast) because it is used for different kinds of handlers, with unrelated types.

      TODO: make final and possible promote to sub-classes

      Since:
        1.3

    - #### _typeHandler

          protected Object _typeHandler

      Optional handler that can be attached to indicate how to handle additional type metadata associated with this type.

      Note: untyped (i.e. caller has to cast) because it is used for different kinds of handlers, with unrelated types.

      TODO: make final and possible promote to sub-classes

      Since:
        1.5

  - ### Constructor Detail

    - #### JavaType

          protected JavaType(Class<?> raw,
                  int additionalHash)

      Parameters:
        `raw` - "Raw" (type-erased) class for this type
        `additionalHash` - Additional hash code to use, in addition to hash code of the class name

  - ### Method Detail

    - #### withTypeHandler

          public abstract JavaType withTypeHandler(Object h)

      "Copy method" that will construct a new instance that is identical to this instance, except that it will have specified type handler assigned.
      Returns:
        Newly created type instance
      Since:
        1.7

    - #### withContentTypeHandler

          public abstract JavaType withContentTypeHandler(Object h)

      "Copy method" that will construct a new instance that is identical to this instance, except that its content type will have specified type handler assigned.
      Returns:
        Newly created type instance
      Since:
        1.7

    - #### withValueHandler

          public JavaType withValueHandler(Object h)

      Since:
        1.9

    - #### withContentValueHandler

          public JavaType withContentValueHandler(Object h)

      Since:
        1.9

    - #### setValueHandler

          @Deprecated
          public void setValueHandler(Object h)

      Deprecated. Since 1.9, should not be used; instead, use `withContentTypeHandler` and `withContentValueHandler` methods.
      Method for assigning handler to associate with this type; or if null passed, to remove such assignment
      Since:
        1.3

    - #### narrowBy

          public JavaType narrowBy(Class<?> subclass)

      Method that can be called to do a "narrowing" conversions; that is, to return a type with a raw class that is assignable to the raw class of this type. If this is not possible, an `IllegalArgumentException` is thrown. If class is same as the current raw class, instance itself is returned.

    - #### forcedNarrowBy

          public JavaType forcedNarrowBy(Class<?> subclass)

      More efficient version of `narrowBy(java.lang.Class<?>)`, called by internal framework in cases where compatibility checks are to be skipped.
      Since:
        1.5

    - #### widenBy

          public JavaType widenBy(Class<?> superclass)

      Method that can be called to do a "widening" conversions; that is, to return a type with a raw class that could be assigned from this type. If such conversion is not possible, an `IllegalArgumentException` is thrown. If class is same as the current raw class, instance itself is returned.

    - #### _narrow

          protected abstract JavaType _narrow(Class<?> subclass)

    - #### _widen

          protected JavaType _widen(Class<?> superclass)

      Default implementation is just to call `_narrow(java.lang.Class<?>)`, since underlying type construction is usually identical

    - #### narrowContentsBy

          public abstract JavaType narrowContentsBy(Class<?> contentClass)

    - #### widenContentsBy

          public abstract JavaType widenContentsBy(Class<?> contentClass)

      Since:
        1.8

    - #### getRawClass

          public final Class<?> getRawClass()

    - #### hasRawClass

          public final boolean hasRawClass(Class<?> clz)

      Method that can be used to check whether this type has specified Class as its type erasure. Put another way, returns true if instantiation of this Type is given (type-erased) Class.

    - #### isAbstract

          public boolean isAbstract()

    - #### isConcrete

          public boolean isConcrete()

      Since:
        1.3

    - #### isThrowable

          public boolean isThrowable()

    - #### isArrayType

          public boolean isArrayType()

    - #### isEnumType

          public final boolean isEnumType()

    - #### isInterface

          public final boolean isInterface()

    - #### isPrimitive

          public final boolean isPrimitive()

    - #### isFinal

          public final boolean isFinal()

    - #### isContainerType

          public abstract boolean isContainerType()

      Returns:
        True if type represented is a container type; this includes array, Map and Collection types.

    - #### isCollectionLikeType

          public boolean isCollectionLikeType()

      Returns:
        True if type is either true `Collection` type, or something similar (meaning it has at least one type parameter, which describes type of contents)
      Since:
        1.8

    - #### isMapLikeType

          public boolean isMapLikeType()

      Returns:
        True if type is either true `Map` type, or something similar (meaning it has at least two type parameter; first one describing key type, second value type)
      Since:
        1.8

    - #### hasGenericTypes

          public boolean hasGenericTypes()

      Method that can be used to find out if the type directly declares generic parameters (for its direct super-class and/or super-interfaces).
      Since:
        1.6

    - #### getKeyType

          public JavaType getKeyType()

      Method for accessing key type for this type, assuming type has such a concept (only Map types do)

    - #### getContentType

          public JavaType getContentType()

      Method for accessing content type of this type, if type has such a thing: simple types do not, structured types do (like arrays, Collections and Maps)

    - #### containedTypeCount

          public int containedTypeCount()

      Method for checking how many contained types this type has. Contained types are usually generic types, so that generic Maps have 2 contained types.
      Since:
        1.5

    - #### containedType

          public JavaType containedType(int index)

      Method for accessing definitions of contained ("child") types.
      Parameters:
        `index` - Index of contained type to return
      Returns:
        Contained type at index, or null if no such type exists (no exception thrown)
      Since:
        1.5

    - #### containedTypeName

          public String containedTypeName(int index)

      Method for accessing name of type variable in indicated position. If no name is bound, will use placeholders (derived from 0-based index); if no type variable or argument exists with given index, null is returned.
      Parameters:
        `index` - Index of contained type to return
      Returns:
        Contained type at index, or null if no such type exists (no exception thrown)
      Since:
        1.5

    - #### getValueHandler

          public <T> T getValueHandler()

      Method for accessing value handler associated with this type, if any
      Since:
        1.3

    - #### getTypeHandler

          public <T> T getTypeHandler()

      Method for accessing type handler associated with this type, if any
      Since:
        1.5

    - #### toCanonical

          public abstract String toCanonical()

      Method that can be used to serialize type into form from which it can be fully deserialized from at a later point (using `TypeFactory` from mapper package). For simple types this is same as calling `Class.getName()`, but for structured types it may additionally contain type information about contents.
      Since:
        1.5

    - #### getGenericSignature

          public String getGenericSignature()

      Method for accessing signature that contains generic type information, in form compatible with JVM 1.5 as per JLS. It is a superset of `getErasedSignature()`, in that generic information can be automatically removed if necessary (just remove outermost angle brackets along with content inside)
      Since:
        1.6

    - #### getGenericSignature

          public abstract StringBuilder getGenericSignature(StringBuilder sb)

      Parameters:
        `sb` - StringBuilder to append signature to
      Returns:
        StringBuilder that was passed in; returned to allow call chaining
      Since:
        1.6

    - #### getErasedSignature

          public String getErasedSignature()

      Method for accessing signature without generic type information, in form compatible with all versions of JVM, and specifically used for type descriptions when generating byte code.
      Since:
        1.6

    - #### getErasedSignature

          public abstract StringBuilder getErasedSignature(StringBuilder sb)

      Method for accessing signature without generic type information, in form compatible with all versions of JVM, and specifically used for type descriptions when generating byte code.
      Parameters:
        `sb` - StringBuilder to append signature to
      Returns:
        StringBuilder that was passed in; returned to allow call chaining
      Since:
        1.6

    - #### _assertSubclass

          protected void _assertSubclass(Class<?> subclass,
                             Class<?> superClass)

    - #### toString

          public abstract String toString()

      Overrides:
        `toString` in class `Object`

    - #### equals

          public abstract boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public final int hashCode()

      Overrides:
        `hashCode` in class `Object`