Serialization features

Jackson on/off features: SerializationFeature

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

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 class name of the serialized instance (or value type if static typing used or root type specified); or, if using JAXB annotations, name from @XmlRootElement.
• INDENT_OUTPUT (default: false)
  • Controls whether output is indented using the default indentation ("pretty-printing") mechanism (2-space, platform linefeeds) or not.

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 beconvenient 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}}}
• SORT_PROPERTIES_ALPHABETICALLY (default: false)
  • Controls default ordering used for serializing POJO fields (note: does NOT apply to Maps!): if enabled, default ordering is alphabetic (similar to how {{{@JsonPropertyOrder.alphabetic=true}}} works; if disabled, default order is unspecified.
  • Note that explicit ordering annotations on type (class) override default settings.
• DEFAULT_VIEW_INCLUSION (default: true)
  • Controls what is the behavior of properties that have no matching {{{JsonView}}} annotation: if set to true, they are included in all views; if false, not included in any views. This only affects JacksonJsonView enabled processing (i.e. when Serialization View is specified)
• 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_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: true)
  • 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.

Other

• EAGER_SERIALIZER_FETCH (default: true)
  • 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.