Serialization features

Jackson on/off features: SerializationFeature

Jackson defines a set of features that relate to serialization (writing Java objects as JSON), and that can be changed on per-call basis (by using ObjectWriter). For example:

final ObjectWriter w = objectMapper.writer();
// enable one feature, disable another
byte[] json = w
  .with(SerializationFeature.INDENT_OUTPUT)
  .without(FAIL_ON_EMPTY_BEANS.WRAP_EXCEPTIONS)
  .writeValueAsBytes(value);

You can also change defaults for ObjectMapper, to be used as the base for all ObjectWriter instances, using enable(feature), disable(feature) and configure(feature, state) methods.

Settings can be divided in couple of loose categories, as follows.

Generic output features

• WRAP_ROOT_VALUE (default: false)
  • When enabled, will wrap output in a single-property JSON Object. Name of wrapper property is based on one of:
    • @JsonRootName annotation value, or
    • @XmlRootElement if (and only if) using JAXB Annotations, or
    • Simple Class name (no package prefix) of the serialized instance (or value type if static typing used or root type specified), if no annotation is specified.
  • Note that this settings does NOT have effect when writing XML since XML ALWAYS requires separate root element (true for Jackson versions 2.3 and later)
• INDENT_OUTPUT (default: false)
  • Controls whether output is indented using the default indentation ("pretty-printing") mechanism (2-space, platform linefeeds) or not.
  • NOTE: not all data formats support indentation: binary formats do not have the concept (they are not human-readable); and CSV has flat structure and can not be "prettified"

Error handling

• FAIL_ON_EMPTY_BEANS (default: true)
  • Controls whether exception is thrown if no serializer is found for a type (Class); and type has neither getters nor recognized annotations (ones configured AnnotationIntrospector recognizes, including JAXB Annotations if JAXB introspector used).
• WRAP_EXCEPTIONS (default: true)
  • Feature that determines whether Jackson code should catch and wrap Exceptions (but never Errors) to add additional information about location (within input) of problem or not.
  • If enabled, most exceptions will be caught and re-thrown (exception specifically being thatjava.io.IOExceptions may be passed as-is, since they are declared as throwable); this can be convenient both in that all exceptions will be checked and declared, and so there is more contextual information. However, sometimes calling application may just want "raw" unchecked exceptions passed as is.

Output life-cycle features

• CLOSE_CLOSEABLE (default: false)
  • If enabled, ObjectMapper will call close() and root values that implement java.io.Closeable; including cases where exception is thrown and serialization does not completely succeed.
  • Can be useful for resource clean up; and specifically allows for building wrappers that can be useful when serializing referential values (like, say, serializing a {{{java.io.File}}} value by reading contents of a file and outputting as JSON String or base64-encoded binary)
• FLUSH_AFTER_WRITE_VALUE (default: true)
  • Determines whether JsonGenerator.flush() is automatically called after ObjectMappers writeValue(JsonGenerator, ...) is called or not (note: does NOT affect methods that do not take JsonGenerator) -- if true flush() is called; if false, it is not called.
  • Main reason to disable this feature is performance; for network connections flushing may send message earlier than optimal, and with some compressing streams compression block may complete with flush().

Datatype-specific serialization

• WRITE_DATES_AS_TIMESTAMPS (default: true)
  • Controls whether Date / Time values are to be written out as numeric (64-bit) timestamps (if true) or as Strings. If latter, format used is defined by SerializationConfig.getDateFormat
• WRITE_DATE_KEYS_AS_TIMESTAMPS (default: false)
  • Feature that determines whether java.util.Dates (and sub-types) used as java.util.Map keys are serialized as timestamps or not. If not, will be serialized as textual (ISO-8601) values.
• WRITE_CHAR_ARRAYS_AS_JSON_ARRAYS (default: false)
  • Controls how basic char[] values are serialized: if enabled, they will be serialized as full JSON Arrays, with JSON Strings (of length 1 character) as elements; if disabled (which is the default) as a single JSON String consisting of all characters of the array.
• WRITE_ENUMS_USING_TO_STRING (default: false)
  • Determines which method is used to determine expected serialization of an Enum (when serialized as String): if false (default), use Enum.name(); if true, Enum.toString().
• WRITE_ENUMS_USING_INDEX (default: false)
  • Determines whether Enums are to be serialized as integers (true), or Strings (false): if integers, Enum.ordinal() value is used as serialization.
• WRITE_NULL_MAP_VALUES (default: true)
  • Determines whether Map entries with value null are serialized or not.
• WRITE_EMPTY_JSON_ARRAYS (default: true)
  • Allows suppressing serialization of empty Collections/arrays.
• WRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED (default: false)
  • Feature to change handling of single-element Arrays, java.util.Collections, so that such arrays/collections are serialized as "unwrapped" elements, not as JSON Arrays.
• WRITE_BIGDECIMAL_AS_PLAIN (default: false) (since Jackson 2.2)
  • If enabled, will prevent use of scientific notation (use of 'e' in value to normalize scale of mantisaa); if disabled, will use scientific notation when necessary.
• WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS (default: false) (since Jackson 2.2)
  • Feature that controls whether numeric timestamp values are expected to be written using nanosecond timestamps (enabled) or not (disabled); if disabled, standard millisecond timestamps are assumed.
• ORDER_MAP_ENTRIES_BY_KEYS (default: false)
  • Feature that determines whether java.util.Map entries are first sorted by key before serialization or not: if enabled, additional sorting step is performed if necessary (not necessary for java.util.SortedMaps), if disabled, no additional sorting is needed.

Other

• EAGER_SERIALIZER_FETCH (default: true) (since Jackson 2.1)
  • Feature that determines whether ObjectWriter should try to eagerly fetch necessary JsonSerializer when possible. This improves performance in cases where similarly configured ObjectWriter instance is used multiple times; and should not significantly affect single-use cases.
  • There should not be any need to normally disable this feature: only consider that if there are actual perceived problems.
• USE_EQUALITY_FOR_OBJECT_ID (default: false) (since Jackson 2.3)
  • Feature that determines whether Object Identity is compared using true JVM-level identity of Object (false); or, equals() method.
  • Setting this to true (to use equals()) is sometimes useful when dealing with Database-bound objects with ORM libraries like Hibernate.