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 DeserializationFeature(boolean defaultState)495 private DeserializationFeature(boolean defaultState) { 496 _defaultState = defaultState; 497 _mask = (1 << ordinal()); 498 } 499 500 @Override enabledByDefault()501 public boolean enabledByDefault() { return _defaultState; } 502 503 @Override getMask()504 public int getMask() { return _mask; } 505 506 @Override enabledIn(int flags)507 public boolean enabledIn(int flags) { return (flags & _mask) != 0; } 508 } 509