Skip to content

JacksonFeatures

Jump to bottom
Tatu Saloranta edited this page Apr 3, 2015 · 10 revisions

Jackson features

Features configurable via ObjectMapper, ObjectWriter and ObjectReader are divide into two main categories: high-level settings that affect jackson-databind components directly; and low-level settings that affect behavior of Streaming API behavior (JsonParser, JsonGenerator).

Databind features

For core databinding, features are divided further in 3 categories:

  • [Mapper features](Mapper Features)
  • [Serialization features](Serialization Features) (writing POJOs as JSON and other formats)
  • [Deserialization features](Deserialization Features) (reading JSON and other formats as POJOs)

Of these, Mapper Features can only be modified before using ObjectMapper: changes after use may or may not take effects. If you need different configured mapper (or ObjectWriter or ObjectReader), you will need a new mapper instance: you can do this with ObjectMapper.copy() -- it will copy current settings, but allow changes to Mapper Features.

Both Serialization and Deserialization features may, however, be configured by constructing new ObjectReader and ObjectWriter instances like so:

ObjectWriter w = mapper.write(SerializationFeature.WRAP_ROOT_VALUE);
ObjectWriter w2 = w.without(SerializationFeature.WRITE_DURATIONS_AS_TIMESTAMPS);
ObjectReader r = mapper.reader(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS);
ObjectReader r2 = r2.with(DeserializationFeature.USE_JAVA_ARRAY_FOR_JSON_ARRAY)
   .without(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);

Since both ObjectReader / ObjectWriter are immutable, methods will create new readers/writers and configuration is fully thread-safe. Cost of these instances is minimal (unlike cost of creating ObjectMappers, which is substantial) so while they may be freely shared and pooled, this is typically not necessary nor improve performance measurably.

Additional notes:

  • Most databind features do NOT affect Tree Model (JsonNode) since Tree Model is meant to be 1-to-1 representation of underlying physical content, and as such, minimal amount of converting is done on purpose.

Streaming API features

Similarly, low-level features are divided in 3 categories:

Similar to databind features, Factory Features may only be changed after constructing factory (either directly, or automatically via ObjectMapper), but before usage. Parser and Generator Features may be modified dynamically between calls, using ObjectReader and ObjectWriter methods similar to how Serialization and Deserialization features may be enabled and disabled.

Clone this wiki locally