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.

Value 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.Integerorjava.lang.Long` is used (smallest applicable type that can contain actual value)
  • USE_JAVA_ARRAY_FOR_JSON_ARRAY (default: false)
    • 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 java.util.List, if enabled as Object[].
  • READ_ENUMS_USING_TO_STRING (default: false)
    • Determines which method is used to determine expected serialization of an Enum: if false (default), use Enum.name(); if true, Enum.toString().
  • 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.

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).

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