JsonNode), as well as
related functionality for performing conversions.
In addition to directly reading and writing JSON (and with different underlying
TokenStreamFactory configuration, other formats), it is also the
mechanism for creating ObjectReaders and ObjectWriters which
offer more advancing reading/writing functionality.
Construction of mapper instances proceeds either via no-arguments constructor
(producing instance with default configuration); or through one of two build
methods.
First build method is the static builder() on exact type
and second rebuild() method on an existing mapper.
Former starts with default configuration (same as one that no-arguments constructor
created mapper has), and latter starts with configuration of the mapper it is called
on.
In both cases, after configuration (including addition of JacksonModules) is complete,
instance is created by calling MapperBuilder#build() method.
Mapper (and ObjectReaders, ObjectWriters it constructs) will
use instances of JsonParser and JsonGenerator
for implementing actual reading/writing of JSON.
Note that although most read and write methods are exposed through this class,
some of the functionality is only exposed via ObjectReader and
ObjectWriter: specifically, reading/writing of longer sequences of
values is only available through ObjectReader#readValues(InputStream)
and ObjectWriter#writeValues(OutputStream).
Simplest usage is of form:
final ObjectMapper mapper = new ObjectMapper(); // can use static singleton, inject: just make sure to reuse!
MyValue value = new MyValue();
// ... and configure
File newState = new File("my-stuff.json");
mapper.writeValue(newState, value); // writes JSON serialization of MyValue instance
// or, read
MyValue older = mapper.readValue(new File("my-older-stuff.json"), MyValue.class);
// Or if you prefer JSON Tree representation:
JsonNode root = mapper.readTree(newState);
// and find values by, for example, using a tools.jackson.core.JsonPointer expression:
int age = root.at("/personal/age").getValueAsInt();
Mapper instances are fully thread-safe as of Jackson 3.0.
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).
| Modifier and Type | Class and Description |
|---|---|
| private static class | ObjectMapper.
Base implementation for "Vanilla" |
| Modifier and Type | Field and Description |
|---|---|
| protected final DeserializationConfig | _deserializationConfig
Configuration object that defines basic global settings for the serialization process |
| protected final DeserializationContexts | _deserializationContexts
Factory used for constructing per-call |
| protected final InjectableValues | _injectableValues
Provider for values to inject in deserialized POJOs. |
| protected final ConcurrentHashMap | _rootDeserializers
We will use a separate main-level Map for keeping track of root-level deserializers. |
| protected final MapperBuilderState | _savedBuilderState
Minimal state retained to allow both re-building (by creating new builder) and JDK serialization of this mapper. |
| protected final SerializationConfig | _serializationConfig
Configuration object that defines basic global settings for the serialization process |
| protected final SerializationContexts | _serializationContexts
Factory used for constructing per-call |
| protected final TokenStreamFactory | _streamFactory
Factory used to create |
| protected final TypeFactory | _typeFactory
Specific factory used for creating |
| private static final JavaType | |
| private static final long |
| Access | Constructor and Description |
|---|---|
| public | ObjectMapper()
Default constructor, which will construct the default JSON-handling
|
| public | ObjectMapper(TokenStreamFactory streamFactory)
Constructs instance that uses specified |
| protected | ObjectMapper(MapperBuilder<?, ?> builder)
Constructor usually called either by |
| Modifier and Type | Method and Description |
|---|---|
| protected final void | |
| private final void | _configAndWriteCloseable(SerializationContextExt prov, JsonGenerator g, Object value)
Helper method used when value to serialize is |
| protected final void | _configAndWriteValue(SerializationContextExt prov, JsonGenerator g, Object value)
Method called to configure the generator as necessary and then call write functionality |
| protected Object | |
| protected DeserializationContextExt | _deserializationContext(JsonParser p)
Internal helper method called to create an instance of |
| public DeserializationContextExt | |
| protected DeserializationContextExt | |
| protected ValueDeserializer | _findRootDeserializer(DeserializationContext ctxt, JavaType valueType)
Method called to locate deserializer for the passed root-level value. |
| protected JsonToken | Returns: First token to be used for data binding after this call: can never be null as exception will be thrown if parser cannot provide more tokens.Method called to ensure that given parser is ready for reading content for data binding. |
| protected ObjectReader | _newReader(DeserializationConfig config)
Factory method sub-classes must override, to produce |
| protected ObjectReader | _newReader(DeserializationConfig config, JavaType valueType, Object valueToUpdate, FormatSchema schema, InjectableValues injectableValues)
Factory method sub-classes must override, to produce |
| protected ObjectWriter | _newWriter(SerializationConfig config)
Factory method sub-classes must override, to produce |
| protected ObjectWriter | _newWriter(SerializationConfig config, FormatSchema schema)
Factory method sub-classes must override, to produce |
| protected ObjectWriter | _newWriter(SerializationConfig config, JavaType rootType, PrettyPrinter pp)
Factory method sub-classes must override, to produce |
| protected Object | |
| protected JsonNode | _readTreeAndClose(DeserializationContextExt ctxt, JsonParser p0)
Similar to |
| protected Object | _readValue(DeserializationContextExt ctxt, JsonParser p, JavaType valueType)
Actual implementation of value reading+binding operation. |
| protected SerializationContextExt | _serializationContext(SerializationConfig config)
Overridable helper method used for constructing
|
| public SerializationContextExt | |
| protected final void | |
| protected void | |
| protected final void | _writeCloseableValue(JsonGenerator g, Object value, SerializationConfig cfg)
Helper method used when value to serialize is |
| public void | acceptJsonFormatVisitor(Class<?>
Type to generate schema for (possibly with generic signature) type, JsonFormatVisitorWrapper visitor)Method for visiting type hierarchy for given type, using specified visitor. |
| public void | |
| public void | acceptJsonFormatVisitor(JavaType
Type to generate schema for (possibly with generic signature) type, JsonFormatVisitorWrapper visitor)Method for visiting type hierarchy for given type, using specified visitor. |
| public JsonNode | |
| public void | |
| public JavaType | constructType(Type type)
Convenience method for constructing |
| public JavaType | constructType(TypeReference<?> typeReference)
Convenience method for constructing |
| public <T> T | convertValue(Object fromValue, Class<T> toValueType)
Convenience method for doing two-step conversion from given value, into instance of given value type, by writing value into temporary buffer and reading from the buffer into specified target type. |
| public <T> T | |
| public <T> T | |
| public ArrayNode | createArrayNode()
Implements tools. Note return type is co-variant, as basic |
| public JsonGenerator | createGenerator(OutputStream out)
Factory method for constructing |
| public JsonGenerator | createGenerator(OutputStream out, JsonEncoding enc)
Factory method for constructing |
| public JsonGenerator | createGenerator(Writer w)
Factory method for constructing |
| public JsonGenerator | createGenerator(File f, JsonEncoding enc)
Factory method for constructing |
| public JsonGenerator | createGenerator(Path path, JsonEncoding enc)
Factory method for constructing |
| public JsonGenerator | createGenerator(DataOutput out)
Factory method for constructing |
| public JsonParser | createNonBlockingByteArrayParser()
Factory method for constructing non-blocking |
| public JsonParser | createNonBlockingByteBufferParser()
Factory method for constructing non-blocking |
| public ObjectNode | createObjectNode()
Implements tools. Note return type is co-variant, as basic |
| public JsonParser | createParser(File src)
Factory method for constructing |
| public JsonParser | createParser(Path src)
Factory method for constructing |
| public JsonParser | createParser(InputStream in)
Factory method for constructing |
| public JsonParser | createParser(Reader r)
Factory method for constructing |
| public JsonParser | createParser(byte[] content)
Factory method for constructing |
| public JsonParser | createParser(byte[] content, int offset, int len)
Factory method for constructing |
| public JsonParser | createParser(String content)
Factory method for constructing |
| public JsonParser | createParser(char[] content)
Factory method for constructing |
| public JsonParser | createParser(char[] content, int offset, int len)
Factory method for constructing |
| public JsonParser | createParser(DataInput content)
Factory method for constructing |
| public DeserializationConfig | deserializationConfig()
Accessor for internal configuration object that contains settings for
deserialization operations ( Note Not to be used by application code; needed by some tests |
| public InjectableValues | |
| public JsonNodeFactory | getNodeFactory()
Method that can be used to get hold of |
| public TypeFactory | |
| public boolean | |
| public boolean | |
| public boolean | |
| public boolean | |
| public boolean | isEnabled(DeserializationFeature f)
Method for checking whether given deserialization-specific feature is enabled. |
| public boolean | isEnabled(SerializationFeature f)
Method for checking whether given serialization-specific feature is enabled. |
| public boolean | |
| public JsonNode | |
| public JsonNode | |
| public ObjectReader | |
| public ObjectReader | reader(DeserializationFeature feature)
Factory method for constructing |
| public ObjectReader | reader(DeserializationFeature first, DeserializationFeature... other)
Factory method for constructing |
| public ObjectReader | reader(DatatypeFeature feature)
Factory method for constructing |
| public ObjectReader | reader(JsonNodeFactory nodeFactory)
Factory method for constructing |
| public ObjectReader | reader(FormatSchema
Schema to pass to parser schema)Factory method for constructing |
| public ObjectReader | reader(InjectableValues
Injectable values to use injectableValues)Factory method for constructing |
| public ObjectReader | reader(Base64Variant defaultBase64)
Factory method for constructing |
| public ObjectReader | reader(ContextAttributes attrs)
Factory method for constructing |
| public ObjectReader | readerFor(JavaType type)
Factory method for constructing |
| public ObjectReader | readerFor(Class<?> type)
Factory method for constructing |
| public ObjectReader | readerFor(TypeReference<?> typeRef)
Factory method for constructing |
| public ObjectReader | readerForArrayOf(Class<?> type)
Factory method for constructing |
| public ObjectReader | readerForListOf(Class<?> type)
Factory method for constructing |
| public ObjectReader | readerForMapOf(Class<?> type)
Factory method for constructing
readerFor(new TypeReference<Map<String, type>>() { });
|
| public ObjectReader | readerForUpdating(Object valueToUpdate)
Factory method for constructing |
| public ObjectReader | readerWithView(Class<?> view)
Factory method for constructing |
| protected Object | |
| public JsonNode | Returns: aJsonNode, if valid JSON content found; null
if input has no content to bind -- note, however, that if
JSON null token is found, it will be represented
as a non-null JsonNode (one that returns true
for JsonNode#isNull()Implements tools. Method to deserialize JSON content as a tree |
| public JsonNode | Returns: aJsonNode, if valid JSON content found; null
if input has no content to bind -- note, however, that if
JSON null token is found, it will be represented
as a non-null JsonNode (one that returns true
for JsonNode#isNull()Input stream used to read JSON content
for building the JSON tree. in)Method to deserialize JSON content as tree expressed
using set of |
| public JsonNode | |
| public JsonNode | |
| public JsonNode | readTree(byte[] content)
Same as |
| public JsonNode | readTree(byte[] content, int offset, int len)
Same as |
| public JsonNode | |
| public JsonNode | |
| public JsonNode | readTree(TokenBuffer src)
Same as |
| public <T> T | readValue(JsonParser p, 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 |
| public <T> T | readValue(JsonParser p, TypeReference<T> valueTypeRef)
Method to deserialize JSON content into a Java type, reference to which is passed as argument. |
| public final <T> T | readValue(JsonParser p, ResolvedType valueType)
Method to deserialize JSON content into a Java type, reference to which is passed as argument. |
| public <T> T | readValue(JsonParser p, JavaType valueType)
Type-safe overloaded method, basically alias for |
| public <T> T | |
| public <T> T | readValue(File src, TypeReference<T> valueTypeRef)
Method to deserialize JSON content from given file into given Java type. |
| public <T> T | |
| public <T> T | |
| public <T> T | readValue(Path src, TypeReference<T> valueTypeRef)
Method to deserialize JSON content from given path into given Java type. |
| public <T> T | |
| public <T> T | |
| public <T> T | readValue(String content, TypeReference<T> valueTypeRef)
Method to deserialize JSON content from given JSON content String. |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> T | |
| public <T> MappingIterator | readValues(JsonParser p, JavaType valueType)
Convenience method, equivalent in function to: readerFor(valueType).readValues(p); |
| public <T> MappingIterator | readValues(JsonParser p, Class<T> valueType)
Convenience method, equivalent in function to: readerFor(valueType).readValues(p); |
| public <T> MappingIterator | |
| public <M extends ObjectMapper, B extends MapperBuilder | rebuild()
Method for creating a new |
| public Collection | registeredModules()
Method that may be used to find out |
| public SerializationConfig | serializationConfig()
Accessor for internal configuration object that contains settings for
serialization operations ( Note Not to be used by application code; needed by some tests |
| public JsonNode | |
| public TokenStreamFactory | Returns: TokenStreamFactory that this mapper uses when it needs to
construct Json parser and generatorsMethod that can be used to get hold of |
| public JsonParser | treeAsTokens(TreeNode
Root node of the tree that resulting parser will read from n)Implements tools. Method for constructing a |
| public <T> T | treeToValue(TreeNode n, Class<T> valueType)
Convenience conversion method that will bind data given JSON tree contains into specific value (usually bean) type. |
| public <T> T | treeToValue(TreeNode n, JavaType valueType)
Same as |
| public <T> T | treeToValue(TreeNode n, TypeReference<T> toValueTypeRef)
Same as |
| public <T> T | Returns: Either the first argument (`valueToUpdate`), if it is mutable; or a result of creating new instance that is result of "merging" values (for example, "updating" a Java array will create a new array)Object to update valueToUpdate, Object Object to conceptually serialize and merge into value to
update; can be thought of as a provider for overrides to apply. overrides)Convenience method similar to Implementation is approximately as follows:
|
| public < Actual node type; usually either basic T extends JsonNode> TJsonNode or
tools. | Returns: (non-null) Root node of the resulting content tree: in case ofnull value node for which JsonNode#isNull() returns true.Java value to convert fromValue)Method that is reverse of |
| public Version | version()
Implements tools. Method that will return version information stored in and read from jar that contains this class. |
| public ObjectWriter | |
| public ObjectWriter | writer(SerializationFeature feature)
Factory method for constructing |
| public ObjectWriter | writer(SerializationFeature first, SerializationFeature... other)
Factory method for constructing |
| public ObjectWriter | writer(DatatypeFeature f)
Factory method for constructing |
| public ObjectWriter | writer(DateFormat df)
Factory method for constructing |
| public ObjectWriter | writer(FilterProvider filterProvider)
Factory method for constructing |
| public ObjectWriter | writer(FormatSchema
Schema to pass to generator schema)Factory method for constructing |
| public ObjectWriter | writer(Base64Variant defaultBase64)
Factory method for constructing |
| public ObjectWriter | writer(CharacterEscapes escapes)
Factory method for constructing |
| public ObjectWriter | writer(ContextAttributes attrs)
Factory method for constructing |
| protected Object | |
| public ObjectWriter | writerFor(Class<?> rootType)
Factory method for constructing |
| public ObjectWriter | writerFor(TypeReference<?> rootType)
Factory method for constructing |
| public ObjectWriter | writerFor(JavaType rootType)
Factory method for constructing |
| public ObjectWriter | writerWithDefaultPrettyPrinter()
Factory method for constructing |
| public ObjectWriter | writerWithView(Class<?> serializationView)
Factory method for constructing |
| public void | |
| public void | writeValue(JsonGenerator g, Object value)
Method that can be used to serialize any Java value as
JSON output, using provided |
| public void | writeValue(File file, Object value)
Method that can be used to serialize any Java value as JSON output, written to File provided. |
| public void | writeValue(Path path, Object value)
Method that can be used to serialize any Java value as JSON output, written to Path provided. |
| public void | writeValue(OutputStream out, Object value)
Method that can be used to serialize any Java value as
JSON output, using output stream provided (using encoding
|
| public void | |
| public void | writeValue(Writer w, Object value)
Method that can be used to serialize any Java value as JSON output, using Writer provided. |
| public byte[] | |
| public String | |
| public TokenBuffer | writeValueIntoBuffer(Object value)
Convenience method that can be used to serialize any Java value into newly created
|