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

org.codehaus.jackson.jaxrs

## Class JacksonJsonProvider

- java.lang.Object
- - org.codehaus.jackson.jaxrs.JacksonJsonProvider

- All Implemented Interfaces:
    MessageBodyReader<Object>, MessageBodyWriter<Object>, Versioned
  Direct Known Subclasses:
    JacksonJaxbJsonProvider

      @Provider
      public class JacksonJsonProvider
      extends Object
      implements MessageBodyReader<Object>, MessageBodyWriter<Object>, Versioned

  Basic implementation of JAX-RS abstractions (`MessageBodyReader`, `MessageBodyWriter`) needed for binding JSON ("application/json") content to and from Java Objects ("POJO"s).

  Actual data binding functionality is implemented by `ObjectMapper`: mapper to use can be configured in multiple ways:

  - By explicitly passing mapper to use in constructor
  - By explictly setting mapper to use by `setMapper(org.codehaus.jackson.map.ObjectMapper)`
  - By defining JAX-RS `Provider` that returns `ObjectMapper`s.
  - By doing none of above, in which case a default mapper instance is constructed (and configured if configuration methods are called)
  The last method ("do nothing specific") is often good enough; explicit passing of Mapper is simple and explicit; and Provider-based method may make sense with Depedency Injection frameworks, or if Mapper has to be configured differently for different media types.

  Note that the default mapper instance will be automatically created if one of explicit configuration methods (like `configure(org.codehaus.jackson.map.DeserializationConfig.Feature, boolean)`) is called: if so, Provider-based introspection is NOT used, but the resulting Mapper is used as configured.

  Note: version 1.3 added a sub-class (`JacksonJaxbJsonProvider`) which is configured by default to use both Jackson and JAXB annotations for configuration (base class when used as-is defaults to using just Jackson annotations)

  Author:
    Tatu Saloranta

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `_cfgCheckCanDeserialize` Whether we want to actually check that Jackson has a deserializer for given type.
    `protected boolean` | `_cfgCheckCanSerialize` Whether we want to actually check that Jackson has a serializer for given type.
    `protected HashSet<ClassKey>` | `_cfgCustomUntouchables` Set of types (classes) that provider should ignore for data binding
    `protected String` | `_jsonpFunctionName` JSONP function name to use for automatic JSONP wrapping, if any; if null, no JSONP wrapping is done.
    `protected MapperConfigurator` | `_mapperConfig` Helper object used for encapsulating configuration aspects of `ObjectMapper`
    `protected Providers` | `_providers` Injectable context object used to locate configured instance of `ObjectMapper` to use for actual serialization.
    `static Class<?>[]` | `_unreadableClasses` These are classes that we never use for reading (never try to deserialize instances of these types).
    `static HashSet<ClassKey>` | `_untouchables` Looks like we need to worry about accidental data binding for types we shouldn't be handling.
    `static Class<?>[]` | `_unwritableClasses` These are classes that we never use for writing (never try to serialize instances of these types).
    `static Annotations[]` | `BASIC_ANNOTATIONS` Default annotation sets to use, if not explicitly defined during construction: only Jackson annotations are used for the base class.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JacksonJsonProvider()` Default constructor, usually used when provider is automatically configured to be used with JAX-RS implementation.
    `JacksonJsonProvider(Annotations... annotationsToUse)`
    `JacksonJsonProvider(ObjectMapper mapper)`
    `JacksonJsonProvider(ObjectMapper mapper, Annotations[] annotationsToUse)` Constructor to use when a custom mapper (usually components like serializer/deserializer factories that have been configured) is to be used.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected static boolean` | `_containedIn(Class<?> mainType, HashSet<ClassKey> set)`
    `protected Class<?>` | `_findView(ObjectMapper mapper, Annotation[] annotations)`
    `void` | `addUntouchable(Class<?> type)` Method for marking specified type as "untouchable", meaning that provider will not try to read or write values of this type (or its subtypes).
    `void` | `checkCanDeserialize(boolean state)` Method for defining whether actual detection for existence of a deserializer for type should be done when `isReadable(java.lang.Class<?>, java.lang.reflect.Type, java.lang.annotation.Annotation[], javax.ws.rs.core.MediaType)` is called.
    `void` | `checkCanSerialize(boolean state)` Method for defining whether actual detection for existence of a serializer for type should be done when `isWriteable(java.lang.Class<?>, java.lang.reflect.Type, java.lang.annotation.Annotation[], javax.ws.rs.core.MediaType)` is called.
    `JacksonJsonProvider` | `configure(DeserializationConfig.Feature f, boolean state)`
    `JacksonJsonProvider` | `configure(JsonGenerator.Feature f, boolean state)`
    `JacksonJsonProvider` | `configure(JsonParser.Feature f, boolean state)`
    `JacksonJsonProvider` | `configure(SerializationConfig.Feature f, boolean state)`
    `JacksonJsonProvider` | `disable(DeserializationConfig.Feature f, boolean state)`
    `JacksonJsonProvider` | `disable(JsonGenerator.Feature f, boolean state)`
    `JacksonJsonProvider` | `disable(JsonParser.Feature f, boolean state)`
    `JacksonJsonProvider` | `disable(SerializationConfig.Feature f, boolean state)`
    `JacksonJsonProvider` | `enable(DeserializationConfig.Feature f, boolean state)`
    `JacksonJsonProvider` | `enable(JsonGenerator.Feature f, boolean state)`
    `JacksonJsonProvider` | `enable(JsonParser.Feature f, boolean state)`
    `JacksonJsonProvider` | `enable(SerializationConfig.Feature f, boolean state)`
    `protected JsonEncoding` | `findEncoding(MediaType mediaType, MultivaluedMap<String,Object> httpHeaders)` Helper method to use for determining desired output encoding.
    `long` | `getSize(Object value, Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType)` Method that JAX-RS container calls to try to figure out serialized length of given value.
    `protected boolean` | `isJsonType(MediaType mediaType)` Helper method used to check whether given media type is JSON type or sub type.
    `boolean` | `isReadable(Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType)` Method that JAX-RS container calls to try to check whether values of given type (and media type) can be deserialized by this provider.
    `boolean` | `isWriteable(Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType)` Method that JAX-RS container calls to try to check whether given value (of specified type) can be serialized by this provider.
    `ObjectMapper` | `locateMapper(Class<?> type, MediaType mediaType)` Method called to locate `ObjectMapper` to use for serialization and deserialization.
    `Object` | `readFrom(Class<Object> type, Type genericType, Annotation[] annotations, MediaType mediaType, MultivaluedMap<String,String> httpHeaders, InputStream entityStream)` Method that JAX-RS container calls to deserialize given value.
    `void` | `setAnnotationsToUse(Annotations[] annotationsToUse)` Method for configuring which annotation sets to use (including none).
    `void` | `setJSONPFunctionName(String fname)`
    `void` | `setMapper(ObjectMapper m)` Method that can be used to directly define `ObjectMapper` to use for serialization and deserialization; if null, will use the standard provider discovery from context instead.
    `Version` | `version()` Method that will return version information stored in and read from jar that contains this class.
    `void` | `writeTo(Object value, Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType, MultivaluedMap<String,Object> httpHeaders, OutputStream entityStream)` Method that JAX-RS container calls to serialize given value.

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

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

