Skip to content

Deserialization Features

Jump to bottom
cowtowncoder edited this page Apr 9, 2013 · 27 revisions

Jackson on/off features: DeserializationFeature

Jackson defines a set of features that relate to deserialization (reading JSON into Java Objects), and that can be changed on per-call basis.

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

Conversions

  • USE_BIG_DECIMAL_FOR_FLOATS (default: false)
    • Controls whether {{{java.math.BigDecimal}}} is used for deserializing {{{JSON}}} floating point numbers, when resulting type is a generic type ({{{java.lang.Object}}}) or generic number type ({{{java.lang.Number}}}); if disabled type will be {{{java.lang.Double}}}
    • Does not affect explicit type (i.e. if expected result type is {{{java.lang.Double}}} or such)
  • USE_BIG_INTEGER_FOR_INTS (default: false)
    • Similar to {{{USE_BIG_DECIMAL_FOR_FLOATS}}}, but used when value to map is a JSON integer number (numeric value without decimal point). If enabled, type {{{java.math.BigInteger}}} is used for binding to generic types; if disabled, {{{java.lang.Integer}}} or {{{java.lang.Long}}} is used (smallest applicable type that can contain actual value)
  • USE_JAVA_ARRAY_FOR_JSON_ARRAY (default: false) (since JacksonRelease19)
    • Determines whether to bind JSON Arrays as {{{java.util.Lists}}} or {{{Object[]}}} instances, when binding to nominal type of {{{java.lang.Object}}}: if disabled, as {{{List}}}, if enabled as {{{Object[]}}}.
  • READ_ENUMS_USING_TO_STRING (default: false) (since JacksonRelease16)
    • Determines which method is used to determine expected serialization of an Enum: if false (default), use {{{Enum.name()}}}; if true, {{{Enum.toString()}}}.

Failure handling

  • FAIL_ON_UNKNOWN_PROPERTIES (default: true) (since JacksonRelease12)
  • Used to control whether encountering of unknown properties (one for which there is no setter; and there is no fallback "any setter" method defined using {{{@JsonAnySetter}}} annotation) should result in a {{{JsonMappingException}}} (when enabled), or just quietly ignored (when disabled)
  • FAIL_ON_NULL_FOR_PRIMITIVES (default: false) (since JacksonRelease17)
  • Determines whether JSON null is acceptable for Java primitive types ({{{int}}}, {{{boolean}}}, {{{double}}} etc); if set to 'false', default value is used; if 'true', a {{{JsonProcessingException}}} will be thrown.
  • FAIL_ON_NUMBERS_FOR_ENUMS (default: false) (since JacksonRelease17)
  • Determines whether JSON integer numbers (0, 1, 2, ...) can be deserialized into Java Enum types; if set to 'false', this is legal and value is used to deserialize value that matches Enum.ordinal(); if 'true', trying to deserialize JSON number into Enum throws a {{{JsonProcessingException}}}
  • FAIL_ON_INVALID_SUBTYPE (default: true) (since [[JacksonRelease22 | 2.2])
  • Determines what happens when type information for polymorphic types (see @JsonTypeInfo) is either missing or invalid (unmappable); if enabled, exception is thrown; if disabled, null reference is used instead (as type can not be determined).

Value conversions

  • ACCEPT_EMPTY_STRING_AS_NULL_OBJECT (default: false)
    • Determines whether empty JSON String value is accepted as null value for regular POJOs ("beans") with data-binding: this can be useful when dealing endpoints written in a language that has loose typing and may represent missing objects as Empty Strings.
  • READ_UNKNOWN_ENUM_VALUES_AS_NULL (default: false)
    • Feature that allows unknown Enum values to be parsed as Java null values. If disabled, unknown Enum values will throw exceptions.
    • Note that in some cases this will basically ignore unknown Enum values; this is the keys for keys of java.util.EnumMap and values of java.util.EnumSet (because nulls are not accepted in these cases.

Structural conversions

  • ACCEPT_SINGLE_VALUE_AS_ARRAY (default: false)
    • Allows auto-conversion from non-JSON-array values to single-element arrays and Collections (adding implicit "array wrapper"): this is sometimes necessary for interoperability, as some libraries and frameworks omit JSON arrays when serializing single-element arrays.
  • UNWRAP_ROOT_VALUE (default: false)
    • Feature to allow "unwrapping" root-level JSON value, to match setting of SerializationFeature#WRAP_ROOT_VALUE used for serialization.
    • Will verify that the root JSON value is a JSON Object, and that it has a single property with expected root name. If not, a JsonMappingException is thrown; otherwise value of the wrapped property will be deserialized as if it was the root value.
Clone this wiki locally