com.fasterxml.jackson.jaxrs.xml
Class JacksonXMLProvider

java.lang.Object
  com.fasterxml.jackson.jaxrs.xml.JacksonXMLProvider

All Implemented Interfaces:

com.fasterxml.jackson.core.Versioned, javax.ws.rs.ext.MessageBodyReader<Object>, javax.ws.rs.ext.MessageBodyWriter<Object>

Direct Known Subclasses:

JacksonJaxbXMLProvider

@Provider
public class JacksonXMLProvider
extends Object
implements javax.ws.rs.ext.MessageBodyReader<Object>, javax.ws.rs.ext.MessageBodyWriter<Object>, com.fasterxml.jackson.core.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(com.fasterxml.jackson.dataformat.xml.XmlMapper)
• By defining JAX-RS Provider that returns XmlMappers.
• 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(com.fasterxml.jackson.databind.DeserializationFeature, 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 (JacksonJaxbXMLProvider) 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

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 MapperConfigurator	_mapperConfig Helper object used for encapsulating configuration aspects of XmlMapper
protected javax.ws.rs.ext.Providers	_providers Injectable context object used to locate configured instance of XmlMapper to use for actual serialization.
protected com.fasterxml.jackson.databind.util.LRUMap<AnnotationBundleKey,EndpointConfig>	_readers Cache for resolved endpoint configurations when reading XML
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).
protected com.fasterxml.jackson.databind.util.LRUMap<AnnotationBundleKey,EndpointConfig>	_writers Cache for resolved endpoint configurations when writing XML
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

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

JacksonXMLProvider(Annotations... annotationsToUse)

JacksonXMLProvider(com.fasterxml.jackson.dataformat.xml.XmlMapper mapper)