- - ### Field Detail

    - #### BASIC_ANNOTATIONS

          public static final Annotations[] BASIC_ANNOTATIONS

      Default annotation sets to use, if not explicitly defined during construction: only Jackson annotations are used for the base class. Sub-classes can use other settings.

    - #### _untouchables

          public static final HashSet<ClassKey> _untouchables

      Looks like we need to worry about accidental data binding for types we shouldn't be handling. This is probably not a very good way to do it, but let's start by blacklisting things we are not to handle.

      (why ClassKey? since plain old Class has no hashCode() defined, lookups are painfully slow)

    - #### _unreadableClasses

          public static final Class<?>[] _unreadableClasses

      These are classes that we never use for reading (never try to deserialize instances of these types).

    - #### _unwritableClasses

          public static final Class<?>[] _unwritableClasses

      These are classes that we never use for writing (never try to serialize instances of these types).

    - #### _mapperConfig

          protected final MapperConfigurator _mapperConfig

      Helper object used for encapsulating configuration aspects of `ObjectMapper`

    - #### _cfgCustomUntouchables

          protected HashSet<ClassKey> _cfgCustomUntouchables

      Set of types (classes) that provider should ignore for data binding
      Since:
        1.5

    - #### _jsonpFunctionName

          protected String _jsonpFunctionName

      JSONP function name to use for automatic JSONP wrapping, if any; if null, no JSONP wrapping is done.

    - #### _providers

          @Context
          protected Providers _providers

      Injectable context object used to locate configured instance of `ObjectMapper` to use for actual serialization.

    - #### _cfgCheckCanSerialize

          protected boolean _cfgCheckCanSerialize

      Whether we want to actually check that Jackson has a serializer for given type. Since this should generally be the case (due to auto-discovery) and since the call to check availability can be bit expensive, defaults to false.

    - #### _cfgCheckCanDeserialize

          protected boolean _cfgCheckCanDeserialize

      Whether we want to actually check that Jackson has a deserializer for given type. Since this should generally be the case (due to auto-discovery) and since the call to check availability can be bit expensive, defaults to false.

  - ### Constructor Detail

    - #### JacksonJsonProvider

          public JacksonJsonProvider()

      Default constructor, usually used when provider is automatically configured to be used with JAX-RS implementation.

    - #### JacksonJsonProvider

          public JacksonJsonProvider(Annotations... annotationsToUse)

      Parameters:
        `annotationsToUse` - Annotation set(s) to use for configuring data binding

    - #### JacksonJsonProvider

          public JacksonJsonProvider(ObjectMapper mapper)

    - #### JacksonJsonProvider

          public JacksonJsonProvider(ObjectMapper mapper,
                             Annotations[] annotationsToUse)

      Constructor to use when a custom mapper (usually components like serializer/deserializer factories that have been configured) is to be used.

  - ### Method Detail

    - #### version

          public Version version()

      Method that will return version information stored in and read from jar that contains this class.
      Specified by:
        `version` in interface `Versioned`
      Since:
        1.6

    - #### checkCanDeserialize

          public void checkCanDeserialize(boolean state)

      Method for defining whether actual detection for existence of a deserializer for type should be done when `isReadable(java.lang.Class<?>, java.lang.reflect.Type, java.lang.annotation.Annotation[], javax.ws.rs.core.MediaType)` is called.

    - #### checkCanSerialize

          public void checkCanSerialize(boolean state)

      Method for defining whether actual detection for existence of a serializer for type should be done when `isWriteable(java.lang.Class<?>, java.lang.reflect.Type, java.lang.annotation.Annotation[], javax.ws.rs.core.MediaType)` is called.

    - #### setAnnotationsToUse

          public void setAnnotationsToUse(Annotations[] annotationsToUse)

      Method for configuring which annotation sets to use (including none). Annotation sets are defined in order decreasing precedence; that is, first one has the priority over following ones.
      Parameters:
        `annotationsToUse` - Ordered list of annotation sets to use; if null, default

    - #### setMapper

          public void setMapper(ObjectMapper m)

      Method that can be used to directly define `ObjectMapper` to use for serialization and deserialization; if null, will use the standard provider discovery from context instead. Default setting is null.

    - #### configure

          public JacksonJsonProvider configure(DeserializationConfig.Feature f,
                                      boolean state)

    - #### configure

          public JacksonJsonProvider configure(SerializationConfig.Feature f,
                                      boolean state)

    - #### configure

          public JacksonJsonProvider configure(JsonParser.Feature f,
                                      boolean state)

    - #### configure

          public JacksonJsonProvider configure(JsonGenerator.Feature f,
                                      boolean state)

    - #### enable

          public JacksonJsonProvider enable(DeserializationConfig.Feature f,
                                   boolean state)

    - #### enable

          public JacksonJsonProvider enable(SerializationConfig.Feature f,
                                   boolean state)

    - #### enable

          public JacksonJsonProvider enable(JsonParser.Feature f,
                                   boolean state)

    - #### enable

          public JacksonJsonProvider enable(JsonGenerator.Feature f,
                                   boolean state)

    - #### disable

          public JacksonJsonProvider disable(DeserializationConfig.Feature f,
                                    boolean state)

    - #### disable

          public JacksonJsonProvider disable(SerializationConfig.Feature f,
                                    boolean state)

    - #### disable

          public JacksonJsonProvider disable(JsonParser.Feature f,
                                    boolean state)

    - #### disable

          public JacksonJsonProvider disable(JsonGenerator.Feature f,
                                    boolean state)

    - #### addUntouchable

          public void addUntouchable(Class<?> type)

      Method for marking specified type as "untouchable", meaning that provider will not try to read or write values of this type (or its subtypes).
      Parameters:
        `type` - Type to consider untouchable; can be any kind of class, including abstract class or interface. No instance of this type (including subtypes, i.e. types assignable to this type) will be read or written by provider
      Since:
        1.5

    - #### setJSONPFunctionName

          public void setJSONPFunctionName(String fname)

    - #### isReadable

          public boolean isReadable(Class<?> type,
                           Type genericType,
                           Annotation[] annotations,
                           MediaType mediaType)

      Method that JAX-RS container calls to try to check whether values of given type (and media type) can be deserialized by this provider. Implementation will first check that expected media type is a JSON type (via call to `isJsonType(javax.ws.rs.core.MediaType)`; then verify that type is not one of "untouchable" types (types we will never automatically handle), and finally that there is a deserializer for type (iff `checkCanDeserialize(boolean)` has been called with true argument -- otherwise assumption is there will be a handler)
      Specified by:
        `isReadable` in interface `MessageBodyReader<Object>`

    - #### readFrom

          public Object readFrom(Class<Object> type,
                        Type genericType,
                        Annotation[] annotations,
                        MediaType mediaType,
                        MultivaluedMap<String,String> httpHeaders,
                        InputStream entityStream)
                          throws IOException

      Method that JAX-RS container calls to deserialize given value.
      Specified by:
        `readFrom` in interface `MessageBodyReader<Object>`
      Throws:
        `IOException`

    - #### getSize

          public long getSize(Object value,
                     Class<?> type,
                     Type genericType,
                     Annotation[] annotations,
                     MediaType mediaType)

      Method that JAX-RS container calls to try to figure out serialized length of given value. Since computation of this length is about as expensive as serialization itself, implementation will return -1 to denote "not known", so that container will determine length from actual serialized output (if needed).
      Specified by:
        `getSize` in interface `MessageBodyWriter<Object>`

    - #### isWriteable

          public boolean isWriteable(Class<?> type,
                            Type genericType,
                            Annotation[] annotations,
                            MediaType mediaType)

      Method that JAX-RS container calls to try to check whether given value (of specified type) can be serialized by this provider. Implementation will first check that expected media type is a JSON type (via call to `isJsonType(javax.ws.rs.core.MediaType)`; then verify that type is not one of "untouchable" types (types we will never automatically handle), and finally that there is a serializer for type (iff `checkCanSerialize(boolean)` has been called with true argument -- otherwise assumption is there will be a handler)
      Specified by:
        `isWriteable` in interface `MessageBodyWriter<Object>`

    - #### writeTo

          public void writeTo(Object value,
                     Class<?> type,
                     Type genericType,
                     Annotation[] annotations,
                     MediaType mediaType,
                     MultivaluedMap<String,Object> httpHeaders,
                     OutputStream entityStream)
                       throws IOException

      Method that JAX-RS container calls to serialize given value.
      Specified by:
        `writeTo` in interface `MessageBodyWriter<Object>`
      Throws:
        `IOException`

    - #### findEncoding

          protected JsonEncoding findEncoding(MediaType mediaType,
                                  MultivaluedMap<String,Object> httpHeaders)

      Helper method to use for determining desired output encoding. For now, will always just use UTF-8...
      Since:
        1.7.0

    - #### isJsonType

          protected boolean isJsonType(MediaType mediaType)

      Helper method used to check whether given media type is JSON type or sub type. Current implementation essentially checks to see whether `MediaType.getSubtype()` returns "json" or something ending with "+json".

    - #### locateMapper

          public ObjectMapper locateMapper(Class<?> type,
                                  MediaType mediaType)

      Method called to locate `ObjectMapper` to use for serialization and deserialization. If an instance has been explicitly defined by `setMapper(org.codehaus.jackson.map.ObjectMapper)` (or non-null instance passed in constructor), that will be used. If not, will try to locate it using standard JAX-RS `ContextResolver` mechanism, if it has been properly configured to access it (by JAX-RS runtime). Finally, if no mapper is found, will return a default unconfigured `ObjectMapper` instance (one constructed with default constructor and not modified in any way)
      Parameters:
        `type` - Class of object being serialized or deserialized; not checked at this point, since it is assumed that unprocessable classes have been already weeded out, but will be passed to `ContextResolver` as is.
        `mediaType` - Declared media type for the instance to process: not used by this method, but will be passed to `ContextResolver` as is.

    - #### _containedIn

          protected static boolean _containedIn(Class<?> mainType,
                             HashSet<ClassKey> set)

    - #### _findView

          protected Class<?> _findView(ObjectMapper mapper,
                           Annotation[] annotations)
                                throws JsonMappingException

      Throws:
        `JsonMappingException`