1 package com.fasterxml.jackson.databind;
2
3 import com.fasterxml.jackson.databind.cfg.ConfigFeature;
4
5 /**
6 * Enumeration that defines simple on/off features that affect
7 * the way Java objects are deserialized from JSON
8 *<p>
9 * Note that features can be set both through
10 * {@link ObjectMapper} (as sort of defaults) and through
11 * {@link ObjectReader}.
12 * In first case these defaults must follow "config-then-use" patterns
13 * (i.e. defined once, not changed afterwards); all per-call
14 * changes must be done using {@link ObjectReader}.
15 *<p>
16 * Note that features that do not indicate version of inclusion
17 * were available in Jackson 2.0 (or earlier); only later additions
18 * indicate version of inclusion.
19 */
20 public enum DeserializationFeature implements ConfigFeature
21 {
22 /*
23 /******************************************************
24 /* Value (mostly scalar) conversion features
25 /******************************************************
26 */
27
28 /**
29 * Feature that determines whether JSON floating point numbers
30 * are to be deserialized into {@link java.math.BigDecimal}s
31 * if only generic type description (either {@link Object} or
32 * {@link Number}, or within untyped {@link java.util.Map}
33 * or {@link java.util.Collection} context) is available.
34 * If enabled such values will be deserialized as {@link java.math.BigDecimal}s;
35 * if disabled, will be deserialized as {@link Double}s.
36 *<p>
37 * NOTE: one aspect of {@link java.math.BigDecimal} handling that may need
38 * configuring is whether trailing zeroes are trimmed:
39 * {@link com.fasterxml.jackson.databind.node.JsonNodeFactory} has
40 * {@link com.fasterxml.jackson.databind.node.JsonNodeFactory#withExactBigDecimals} for
41 * changing default behavior (default is for trailing zeroes to be trimmed).
42 *<p>
43 * Feature is disabled by default, meaning that "untyped" floating
44 * point numbers will by default be deserialized as {@link Double}s
45 * (choice is for performance reason -- BigDecimals are slower than
46 * Doubles).
47 */
48 USE_BIG_DECIMAL_FOR_FLOATS(false),
49
50 /**
51 * Feature that determines whether JSON integral (non-floating-point)
52 * numbers are to be deserialized into {@link java.math.BigInteger}s
53 * if only generic type description (either {@link Object} or
54 * {@link Number}, or within untyped {@link java.util.Map}
55 * or {@link java.util.Collection} context) is available.
56 * If enabled such values will be deserialized as
57 * {@link java.math.BigInteger}s;
58 * if disabled, will be deserialized as "smallest" available type,
59 * which is either {@link Integer}, {@link Long} or
60 * {@link java.math.BigInteger}, depending on number of digits.
61 * <p>
62 * Feature is disabled by default, meaning that "untyped" integral
63 * numbers will by default be deserialized using whatever
64 * is the most compact integral type, to optimize efficiency.
65 */
66 USE_BIG_INTEGER_FOR_INTS(false),
67
68 /**
69 * Feature that determines how "small" JSON integral (non-floating-point)
70 * numbers -- ones that fit in 32-bit signed integer (`int`) -- are bound
71 * when target type is loosely typed as {@link Object} or {@link Number}
72 * (or within untyped {@link java.util.Map} or {@link java.util.Collection} context).
73 * If enabled, such values will be deserialized as {@link java.lang.Long};
74 * if disabled, they will be deserialized as "smallest" available type,
75 * {@link Integer}.
76 * In addition, if enabled, trying to bind values that do not fit in {@link java.lang.Long}
77 * will throw a {@link com.fasterxml.jackson.core.JsonProcessingException}.
78 *<p>
79 * Note: if {@link #USE_BIG_INTEGER_FOR_INTS} is enabled, it has precedence
80 * over this setting, forcing use of {@link java.math.BigInteger} for all
81 * integral values.
82 *<p>
83 * Feature is disabled by default, meaning that "untyped" integral
84 * numbers will by default be deserialized using {@link java.lang.Integer}
85 * if value fits.
86 *
87 * @since 2.6
88 */
89 USE_LONG_FOR_INTS(false),
90
91 /**
92 * Feature that determines whether JSON Array is mapped to
93 * <code>Object[]</code> or {@code List<Object>} when binding
94 * "untyped" objects (ones with nominal type of <code>java.lang.Object</code>).
95 * If true, binds as <code>Object[]</code>; if false, as {@code List<Object>}.
96 *<p>
97 * Feature is disabled by default, meaning that JSON arrays are bound as
98 * {@link java.util.List}s.
99 */
100 USE_JAVA_ARRAY_FOR_JSON_ARRAY(false),
101
102 /*
103 /******************************************************
104 /* Error handling features
105 /******************************************************
106 */
107
108 /**
109 * Feature that determines whether encountering of unknown
110 * properties (ones that do not map to a property, and there is
111 * no "any setter" or handler that can handle it)
112 * should result in a failure (by throwing a
113 * {@link JsonMappingException}) or not.
114 * This setting only takes effect after all other handling
115 * methods for unknown properties have been tried, and
116 * property remains unhandled.
117 *<p>
118 * Feature is enabled by default (meaning that a
119 * {@link JsonMappingException} will be thrown if an unknown property
120 * is encountered).
121 */
122 FAIL_ON_UNKNOWN_PROPERTIES(true),
123
124 /**
125 * Feature that determines whether encountering of JSON null
126 * is an error when deserializing into Java primitive types
127 * (like 'int' or 'double'). If it is, a JsonProcessingException
128 * is thrown to indicate this; if not, default value is used
129 * (0 for 'int', 0.0 for double, same defaulting as what JVM uses).
130 *<p>
131 * Feature is disabled by default.
132 */
133 FAIL_ON_NULL_FOR_PRIMITIVES(false),
134
135 /**
136 * Feature that determines whether JSON integer numbers are valid
137 * values to be used for deserializing Java enum values.
138 * If set to 'false' numbers are acceptable and are used to map to
139 * ordinal() of matching enumeration value; if 'true', numbers are
140 * not allowed and a {@link JsonMappingException} will be thrown.
141 * Latter behavior makes sense if there is concern that accidental
142 * mapping from integer values to enums might happen (and when enums
143 * are always serialized as JSON Strings)
144 *<p>
145 * Feature is disabled by default.
146 */
147 FAIL_ON_NUMBERS_FOR_ENUMS(false),
148
149 /**
150 * Feature that determines what happens when type of a polymorphic
151 * value (indicated for example by {@link com.fasterxml.jackson.annotation.JsonTypeInfo})
152 * cannot be found (missing) or resolved (invalid class name, unmappable id);
153 * if enabled, an exception ir thrown; if false, null value is used instead.
154 *<p>
155 * Feature is enabled by default so that exception is thrown for missing or invalid
156 * type information.
157 *
158 * @since 2.2
159 */
160 FAIL_ON_INVALID_SUBTYPE(true),
161
162 /**
163 * Feature that determines what happens when reading JSON content into tree
164 * ({@link com.fasterxml.jackson.core.TreeNode}) and a duplicate key
165 * is encountered (property name that was already seen for the JSON Object).
166 * If enabled, {@link JsonMappingException} will be thrown; if disabled, no exception
167 * is thrown and the new (later) value overwrites the earlier value.
168 *<p>
169 * Note that this property does NOT affect other aspects of data-binding; that is,
170 * no detection is done with respect to POJO properties or {@link java.util.Map}
171 * keys. New features may be added to control additional cases.
172 *<p>
173 * Feature is disabled by default so that no exception is thrown.
174 *
175 * @since 2.3
176 */
177 FAIL_ON_READING_DUP_TREE_KEY(false),
178
179 /**
180 * Feature that determines what happens when a property that has been explicitly
181 * marked as ignorable is encountered in input: if feature is enabled,
182 * {@link JsonMappingException} is thrown; if false, property is quietly skipped.
183 *<p>
184 * Feature is disabled by default so that no exception is thrown.
185 *
186 * @since 2.3
187 */
188 FAIL_ON_IGNORED_PROPERTIES(false),
189
190 /**
191 * Feature that determines what happens if an Object Id reference is encountered
192 * that does not refer to an actual Object with that id ("unresolved Object Id"):
193 * either an exception is thrown (<code>true</code>), or a null object is used
194 * instead (<code>false</code>).
195 * Note that if this is set to <code>false</code>, no further processing is done;
196 * specifically, if reference is defined via setter method, that method will NOT
197 * be called.
198 *<p>
199 * Feature is enabled by default, so that unknown Object Ids will result in an
200 * exception being thrown, at the end of deserialization.
201 *
202 * @since 2.5
203 */
204 FAIL_ON_UNRESOLVED_OBJECT_IDS(true),
205
206 /**
207 * Feature that determines what happens if one or more Creator properties (properties
208 * bound to parameters of Creator method (constructor or static factory method))
209 * are missing value to bind to from content.
210 * If enabled, such missing values result in a {@link JsonMappingException} being
211 * thrown with information on the first one (by index) of missing properties.
212 * If disabled, and if property is NOT marked as required,
213 * missing Creator properties are filled
214 * with <code>null values</code> provided by deserializer for the type of parameter
215 * (usually null for Object types, and default value for primitives; but redefinable
216 * via custom deserializers).
217 *<p>
218 * Note that having an injectable value counts as "not missing".
219 *<p>
220 * Feature is disabled by default, so that no exception is thrown for missing creator
221 * property values, unless they are explicitly marked as `required`.
222 *
223 * @since 2.6
224 */
225 FAIL_ON_MISSING_CREATOR_PROPERTIES(false),
226
227 /**
228 * Feature that determines what happens if one or more Creator properties (properties
229 * bound to parameters of Creator method (constructor or static factory method))
230 * are bound to null values - either from the JSON or as a default value. This
231 * is useful if you want to avoid nulls in your codebase, and particularly useful
232 * if you are using Java or Scala optionals for non-mandatory fields.
233 * Feature is disabled by default, so that no exception is thrown for missing creator
234 * property values, unless they are explicitly marked as `required`.
235 *
236 * @since 2.8
237 */
238 FAIL_ON_NULL_CREATOR_PROPERTIES(false),
239
240 /**
241 * Feature that determines what happens when a property annotated with
242 * {@link com.fasterxml.jackson.annotation.JsonTypeInfo.As#EXTERNAL_PROPERTY} is missing,
243 * but associated type id is available. If enabled, {@link JsonMappingException} is always
244 * thrown when property value is missing (if type id does exist);
245 * if disabled, exception is only thrown if property is marked as `required`.
246 *<p>
247 * Feature is enabled by default, so that exception is thrown when a subtype property is
248 * missing.
249 *
250 * @since 2.9
251 */
252 FAIL_ON_MISSING_EXTERNAL_TYPE_ID_PROPERTY(true),
253
254 /**
255 * Feature that determines behaviour for data-binding after binding the root value.
256 * If feature is enabled, one more call to
257 * {@link com.fasterxml.jackson.core.JsonParser#nextToken} is made to ensure that
258 * no more tokens are found (and if any is found,
259 * {@link com.fasterxml.jackson.databind.exc.MismatchedInputException} is thrown); if
260 * disabled, no further checks are made.
261 *<p>
262 * Feature could alternatively be called <code>READ_FULL_STREAM</code>, since it
263 * effectively verifies that input stream contains only as much data as is needed
264 * for binding the full value, and nothing more (except for possible ignorable
265 * white space or comments, if supported by data format).
266 *<p>
267 * Feature is disabled by default (so that no check is made for possible trailing
268 * token(s)) for backwards compatibility reasons.
269 *
270 * @since 2.9
271 */
272 FAIL_ON_TRAILING_TOKENS(false),
273
274 /**
275 * Feature that determines whether Jackson code should catch
276 * and wrap {@link Exception}s (but never {@link Error}s!)
277 * to add additional information about
278 * location (within input) of problem or not. If enabled,
279 * most exceptions will be caught and re-thrown (exception
280 * specifically being that {@link java.io.IOException}s may be passed
281 * as is, since they are declared as throwable); this can be
282 * convenient both in that all exceptions will be checked and
283 * declared, and so there is more contextual information.
284 * However, sometimes calling application may just want "raw"
285 * unchecked exceptions passed as is.
286 *<p>
287 * Feature is enabled by default.
288 */
289 WRAP_EXCEPTIONS(true),
290
291 /*
292 /******************************************************
293 /* Structural conversion features
294 /******************************************************
295 */
296
297 /**
298 * Feature that determines whether it is acceptable to coerce non-array
299 * (in JSON) values to work with Java collection (arrays, java.util.Collection)
300 * types. If enabled, collection deserializers will try to handle non-array
301 * values as if they had "implicit" surrounding JSON array.
302 * This feature is meant to be used for compatibility/interoperability reasons,
303 * to work with packages (such as XML-to-JSON converters) that leave out JSON
304 * array in cases where there is just a single element in array.
305 *<p>
306 * Feature is disabled by default.
307 */
308 ACCEPT_SINGLE_VALUE_AS_ARRAY(false),
309
310 /**
311 * Feature that determines whether it is acceptable to coerce single value array (in JSON)
312 * values to the corresponding value type. This is basically the opposite of the {@link #ACCEPT_SINGLE_VALUE_AS_ARRAY}
313 * feature. If more than one value is found in the array, a JsonMappingException is thrown.
314 * <p>
315 *
316 * Feature is disabled by default
317 * @since 2.4
318 */
319 UNWRAP_SINGLE_VALUE_ARRAYS(false),
320
321 /**
322 * Feature to allow "unwrapping" root-level JSON value, to match setting of
323 * {@link SerializationFeature#WRAP_ROOT_VALUE} used for serialization.
324 * Will verify that the root JSON value is a JSON Object, and that it has
325 * a single property with expected root name. If not, a
326 * {@link JsonMappingException} is thrown; otherwise value of the wrapped property
327 * will be deserialized as if it was the root value.
328 *<p>
329 * Feature is disabled by default.
330 */
331 UNWRAP_ROOT_VALUE(false),
332
333 /*
334 /******************************************************
335 /* Value conversion features
336 /******************************************************
337 */
338
339 /**
340 * Feature that can be enabled to allow JSON empty String
341 * value ("") to be bound as `null` for POJOs and other structured
342 * values ({@link java.util.Map}s, {@link java.util.Collection}s).
343 * If disabled, standard POJOs can only be bound from JSON `null` or
344 * JSON Object (standard meaning that no custom deserializers or
345 * constructors are defined; both of which can add support for other
346 * kinds of JSON values); if enabled, empty JSON String can be taken
347 * to be equivalent of JSON null.
348 *<p>
349 * NOTE: this does NOT apply to scalar values such as booleans and numbers;
350 * whether they can be coerced depends on
351 * {@link MapperFeature#ALLOW_COERCION_OF_SCALARS}.
352 *<p>
353 * Feature is disabled by default.
354 */
355 ACCEPT_EMPTY_STRING_AS_NULL_OBJECT(false),
356
357 /**
358 * Feature that can be enabled to allow empty JSON Array
359 * value (that is, <code>[ ]</code>) to be bound to POJOs (and
360 * with 2.9, other values too) as `null`.
361 * If disabled, standard POJOs can only be bound from JSON `null` or
362 * JSON Object (standard meaning that no custom deserializers or
363 * constructors are defined; both of which can add support for other
364 * kinds of JSON values); if enabled, empty JSON Array will be taken
365 * to be equivalent of JSON null.
366 *<p>
367 * Feature is disabled by default.
368 *
369 * @since 2.5
370 */
371 ACCEPT_EMPTY_ARRAY_AS_NULL_OBJECT(false),
372
373 /**
374 * Feature that determines whether coercion from JSON floating point
375 * number (anything with command (`.`) or exponent portion (`e` / `E'))
376 * to an expected integral number (`int`, `long`, `java.lang.Integer`, `java.lang.Long`,
377 * `java.math.BigDecimal`) is allowed or not.
378 * If enabled, coercion truncates value; if disabled, a {@link JsonMappingException}
379 * will be thrown.
380 *<p>
381 * Feature is enabled by default.
382 *
383 * @since 2.6
384 */
385 ACCEPT_FLOAT_AS_INT(true),
386
387 /**
388 * Feature that determines standard deserialization mechanism used for
389 * Enum values: if enabled, Enums are assumed to have been serialized using
390 * return value of <code>Enum.toString()</code>;
391 * if disabled, return value of <code>Enum.name()</code> is assumed to have been used.
392 *<p>
393 * Note: this feature should usually have same value
394 * as {@link SerializationFeature#WRITE_ENUMS_USING_TO_STRING}.
395 *<p>
396 * Feature is disabled by default.
397 */
398 READ_ENUMS_USING_TO_STRING(false),
399
400 /**
401 * Feature that allows unknown Enum values to be parsed as null values.
402 * If disabled, unknown Enum values will throw exceptions.
403 *<p>
404 * Note that in some cases this will basically ignore unknown Enum values;
405 * this is the keys for keys of {@link java.util.EnumMap} and values
406 * of {@link java.util.EnumSet} (because nulls are not accepted in these
407 * cases).
408 *<p>
409 * Feature is disabled by default.
410 *
411 * @since 2.0
412 */
413 READ_UNKNOWN_ENUM_VALUES_AS_NULL(false),
414
415 /**
416 * Feature that allows unknown Enum values to be ignored and a predefined value specified through
417 * {@link com.fasterxml.jackson.annotation.JsonEnumDefaultValue @JsonEnumDefaultValue} annotation.
418 * If disabled, unknown Enum values will throw exceptions.
419 * If enabled, but no predefined default Enum value is specified, an exception will be thrown as well.
420 *<p>
421 * Feature is disabled by default.
422 *
423 * @since 2.8
424 */
425 READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE(false),
426
427 /**
428 * Feature that controls whether numeric timestamp values are expected
429 * to be written using nanosecond timestamps (enabled) or not (disabled),
430 * <b>if and only if</b> datatype supports such resolution.
431 * Only newer datatypes (such as Java8 Date/Time) support such resolution --
432 * older types (pre-Java8 <b>java.util.Date</b> etc) and Joda do not --
433 * and this setting <b>has no effect</b> on such types.
434 *<p>
435 * If disabled, standard millisecond timestamps are assumed.
436 * This is the counterpart to {@link SerializationFeature#WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS}.
437 *<p>
438 * Feature is enabled by default, to support most accurate time values possible.
439 *
440 * @since 2.2
441 */
442 READ_DATE_TIMESTAMPS_AS_NANOSECONDS(true),
443
444 /**
445 * Feature that specifies whether context provided {@link java.util.TimeZone}
446 * ({@link DeserializationContext#getTimeZone()} should be used to adjust Date/Time
447 * values on deserialization, even if value itself contains timezone information.
448 * If enabled, contextual <code>TimeZone</code> will essentially override any other
449 * TimeZone information; if disabled, it will only be used if value itself does not
450 * contain any TimeZone information.
451 *<p>
452 * Note that exact behavior depends on date/time types in question; and specifically
453 * JDK type of {@link java.util.Date} does NOT have in-built timezone information
454 * so this setting has no effect.
455 * Further, while {@link java.util.Calendar} does have this information basic
456 * JDK {@link java.text.SimpleDateFormat} is unable to retain parsed zone information,
457 * and as a result, {@link java.util.Calendar} will always get context timezone
458 * adjustment regardless of this setting.
459 *<p>
460 *<p>
461 * Taking above into account, this feature is supported only by extension modules for
462 * Joda and Java 8 date/tyime datatypes.
463 *
464 * @since 2.2
465 */
466 ADJUST_DATES_TO_CONTEXT_TIME_ZONE(true),
467
468 /*
469 /******************************************************
470 /* Other
471 /******************************************************
472 */
473
474 /**
475 * Feature that determines whether {@link ObjectReader} should
476 * try to eagerly fetch necessary {@link JsonDeserializer} when
477 * possible. This improves performance in cases where similarly
478 * configured {@link ObjectReader} instance is used multiple
479 * times; and should not significantly affect single-use cases.
480 *<p>
481 * Note that there should not be any need to normally disable this
482 * feature: only consider that if there are actual perceived problems.
483 *<p>
484 * Feature is enabled by default.
485 *
486 * @since 2.1
487 */
488 EAGER_DESERIALIZER_FETCH(true)
489
490 ;
491
492 private final boolean _defaultState;
493 private final int _mask;
494
495 private DeserializationFeature(boolean defaultState) {
496 _defaultState = defaultState;
497 _mask = (1 << ordinal());
498 }
499
500 @Override
501 public boolean enabledByDefault() { return _defaultState; }
502
503 @Override
504 public int getMask() { return _mask; }
505
506 @Override
507 public boolean enabledIn(int flags) { return (flags & _mask) != 0; }
508 }
509