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, by using ObjectReader. You can also change defaults for ObjectMapper, to be used as the base for all ObjectReader instances.

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.
  • READ_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.

Failure handling

  • FAIL_ON_UNKNOWN_PROPERTIES (default: true)
    • 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)
    • 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)
    • 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 Jackson 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