public enum DeserializationFeature extends Enum<DeserializationFeature> implements ConfigFeature
Note that features can be set both through
ObjectMapper
(as sort of defaults) and through
ObjectReader
.
In first case these defaults must follow "config-then-use" patterns
(i.e. defined once, not changed afterwards); all per-call
changes must be done using ObjectReader
.
Note that features that do not indicate version of inclusion were available in Jackson 2.0 (or earlier); only later additions indicate version of inclusion.
Enum Constant and Description |
---|
ACCEPT_EMPTY_ARRAY_AS_NULL_OBJECT
Feature that can be enabled to allow empty JSON Array
value (that is,
[ ] ) to be bound to POJOs (and
with 2.9, other values too) as `null`. |
ACCEPT_EMPTY_STRING_AS_NULL_OBJECT
Feature that can be enabled to allow JSON empty String
value ("") to be bound as `null` for POJOs and other structured
values (
Map s, Collection s). |
ACCEPT_FLOAT_AS_INT
Feature that determines whether coercion from JSON floating point
number (anything with command (`.`) or exponent portion (`e` / `E'))
to an expected integral number (`int`, `long`, `java.lang.Integer`, `java.lang.Long`,
`java.math.BigDecimal`) is allowed or not.
|
ACCEPT_SINGLE_VALUE_AS_ARRAY
Feature that determines whether it is acceptable to coerce non-array
(in JSON) values to work with Java collection (arrays, java.util.Collection)
types.
|
ADJUST_DATES_TO_CONTEXT_TIME_ZONE
Feature that specifies whether context provided
TimeZone
(DeserializationContext.getTimeZone() should be used to adjust Date/Time
values on deserialization, even if value itself contains timezone information. |
EAGER_DESERIALIZER_FETCH
Feature that determines whether
ObjectReader should
try to eagerly fetch necessary JsonDeserializer when
possible. |
FAIL_ON_IGNORED_PROPERTIES
Feature that determines what happens when a property that has been explicitly
marked as ignorable is encountered in input: if feature is enabled,
JsonMappingException is thrown; if false, property is quietly skipped. |
FAIL_ON_INVALID_SUBTYPE
Feature that determines what happens when type of a polymorphic
value (indicated for example by
JsonTypeInfo )
cannot be found (missing) or resolved (invalid class name, non-mappable id);
if enabled, an exception is thrown; if false, null value is used instead. |
FAIL_ON_MISSING_CREATOR_PROPERTIES
Feature that determines what happens if one or more Creator properties (properties
bound to parameters of Creator method (constructor or static factory method))
are missing value to bind to from content.
|
FAIL_ON_MISSING_EXTERNAL_TYPE_ID_PROPERTY
Feature that determines what happens when a property annotated with
JsonTypeInfo.As.EXTERNAL_PROPERTY is missing,
but associated type id is available. |
FAIL_ON_NULL_CREATOR_PROPERTIES
Feature that determines what happens if one or more Creator properties (properties
bound to parameters of Creator method (constructor or static factory method))
are bound to null values - either from the JSON or as a default value.
|
FAIL_ON_NULL_FOR_PRIMITIVES
Feature that determines whether encountering of JSON null
is an error when deserializing into Java primitive types
(like 'int' or 'double').
|
FAIL_ON_NUMBERS_FOR_ENUMS
Feature that determines whether JSON integer numbers are valid
values to be used for deserializing Java enum values.
|
FAIL_ON_READING_DUP_TREE_KEY
Feature that determines what happens when reading JSON content into tree
(
TreeNode ) and a duplicate key
is encountered (property name that was already seen for the JSON Object). |
FAIL_ON_TRAILING_TOKENS
Feature that determines behaviour for data-binding after binding the root value.
|
FAIL_ON_UNKNOWN_PROPERTIES
Feature that determines whether encountering of unknown
properties (ones that do not map to a property, and there is
no "any setter" or handler that can handle it)
should result in a failure (by throwing a
JsonMappingException ) or not. |
FAIL_ON_UNRESOLVED_OBJECT_IDS
Feature that determines what happens if an Object Id reference is encountered
that does not refer to an actual Object with that id ("unresolved Object Id"):
either an exception
UnresolvedForwardReference
containing information about UnresolvedId
is thrown (true ), or a null object is used instead (false ). |
READ_DATE_TIMESTAMPS_AS_NANOSECONDS
Feature that controls whether numeric timestamp values are expected
to be written using nanosecond timestamps (enabled) or not (disabled),
if and only if datatype supports such resolution.
|
READ_ENUMS_USING_TO_STRING
Feature that determines standard deserialization mechanism used for
Enum values: if enabled, Enums are assumed to have been serialized using
return value of
Enum.toString() ;
if disabled, return value of Enum.name() is assumed to have been used. |
READ_UNKNOWN_ENUM_VALUES_AS_NULL
Feature that allows unknown Enum values to be parsed as
null values. |
READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE
Feature that allows unknown Enum values to be ignored and replaced by a predefined value specified through
@JsonEnumDefaultValue annotation. |
UNWRAP_ROOT_VALUE
Feature to allow "unwrapping" root-level JSON value, to match setting of
SerializationFeature.WRAP_ROOT_VALUE used for serialization. |
UNWRAP_SINGLE_VALUE_ARRAYS
Feature that determines whether it is acceptable to coerce single value array (in JSON)
values to the corresponding value type.
|
USE_BIG_DECIMAL_FOR_FLOATS
Feature that determines whether JSON floating point numbers
are to be deserialized into
BigDecimal s
if only generic type description (either Object or
Number , or within untyped Map
or Collection context) is available. |
USE_BIG_INTEGER_FOR_INTS
Feature that determines whether JSON integral (non-floating-point)
numbers are to be deserialized into
BigInteger s
if only generic type description (either Object or
Number , or within untyped Map
or Collection context) is available. |
USE_JAVA_ARRAY_FOR_JSON_ARRAY
Feature that determines whether JSON Array is mapped to
Object[] or List<Object> when binding
"untyped" objects (ones with nominal type of java.lang.Object ). |
USE_LONG_FOR_INTS
Feature that determines how "small" JSON integral (non-floating-point)
numbers -- ones that fit in 32-bit signed integer (`int`) -- are bound
when target type is loosely typed as
Object or Number
(or within untyped Map or Collection context). |
WRAP_EXCEPTIONS
|
Modifier and Type | Method and Description |
---|---|
boolean |
enabledByDefault()
Accessor for checking whether this feature is enabled by default.
|
boolean |
enabledIn(int flags)
Convenience method for checking whether feature is enabled in given bitmask
|
int |
getMask()
Returns bit mask for this feature instance
|
static DeserializationFeature |
valueOf(String name)
Returns the enum constant of this type with the specified name.
|
static DeserializationFeature[] |
values()
Returns an array containing the constants of this enum type, in
the order they are declared.
|
public static final DeserializationFeature USE_BIG_DECIMAL_FOR_FLOATS
BigDecimal
s
if only generic type description (either Object
or
Number
, or within untyped Map
or Collection
context) is available.
If enabled such values will be deserialized as BigDecimal
s;
if disabled, will be deserialized as Double
s.
NOTE: one aspect of BigDecimal
handling that may need
configuring is whether trailing zeroes are trimmed:
JsonNodeFactory
has
JsonNodeFactory.withExactBigDecimals(boolean)
for
changing default behavior (default is for trailing zeroes to be trimmed).
Feature is disabled by default, meaning that "untyped" floating
point numbers will by default be deserialized as Double
s
(choice is for performance reason -- BigDecimals are slower than
Doubles).
public static final DeserializationFeature USE_BIG_INTEGER_FOR_INTS
BigInteger
s
if only generic type description (either Object
or
Number
, or within untyped Map
or Collection
context) is available.
If enabled such values will be deserialized as
BigInteger
s;
if disabled, will be deserialized as "smallest" available type,
which is either Integer
, Long
or
BigInteger
, depending on number of digits.
Feature is disabled by default, meaning that "untyped" integral numbers will by default be deserialized using whatever is the most compact integral type, to optimize efficiency.
public static final DeserializationFeature USE_LONG_FOR_INTS
Object
or Number
(or within untyped Map
or Collection
context).
If enabled, such values will be deserialized as Long
;
if disabled, they will be deserialized as "smallest" available type,
Integer
.
Note: if USE_BIG_INTEGER_FOR_INTS
is enabled, it has precedence
over this setting, forcing use of BigInteger
for all
integral values.
Feature is disabled by default, meaning that "untyped" integral
numbers will by default be deserialized using Integer
if value fits.
public static final DeserializationFeature USE_JAVA_ARRAY_FOR_JSON_ARRAY
Object[]
or List<Object>
when binding
"untyped" objects (ones with nominal type of java.lang.Object
).
If true, binds as Object[]
; if false, as List<Object>
.
Feature is disabled by default, meaning that JSON arrays are bound as
List
s.
public static final DeserializationFeature FAIL_ON_UNKNOWN_PROPERTIES
JsonMappingException
) or not.
This setting only takes effect after all other handling
methods for unknown properties have been tried, and
property remains unhandled.
Feature is enabled by default (meaning that a
JsonMappingException
will be thrown if an unknown property
is encountered).
public static final DeserializationFeature FAIL_ON_NULL_FOR_PRIMITIVES
InvalidNullException
is thrown to indicate this; if not, default value is used
(0 for 'int', 0.0 for double, same defaulting as what JVM uses).
Feature is disabled by default.
public static final DeserializationFeature FAIL_ON_NUMBERS_FOR_ENUMS
JsonMappingException
will be thrown.
Latter behavior makes sense if there is concern that accidental
mapping from integer values to enums might happen (and when enums
are always serialized as JSON Strings)
Feature is disabled by default.
public static final DeserializationFeature FAIL_ON_INVALID_SUBTYPE
JsonTypeInfo
)
cannot be found (missing) or resolved (invalid class name, non-mappable id);
if enabled, an exception is thrown; if false, null value is used instead.
Feature is enabled by default so that exception is thrown for missing or invalid type information.
public static final DeserializationFeature FAIL_ON_READING_DUP_TREE_KEY
TreeNode
) and a duplicate key
is encountered (property name that was already seen for the JSON Object).
If enabled, JsonMappingException
will be thrown; if disabled, no exception
is thrown and the new (later) value overwrites the earlier value.
Note that this property does NOT affect other aspects of data-binding; that is,
no detection is done with respect to POJO properties or Map
keys. New features may be added to control additional cases.
Feature is disabled by default so that no exception is thrown.
public static final DeserializationFeature FAIL_ON_IGNORED_PROPERTIES
JsonMappingException
is thrown; if false, property is quietly skipped.
Feature is disabled by default so that no exception is thrown.
public static final DeserializationFeature FAIL_ON_UNRESOLVED_OBJECT_IDS
UnresolvedForwardReference
containing information about UnresolvedId
is thrown (true
), or a null object is used instead (false
).
Note that if this is set to false
, no further processing is done;
specifically, if reference is defined via setter method, that method will NOT
be called.
Feature is enabled by default, so that unknown Object Ids will result in an exception being thrown, at the end of deserialization.
public static final DeserializationFeature FAIL_ON_MISSING_CREATOR_PROPERTIES
JsonMappingException
being
thrown with information on the first one (by index) of missing properties.
If disabled, and if property is NOT marked as required,
missing Creator properties are filled
with null values
provided by deserializer for the type of parameter
(usually null for Object types, and default value for primitives; but redefinable
via custom deserializers).
Note that having an injectable value counts as "not missing".
Feature is disabled by default, so that no exception is thrown for missing creator property values, unless they are explicitly marked as `required`.
public static final DeserializationFeature FAIL_ON_NULL_CREATOR_PROPERTIES
public static final DeserializationFeature FAIL_ON_MISSING_EXTERNAL_TYPE_ID_PROPERTY
JsonTypeInfo.As.EXTERNAL_PROPERTY
is missing,
but associated type id is available. If enabled, JsonMappingException
is always
thrown when property value is missing (if type id does exist);
if disabled, exception is only thrown if property is marked as `required`.
Feature is enabled by default, so that exception is thrown when a subtype property is missing.
public static final DeserializationFeature FAIL_ON_TRAILING_TOKENS
JsonParser.nextToken()
is made to ensure that
no more tokens are found (and if any is found,
MismatchedInputException
is thrown); if
disabled, no further checks are made.
Feature could alternatively be called READ_FULL_STREAM
, since it
effectively verifies that input stream contains only as much data as is needed
for binding the full value, and nothing more (except for possible ignorable
white space or comments, if supported by data format).
Feature is disabled by default (so that no check is made for possible trailing token(s)) for backwards compatibility reasons.
public static final DeserializationFeature WRAP_EXCEPTIONS
Exception
s (but never Error
s!)
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 that IOException
s 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.
NOTE: most of the time exceptions that may or may not be wrapped are of
type RuntimeException
: as mentioned earlier, various
IOException
s (and in particular
JacksonException
s) will
always be passed as-is.
Feature is enabled by default.
public static final DeserializationFeature ACCEPT_SINGLE_VALUE_AS_ARRAY
Feature is disabled by default.
public static final DeserializationFeature UNWRAP_SINGLE_VALUE_ARRAYS
ACCEPT_SINGLE_VALUE_AS_ARRAY
feature. If more than one value is found in the array, a JsonMappingException is thrown.
NOTE: only single wrapper Array is allowed: if multiple attempted, exception will be thrown. Feature is disabled by default.
public static final DeserializationFeature UNWRAP_ROOT_VALUE
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.
Feature is disabled by default.
public static final DeserializationFeature ACCEPT_EMPTY_STRING_AS_NULL_OBJECT
Map
s, Collection
s).
If disabled, standard POJOs can only be bound from JSON `null` or
JSON Object (standard meaning that no custom deserializers or
constructors are defined; both of which can add support for other
kinds of JSON values); if enabled, empty JSON String can be taken
to be equivalent of JSON null.
NOTE: this does NOT apply to scalar values such as booleans and numbers;
whether they can be coerced depends on
MapperFeature.ALLOW_COERCION_OF_SCALARS
.
IMPORTANT: This feature might work even when an empty string ""
may be a valid value for some types.
Feature is disabled by default.
public static final DeserializationFeature ACCEPT_EMPTY_ARRAY_AS_NULL_OBJECT
[ ]
) to be bound to POJOs (and
with 2.9, other values too) as `null`.
If disabled, standard POJOs can only be bound from JSON `null` or
JSON Object (standard meaning that no custom deserializers or
constructors are defined; both of which can add support for other
kinds of JSON values); if enabled, empty JSON Array will be taken
to be equivalent of JSON null.
Feature is disabled by default.
public static final DeserializationFeature ACCEPT_FLOAT_AS_INT
JsonMappingException
will be thrown.
Feature is enabled by default.
public static final DeserializationFeature READ_ENUMS_USING_TO_STRING
Enum.toString()
;
if disabled, return value of Enum.name()
is assumed to have been used.
Note: this feature should usually have same value
as SerializationFeature.WRITE_ENUMS_USING_TO_STRING
.
Feature is disabled by default.
public static final DeserializationFeature READ_UNKNOWN_ENUM_VALUES_AS_NULL
null
values.
If disabled, unknown Enum values will throw exceptions.
Note that in some cases this will effectively ignore unknown Enum
values,
e.g. when the unknown values are used as keys of EnumMap
or values of EnumSet
: this is because these data structures cannot
store null
values.
Also note that this feature has lower precedence than
READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE
,
meaning this feature will work only if latter feature is disabled.
Feature is disabled by default.
public static final DeserializationFeature READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE
@JsonEnumDefaultValue
annotation.
If disabled, unknown Enum values will throw exceptions.
If enabled, but no predefined default Enum value is specified, an exception will be thrown as well.
Note that this feature has higher precedence than READ_UNKNOWN_ENUM_VALUES_AS_NULL
.
Feature is disabled by default.
public static final DeserializationFeature READ_DATE_TIMESTAMPS_AS_NANOSECONDS
If disabled, standard millisecond timestamps are assumed.
This is the counterpart to SerializationFeature.WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS
.
Feature is enabled by default, to support most accurate time values possible.
public static final DeserializationFeature ADJUST_DATES_TO_CONTEXT_TIME_ZONE
TimeZone
(DeserializationContext.getTimeZone()
should be used to adjust Date/Time
values on deserialization, even if value itself contains timezone information.
If enabled, contextual TimeZone
will essentially override any other
TimeZone information; if disabled, it will only be used if value itself does not
contain any TimeZone information.
Note that exact behavior depends on date/time types in question; and specifically
JDK type of Date
does NOT have in-built timezone information
so this setting has no effect.
Further, while Calendar
does have this information basic
JDK SimpleDateFormat
is unable to retain parsed zone information,
and as a result, Calendar
will always get context timezone
adjustment regardless of this setting.
Taking above into account, this feature is supported only by extension modules for Joda and Java 8 date/time datatypes.
public static final DeserializationFeature EAGER_DESERIALIZER_FETCH
ObjectReader
should
try to eagerly fetch necessary JsonDeserializer
when
possible. This improves performance in cases where similarly
configured ObjectReader
instance is used multiple
times; and should not significantly affect single-use cases.
Note that there should not be any need to normally disable this feature: only consider that if there are actual perceived problems.
Feature is enabled by default.
public static DeserializationFeature[] values()
for (DeserializationFeature c : DeserializationFeature.values()) System.out.println(c);
public static DeserializationFeature valueOf(String name)
name
- the name of the enum constant to be returned.IllegalArgumentException
- if this enum type has no constant with the specified nameNullPointerException
- if the argument is nullpublic boolean enabledByDefault()
ConfigFeature
enabledByDefault
in interface ConfigFeature
public int getMask()
ConfigFeature
getMask
in interface ConfigFeature
public boolean enabledIn(int flags)
ConfigFeature
enabledIn
in interface ConfigFeature
Copyright © 2008–2023 FasterXML. All rights reserved.