JacksonXMLProvider(com.fasterxml.jackson.dataformat.xml.XmlMapper 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

protected static boolean	_containedIn(Class<?> mainType, HashSet<ClassKey> set)
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.
JacksonXMLProvider	configure(com.fasterxml.jackson.databind.DeserializationFeature f, boolean state)
JacksonXMLProvider	configure(com.fasterxml.jackson.core.JsonGenerator.Feature f, boolean state)
JacksonXMLProvider	configure(com.fasterxml.jackson.core.JsonParser.Feature f, boolean state)
JacksonXMLProvider	configure(com.fasterxml.jackson.databind.SerializationFeature f, boolean state)
JacksonXMLProvider	disable(com.fasterxml.jackson.databind.DeserializationFeature f, boolean state)
JacksonXMLProvider	disable(com.fasterxml.jackson.core.JsonGenerator.Feature f, boolean state)
JacksonXMLProvider	disable(com.fasterxml.jackson.core.JsonParser.Feature f, boolean state)
JacksonXMLProvider	disable(com.fasterxml.jackson.databind.SerializationFeature f, boolean state)
JacksonXMLProvider	enable(com.fasterxml.jackson.databind.DeserializationFeature f, boolean state)
JacksonXMLProvider	enable(com.fasterxml.jackson.core.JsonGenerator.Feature f, boolean state)
JacksonXMLProvider	enable(com.fasterxml.jackson.core.JsonParser.Feature f, boolean state)
JacksonXMLProvider	enable(com.fasterxml.jackson.databind.SerializationFeature f, boolean state)
protected com.fasterxml.jackson.core.JsonEncoding	findEncoding(javax.ws.rs.core.MediaType mediaType, javax.ws.rs.core.MultivaluedMap<String,Object> httpHeaders) Helper method to use for determining desired output encoding.
long	getSize(Object value, Class<?> type, Type genericType, Annotation[] annotations, javax.ws.rs.core.MediaType mediaType) Method that JAX-RS container calls to try to figure out serialized length of given value.
boolean	isReadable(Class<?> type, Type genericType, Annotation[] annotations, javax.ws.rs.core.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.
protected boolean	isReadableType(Class<?> type) Helper method called to see if given type is readable, that is, acceptable Java type to bind from XML
protected boolean	isWritableType(Class<?> type) Helper method called to see if given type is writable, that is, acceptable Java type to write out as XML.
boolean	isWriteable(Class<?> type, Type genericType, Annotation[] annotations, javax.ws.rs.core.MediaType mediaType) Method that JAX-RS container calls to try to check whether given value (of specified type) can be serialized by this provider.
protected boolean	isXMLType(javax.ws.rs.core.MediaType mediaType) Helper method used to check whether given media type is XML type or sub type.
com.fasterxml.jackson.dataformat.xml.XmlMapper	locateMapper(Class<?> type, javax.ws.rs.core.MediaType mediaType) Method called to locate XmlMapper to use for serialization and deserialization.
Object	readFrom(Class<Object> type, Type genericType, Annotation[] annotations, javax.ws.rs.core.MediaType mediaType, javax.ws.rs.core.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	setMapper(com.fasterxml.jackson.dataformat.xml.XmlMapper m) Method that can be used to directly define XmlMapper to use for serialization and deserialization; if null, will use the standard provider discovery from context instead.
com.fasterxml.jackson.core.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, javax.ws.rs.core.MediaType mediaType, javax.ws.rs.core.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).

_readers

protected final com.fasterxml.jackson.databind.util.LRUMap<AnnotationBundleKey,EndpointConfig> _readers

Cache for resolved endpoint configurations when reading XML

_writers

protected final com.fasterxml.jackson.databind.util.LRUMap<AnnotationBundleKey,EndpointConfig> _writers

Cache for resolved endpoint configurations when writing XML

_mapperConfig

protected final MapperConfigurator _mapperConfig

Helper object used for encapsulating configuration aspects of XmlMapper

_cfgCustomUntouchables

protected HashSet<ClassKey> _cfgCustomUntouchables

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

_providers

@Context
protected javax.ws.rs.ext.Providers _providers

Injectable context object used to locate configured instance of XmlMapper 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

JacksonXMLProvider

public JacksonXMLProvider()

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

JacksonXMLProvider

public JacksonXMLProvider(Annotations... annotationsToUse)

Parameters:

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

JacksonXMLProvider

public JacksonXMLProvider(com.fasterxml.jackson.dataformat.xml.XmlMapper mapper)

JacksonXMLProvider

public JacksonXMLProvider(com.fasterxml.jackson.dataformat.xml.XmlMapper mapper,
                          Annotations[] annotationsToUse)

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

Parameters:

annotationsToUse - Sets of annotations (Jackson, JAXB) that provider should support

Method Detail

version

public com.fasterxml.jackson.core.Version version()

Method that will return version information stored in and read from jar that contains this class.

Specified by:

version in interface com.fasterxml.jackson.core.Versioned

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(com.fasterxml.jackson.dataformat.xml.XmlMapper m)

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

configure

public JacksonXMLProvider configure(com.fasterxml.jackson.databind.DeserializationFeature f,
                                    boolean state)

configure

public JacksonXMLProvider configure(com.fasterxml.jackson.databind.SerializationFeature f,
                                    boolean state)

configure

public JacksonXMLProvider configure(com.fasterxml.jackson.core.JsonParser.Feature f,
                                    boolean state)

configure

public JacksonXMLProvider configure(com.fasterxml.jackson.core.JsonGenerator.Feature f,
                                    boolean state)

enable

public JacksonXMLProvider enable(com.fasterxml.jackson.databind.DeserializationFeature f,
                                 boolean state)

enable

public JacksonXMLProvider enable(com.fasterxml.jackson.databind.SerializationFeature f,
                                 boolean state)

enable

public JacksonXMLProvider enable(com.fasterxml.jackson.core.JsonParser.Feature f,
                                 boolean state)

enable

public JacksonXMLProvider enable(com.fasterxml.jackson.core.JsonGenerator.Feature f,
                                 boolean state)

disable

public JacksonXMLProvider disable(com.fasterxml.jackson.databind.DeserializationFeature f,
                                  boolean state)

disable

public JacksonXMLProvider disable(com.fasterxml.jackson.databind.SerializationFeature f,
                                  boolean state)

disable

public JacksonXMLProvider disable(com.fasterxml.jackson.core.JsonParser.Feature f,
                                  boolean state)

disable

public JacksonXMLProvider disable(com.fasterxml.jackson.core.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

isReadable

public boolean isReadable(Class<?> type,
                          Type genericType,
                          Annotation[] annotations,
                          javax.ws.rs.core.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 an XML type (via call to isXMLType(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 javax.ws.rs.ext.MessageBodyReader<Object>

readFrom

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

Method that JAX-RS container calls to deserialize given value.

Specified by:

readFrom in interface javax.ws.rs.ext.MessageBodyReader<Object>

Throws:

IOException

getSize

public long getSize(Object value,
                    Class<?> type,
                    Type genericType,
                    Annotation[] annotations,
                    javax.ws.rs.core.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 javax.ws.rs.ext.MessageBodyWriter<Object>

isWriteable

public boolean isWriteable(Class<?> type,
                           Type genericType,
                           Annotation[] annotations,
                           javax.ws.rs.core.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 an XML type (via call to isXMLType(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 javax.ws.rs.ext.MessageBodyWriter<Object>

writeTo

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

Method that JAX-RS container calls to serialize given value.

Specified by:

writeTo in interface javax.ws.rs.ext.MessageBodyWriter<Object>

Throws:

IOException

findEncoding

protected com.fasterxml.jackson.core.JsonEncoding findEncoding(javax.ws.rs.core.MediaType mediaType,
                                                               javax.ws.rs.core.MultivaluedMap<String,Object> httpHeaders)

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

isXMLType

protected boolean isXMLType(javax.ws.rs.core.MediaType mediaType)

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

isReadableType

protected boolean isReadableType(Class<?> type)

Helper method called to see if given type is readable, that is, acceptable Java type to bind from XML

isWritableType

protected boolean isWritableType(Class<?> type)

Helper method called to see if given type is writable, that is, acceptable Java type to write out as XML.

locateMapper

public com.fasterxml.jackson.dataformat.xml.XmlMapper locateMapper(Class<?> type,
                                                                   javax.ws.rs.core.MediaType mediaType)

Method called to locate XmlMapper to use for serialization and deserialization. If an instance has been explicitly defined by setMapper(com.fasterxml.jackson.dataformat.xml.XmlMapper) (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)