org.codehaus.jackson.map
Class ObjectMapper

java.lang.Object
  extended by org.codehaus.jackson.ObjectCodec
      extended by org.codehaus.jackson.map.ObjectMapper

public class ObjectMapper
extends ObjectCodec

This mapper (or, data binder, or codec) provides functionality for conversting between Java objects (instances of JDK provided core classes, beans), and matching JSON constructs. It will use instances of JsonParser and JsonGenerator for implementing actual reading/writing of JSON.

The main conversion API is defined in ObjectCodec, so that implementation details of this class need not be exposed to streaming parser and generator classes.

Note on caching: root-level deserializers are always cached, and accessed using full (generics-aware) type information. This is different from caching of referenced types, which is more limited and is done only for a subset of all deserializer types. The main reason for difference is that at root-level there is no incoming reference (and hence no referencing property, no referral information or annotations to produce differing deserializers), and that the performance impact greatest at root level (since it'll essentially cache the full graph of deserializers involved).


Field Summary
protected  DeserializationConfig _deserializationConfig
          Configuration object that defines basic global settings for the serialization process
protected  DeserializerProvider _deserializerProvider
          Object that manages access to deserializers used for deserializing Json content into Java objects, including possible caching of the deserializers.
protected  JsonFactory _jsonFactory
          Factory used to create JsonParser and JsonGenerator instances as necessary.
protected  java.util.concurrent.ConcurrentHashMap<JavaType,JsonDeserializer<java.lang.Object>> _rootDeserializers
          We will use a separate main-level Map for keeping track of root-level deserializers.
protected  SerializationConfig _serializationConfig
          Configuration object that defines basic global settings for the serialization process
protected  SerializerFactory _serializerFactory
          Serializer factory used for constructing serializers.
protected  SerializerProvider _serializerProvider
          Object that manages access to serializers used for serialization, including caching.
protected  ClassIntrospector<? extends BeanDescription> DEFAULT_INTROSPECTOR
           
 
Constructor Summary
ObjectMapper()
          Default constructor, which will construct the default JsonFactory as necessary, use StdSerializerProvider as its SerializerProvider, and BeanSerializerFactory as its SerializerFactory.
ObjectMapper(JsonFactory jf)
           
ObjectMapper(JsonFactory jf, SerializerProvider sp, DeserializerProvider dp)
           
ObjectMapper(JsonFactory jf, SerializerProvider sp, DeserializerProvider dp, SerializationConfig sconfig, DeserializationConfig dconfig)
           
ObjectMapper(SerializerFactory sf)
           
 
Method Summary
protected  void _configAndWriteValue(JsonGenerator jgen, java.lang.Object value)
          Method called to configure the generator as necessary and then call write functionality
protected  DeserializationContext _createDeserializationContext(JsonParser jp)
           
protected  JsonDeserializer<java.lang.Object> _findRootDeserializer(JavaType valueType)
          Method called to locate deserializer for the passed root-level value.
protected  JsonToken _initForReading(JsonParser jp)
          Method called to ensure that given parser is ready for reading content for data binding.
protected  java.lang.Object _readMapAndClose(JsonParser jp, JavaType valueType)
           
protected  java.lang.Object _readValue(JsonParser jp, JavaType valueType)
          Actual implementation of value reading+binding operation.
 boolean canDeserialize(JavaType type)
          Method that can be called to check whether mapper thinks it could deserialize an Object of given type.
 boolean canSerialize(java.lang.Class<?> type)
          Method that can be called to check whether mapper thinks it could serialize an instance of given Class.
 void configure(DeserializationConfig.Feature f, boolean state)
           
 void configure(SerializationConfig.Feature f, boolean state)
           
 DeserializationConfig getDeserializationConfig()
           
 JsonFactory getJsonFactory()
          Method that can be used to get hold of Json factory that this mapper uses if it needs to construct Json parsers and/or generators.
 SerializationConfig getSerializationConfig()
           
 JsonNode readTree(JsonParser jp)
          Method to deserialize Json content as tree expressed using set of JsonNode instances.
<T> T
readValue(byte[] src, int offset, int len, java.lang.Class<T> valueType)
           
<T> T
readValue(byte[] src, int offset, int len, JavaType valueType)
           
<T> T
readValue(byte[] src, int offset, int len, TypeReference valueTypeRef)
           
<T> T
readValue(java.io.File src, java.lang.Class<T> valueType)
           
<T> T
readValue(java.io.File src, JavaType valueType)
           
<T> T
readValue(java.io.File src, TypeReference valueTypeRef)
           
<T> T
readValue(java.io.InputStream src, java.lang.Class<T> valueType)
           
<T> T
readValue(java.io.InputStream src, JavaType valueType)
           
<T> T
readValue(java.io.InputStream src, TypeReference valueTypeRef)
           
<T> T
readValue(JsonParser jp, java.lang.Class<T> valueType)
          Method to deserialize Json content into a non-container type (it can be an array type, however): typically a bean, array or a wrapper type (like Boolean).
<T> T
readValue(JsonParser jp, JavaType valueType)
          Method to deserialize Json content into a Java type, reference to which is passed as argument.
<T> T
readValue(JsonParser jp, TypeReference<?> valueTypeRef)
          Method to deserialize Json content into a Java type, reference to which is passed as argument.
<T> T
readValue(java.io.Reader src, java.lang.Class<T> valueType)
           
<T> T
readValue(java.io.Reader src, JavaType valueType)
           
<T> T
readValue(java.io.Reader src, TypeReference valueTypeRef)
           
<T> T
readValue(java.lang.String content, java.lang.Class<T> valueType)
           
<T> T
readValue(java.lang.String content, JavaType valueType)
           
<T> T
readValue(java.lang.String content, TypeReference valueTypeRef)
           
<T> T
readValue(java.net.URL src, java.lang.Class<T> valueType)
           
<T> T
readValue(java.net.URL src, JavaType valueType)
           
<T> T
readValue(java.net.URL src, TypeReference valueTypeRef)
           
 void setDeserializationConfig(DeserializationConfig cfg)
           
 void setDeserializerProvider(DeserializerProvider p)
           
 void setSerializationConfig(SerializationConfig cfg)
           
 void setSerializerFactory(SerializerFactory f)
           
 void setSerializerProvider(SerializerProvider p)
           
 void writeTree(JsonGenerator jgen, JsonNode rootNode)
          Method to serialize given Json Tree, using generator provided.
 void writeValue(java.io.File resultFile, java.lang.Object value)
          Method that can be used to serialize any Java value as Json output, written to File provided.
 void writeValue(JsonGenerator jgen, java.lang.Object value)
          Method that can be used to serialize any Java value as Json output, using provided JsonGenerator.
 void writeValue(java.io.OutputStream out, java.lang.Object value)
          Method that can be used to serialize any Java value as Json output, using output stream provided (using encoding {link JsonEncoding#UTF8}).
 void writeValue(java.io.Writer w, java.lang.Object value)
          Method that can be used to serialize any Java value as Json output, using Writer provided.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_INTROSPECTOR

protected final ClassIntrospector<? extends BeanDescription> DEFAULT_INTROSPECTOR

_jsonFactory

protected final JsonFactory _jsonFactory
Factory used to create JsonParser and JsonGenerator instances as necessary.


_serializationConfig

protected SerializationConfig _serializationConfig
Configuration object that defines basic global settings for the serialization process


_serializerProvider

protected SerializerProvider _serializerProvider
Object that manages access to serializers used for serialization, including caching. It is configured with _serializerFactory to allow for constructing custom serializers.


_serializerFactory

protected SerializerFactory _serializerFactory
Serializer factory used for constructing serializers.


_deserializationConfig

protected DeserializationConfig _deserializationConfig
Configuration object that defines basic global settings for the serialization process


_deserializerProvider

protected DeserializerProvider _deserializerProvider
Object that manages access to deserializers used for deserializing Json content into Java objects, including possible caching of the deserializers. It contains a reference to DeserializerFactory to use for constructing acutal deserializers.


_rootDeserializers

protected final java.util.concurrent.ConcurrentHashMap<JavaType,JsonDeserializer<java.lang.Object>> _rootDeserializers
We will use a separate main-level Map for keeping track of root-level deserializers. This is where most succesful cache lookups get resolved. Map will contain resolvers for all kinds of types, including container types: this is different from the component cache which will only cache bean deserializers.

Given that we don't expect much concurrency for additions (should very quickly converge to zero after startup), let's explicitly define a low concurrency setting.

Constructor Detail

ObjectMapper

public ObjectMapper()
Default constructor, which will construct the default JsonFactory as necessary, use StdSerializerProvider as its SerializerProvider, and BeanSerializerFactory as its SerializerFactory. This means that it can serialize all standard JDK types, as well as regular Java Beans (based on method names and Jackson-specific annotations), but does not support JAXB annotations.


ObjectMapper

public ObjectMapper(JsonFactory jf)

ObjectMapper

public ObjectMapper(SerializerFactory sf)

ObjectMapper

public ObjectMapper(JsonFactory jf,
                    SerializerProvider sp,
                    DeserializerProvider dp)

ObjectMapper

public ObjectMapper(JsonFactory jf,
                    SerializerProvider sp,
                    DeserializerProvider dp,
                    SerializationConfig sconfig,
                    DeserializationConfig dconfig)
Parameters:
jf - JsonFactory to use: if null, a new MappingJsonFactory will be constructed
sp - SerializerProvider to use: if null, a StdSerializerProvider will be constructed
dp - DeserializerProvider to use: if null, a StdDeserializerProvider will be constructed
sconfig - Serialization configuration to use; if null, basic SerializationConfig will be constructed
dconfig - Deserialization configuration to use; if null, basic DeserializationConfig will be constructed
Method Detail

setSerializerFactory

public void setSerializerFactory(SerializerFactory f)

setSerializerProvider

public void setSerializerProvider(SerializerProvider p)

setDeserializerProvider

public void setDeserializerProvider(DeserializerProvider p)

getSerializationConfig

public SerializationConfig getSerializationConfig()

setSerializationConfig

public void setSerializationConfig(SerializationConfig cfg)

configure

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

getDeserializationConfig

public DeserializationConfig getDeserializationConfig()

setDeserializationConfig

public void setDeserializationConfig(DeserializationConfig cfg)

configure

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

getJsonFactory

public JsonFactory getJsonFactory()
Method that can be used to get hold of Json factory that this mapper uses if it needs to construct Json parsers and/or generators.

Returns:
Json factory that this mapper uses when it needs to construct Json parser and generators

readValue

public <T> T readValue(JsonParser jp,
                       java.lang.Class<T> valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Method to deserialize Json content into a non-container type (it can be an array type, however): typically a bean, array or a wrapper type (like Boolean).

Note: this method should NOT be used if the result type is a container (Collection or Map. The reason is that due to type erasure, key and value types can not be introspected when using this method.

Specified by:
readValue in class ObjectCodec
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(JsonParser jp,
                       TypeReference<?> valueTypeRef)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Method to deserialize Json content into a Java type, reference to which is passed as argument. Type is passed using so-called "super type token" (see ) and specifically needs to be used if the root type is a parameterized (generic) container type.

Specified by:
readValue in class ObjectCodec
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(JsonParser jp,
                       JavaType valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Method to deserialize Json content into a Java type, reference to which is passed as argument. Type is passed using Jackson specific type; instance of which can be constructed using TypeFactory.

Specified by:
readValue in class ObjectCodec
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readTree

public JsonNode readTree(JsonParser jp)
                  throws java.io.IOException,
                         JsonProcessingException
Method to deserialize Json content as tree expressed using set of JsonNode instances. Returns root of the resulting tree (where root can consist of just a single node if the current event is a value event, not container).

Specified by:
readTree in class ObjectCodec
Throws:
java.io.IOException
JsonProcessingException

writeValue

public void writeValue(JsonGenerator jgen,
                       java.lang.Object value)
                throws java.io.IOException,
                       JsonGenerationException,
                       JsonMappingException
Method that can be used to serialize any Java value as Json output, using provided JsonGenerator.

Specified by:
writeValue in class ObjectCodec
Throws:
java.io.IOException
JsonGenerationException
JsonMappingException

writeTree

public void writeTree(JsonGenerator jgen,
                      JsonNode rootNode)
               throws java.io.IOException,
                      JsonProcessingException
Method to serialize given Json Tree, using generator provided.

Specified by:
writeTree in class ObjectCodec
Throws:
java.io.IOException
JsonProcessingException

canSerialize

public boolean canSerialize(java.lang.Class<?> type)
Method that can be called to check whether mapper thinks it could serialize an instance of given Class. Check is done by checking whether a serializer can be found for the type.

Returns:
True if mapper can find a serializer for instances of given class (potentially serializable), false otherwise (not serializable)

canDeserialize

public boolean canDeserialize(JavaType type)
Method that can be called to check whether mapper thinks it could deserialize an Object of given type. Check is done by checking whether a deserializer can be found for the type.

Returns:
True if mapper can find a serializer for instances of given class (potentially serializable), false otherwise (not serializable)

readValue

public <T> T readValue(java.io.File src,
                       java.lang.Class<T> valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.io.File src,
                       TypeReference valueTypeRef)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.io.File src,
                       JavaType valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.net.URL src,
                       java.lang.Class<T> valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.net.URL src,
                       TypeReference valueTypeRef)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.net.URL src,
                       JavaType valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.lang.String content,
                       java.lang.Class<T> valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.lang.String content,
                       TypeReference valueTypeRef)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.lang.String content,
                       JavaType valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.io.Reader src,
                       java.lang.Class<T> valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.io.Reader src,
                       TypeReference valueTypeRef)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.io.Reader src,
                       JavaType valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.io.InputStream src,
                       java.lang.Class<T> valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.io.InputStream src,
                       TypeReference valueTypeRef)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(java.io.InputStream src,
                       JavaType valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(byte[] src,
                       int offset,
                       int len,
                       java.lang.Class<T> valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(byte[] src,
                       int offset,
                       int len,
                       TypeReference valueTypeRef)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

readValue

public <T> T readValue(byte[] src,
                       int offset,
                       int len,
                       JavaType valueType)
            throws java.io.IOException,
                   JsonParseException,
                   JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

writeValue

public void writeValue(java.io.File resultFile,
                       java.lang.Object value)
                throws java.io.IOException,
                       JsonGenerationException,
                       JsonMappingException
Method that can be used to serialize any Java value as Json output, written to File provided.

Throws:
java.io.IOException
JsonGenerationException
JsonMappingException

writeValue

public void writeValue(java.io.OutputStream out,
                       java.lang.Object value)
                throws java.io.IOException,
                       JsonGenerationException,
                       JsonMappingException
Method that can be used to serialize any Java value as Json output, using output stream provided (using encoding {link JsonEncoding#UTF8}).

Note: method does not close the underlying stream explicitly here; however, JsonFactory this mapper uses may choose to close the stream depending on its settings (by default, it will try to close it when JsonGenerator we construct is closed).

Throws:
java.io.IOException
JsonGenerationException
JsonMappingException

writeValue

public void writeValue(java.io.Writer w,
                       java.lang.Object value)
                throws java.io.IOException,
                       JsonGenerationException,
                       JsonMappingException
Method that can be used to serialize any Java value as Json output, using Writer provided.

Note: method does not close the underlying stream explicitly here; however, JsonFactory this mapper uses may choose to close the stream depending on its settings (by default, it will try to close it when JsonGenerator we construct is closed).

Throws:
java.io.IOException
JsonGenerationException
JsonMappingException

_configAndWriteValue

protected final void _configAndWriteValue(JsonGenerator jgen,
                                          java.lang.Object value)
                                   throws java.io.IOException,
                                          JsonGenerationException,
                                          JsonMappingException
Method called to configure the generator as necessary and then call write functionality

Throws:
java.io.IOException
JsonGenerationException
JsonMappingException

_readValue

protected java.lang.Object _readValue(JsonParser jp,
                                      JavaType valueType)
                               throws java.io.IOException,
                                      JsonParseException,
                                      JsonMappingException
Actual implementation of value reading+binding operation.

Throws:
java.io.IOException
JsonParseException
JsonMappingException

_readMapAndClose

protected java.lang.Object _readMapAndClose(JsonParser jp,
                                            JavaType valueType)
                                     throws java.io.IOException,
                                            JsonParseException,
                                            JsonMappingException
Throws:
java.io.IOException
JsonParseException
JsonMappingException

_initForReading

protected JsonToken _initForReading(JsonParser jp)
                             throws java.io.IOException,
                                    JsonParseException,
                                    JsonMappingException
Method called to ensure that given parser is ready for reading content for data binding.

Returns:
First token to be used for data binding after this call: can never be null as exception will be thrown if parser can not provide more tokens.
Throws:
java.io.IOException - if the underlying input source has problems during parsing
JsonParseException - if parser has problems parsing content
JsonMappingException - if the parser does not have any more content to map (note: Json "null" value is considered content; enf-of-stream not)

_findRootDeserializer

protected JsonDeserializer<java.lang.Object> _findRootDeserializer(JavaType valueType)
                                                            throws JsonMappingException
Method called to locate deserializer for the passed root-level value.

Throws:
JsonMappingException

_createDeserializationContext

protected DeserializationContext _createDeserializationContext(JsonParser jp)