1 package com.fasterxml.jackson.databind; 2 3 import com.fasterxml.jackson.databind.annotation.JsonSerialize; 4 import com.fasterxml.jackson.databind.cfg.ConfigFeature; 5 6 /** 7 * Enumeration that defines simple on/off features to set 8 * for {@link ObjectMapper}, and accessible (but not changeable) 9 * via {@link ObjectReader} and {@link ObjectWriter} (as well as 10 * through various convenience methods through context objects). 11 *<p> 12 * Note that in addition to being only mutable via {@link ObjectMapper}, 13 * changes only take effect when done <b>before any serialization or 14 * deserialization</b> calls -- that is, caller must follow 15 * "configure-then-use" pattern. 16 */ 17 public enum MapperFeature implements ConfigFeature 18 { 19 /* 20 /****************************************************** 21 /* General introspection features 22 /****************************************************** 23 */ 24 25 /** 26 * Feature that determines whether annotation introspection 27 * is used for configuration; if enabled, configured 28 * {@link AnnotationIntrospector} will be used: if disabled, 29 * no annotations are considered. 30 *<p> 31 * Feature is enabled by default. 32 */ 33 USE_ANNOTATIONS(true), 34 35 /** 36 * Feature that determines whether otherwise regular "getter" 37 * methods (but only ones that handle Collections and Maps, 38 * not getters of other type) 39 * can be used for purpose of getting a reference to a Collection 40 * and Map to modify the property, without requiring a setter 41 * method. 42 * This is similar to how JAXB framework sets Collections and 43 * Maps: no setter is involved, just setter. 44 *<p> 45 * Note that such getters-as-setters methods have lower 46 * precedence than setters, so they are only used if no 47 * setter is found for the Map/Collection property. 48 *<p> 49 * Feature is enabled by default. 50 */ 51 USE_GETTERS_AS_SETTERS(true), 52 53 /** 54 * Feature that determines how <code>transient</code> modifier for fields 55 * is handled: if disabled, it is only taken to mean exclusion of the field 56 * as accessor; if true, it is taken to imply removal of the whole property. 57 *<p> 58 * Feature is disabled by default, meaning that existence of `transient` 59 * for a field does not necessarily lead to ignoral of getters or setters 60 * but just ignoring the use of field for access. 61 * 62 * @since 2.6 63 */ 64 PROPAGATE_TRANSIENT_MARKER(false), 65 66 /* 67 /****************************************************** 68 /* Introspection-based property auto-detection 69 /****************************************************** 70 */ 71 72 /** 73 * Feature that determines whether "creator" methods are 74 * automatically detected by consider public constructors, 75 * and static single argument methods with name "valueOf". 76 * If disabled, only methods explicitly annotated are considered 77 * creator methods (except for the no-arg default constructor which 78 * is always considered a factory method). 79 *<p> 80 * Note that this feature has lower precedence than per-class 81 * annotations, and is only used if there isn't more granular 82 * configuration available. 83 *<P> 84 * Feature is enabled by default. 85 */ 86 AUTO_DETECT_CREATORS(true), 87 88 /** 89 * Feature that determines whether non-static fields are recognized as 90 * properties. 91 * If yes, then all public member fields 92 * are considered as properties. If disabled, only fields explicitly 93 * annotated are considered property fields. 94 *<p> 95 * Note that this feature has lower precedence than per-class 96 * annotations, and is only used if there isn't more granular 97 * configuration available. 98 *<p> 99 * Feature is enabled by default. 100 */ 101 AUTO_DETECT_FIELDS(true), 102 103 /** 104 * Feature that determines whether regular "getter" methods are 105 * automatically detected based on standard Bean naming convention 106 * or not. If yes, then all public zero-argument methods that 107 * start with prefix "get" 108 * are considered as getters. 109 * If disabled, only methods explicitly annotated are considered getters. 110 *<p> 111 * Note that since version 1.3, this does <b>NOT</b> include 112 * "is getters" (see {@link #AUTO_DETECT_IS_GETTERS} for details) 113 *<p> 114 * Note that this feature has lower precedence than per-class 115 * annotations, and is only used if there isn't more granular 116 * configuration available. 117 *<p> 118 * Feature is enabled by default. 119 */ 120 AUTO_DETECT_GETTERS(true), 121 122 /** 123 * Feature that determines whether "is getter" methods are 124 * automatically detected based on standard Bean naming convention 125 * or not. If yes, then all public zero-argument methods that 126 * start with prefix "is", and whose return type is boolean 127 * are considered as "is getters". 128 * If disabled, only methods explicitly annotated are considered getters. 129 *<p> 130 * Note that this feature has lower precedence than per-class 131 * annotations, and is only used if there isn't more granular 132 * configuration available. 133 *<p> 134 * Feature is enabled by default. 135 */ 136 AUTO_DETECT_IS_GETTERS(true), 137 138 /** 139 * Feature that determines whether "setter" methods are 140 * automatically detected based on standard Bean naming convention 141 * or not. If yes, then all public one-argument methods that 142 * start with prefix "set" 143 * are considered setters. If disabled, only methods explicitly 144 * annotated are considered setters. 145 *<p> 146 * Note that this feature has lower precedence than per-class 147 * annotations, and is only used if there isn't more granular 148 * configuration available. 149 *<P> 150 * Feature is enabled by default. 151 */ 152 AUTO_DETECT_SETTERS(true), 153 154 /** 155 * Feature that determines whether getters (getter methods) 156 * can be auto-detected if there is no matching mutator (setter, 157 * constructor parameter or field) or not: if set to true, 158 * only getters that match a mutator are auto-discovered; if 159 * false, all auto-detectable getters can be discovered. 160 *<p> 161 * Feature is disabled by default. 162 */ 163 REQUIRE_SETTERS_FOR_GETTERS(false), 164 165 /** 166 * Feature that determines whether member fields declared as 'final' may 167 * be auto-detected to be used mutators (used to change value of the logical 168 * property) or not. If enabled, 'final' access modifier has no effect, and 169 * such fields may be detected according to usual visibility and inference 170 * rules; if disabled, such fields are NOT used as mutators except if 171 * explicitly annotated for such use. 172 *<p> 173 * Feature is enabled by default, for backwards compatibility reasons. 174 * 175 * @since 2.2 176 */ 177 ALLOW_FINAL_FIELDS_AS_MUTATORS(true), 178 179 /** 180 * Feature that determines whether member mutators (fields and 181 * setters) may be "pulled in" even if they are not visible, 182 * as long as there is a visible accessor (getter or field) with same name. 183 * For example: field "value" may be inferred as mutator, 184 * if there is visible or explicitly marked getter "getValue()". 185 * If enabled, inferring is enabled; otherwise (disabled) only visible and 186 * explicitly annotated accessors are ever used. 187 *<p> 188 * Note that 'getters' are never inferred and need to be either visible (including 189 * bean-style naming) or explicitly annotated. 190 *<p> 191 * Feature is enabled by default. 192 * 193 * @since 2.2 194 */ 195 INFER_PROPERTY_MUTATORS(true), 196 197 /** 198 * Feature that determines handling of {@code java.beans.ConstructorProperties} 199 * annotation: when enabled, it is considered as alias of 200 * {@link com.fasterxml.jackson.annotation.JsonCreator}, to mean that constructor 201 * should be considered a property-based Creator; when disabled, only constructor 202 * parameter name information is used, but constructor is NOT considered an explicit 203 * Creator (although may be discovered as one using other annotations or heuristics). 204 *<p> 205 * Feature is mostly used to help inter-operability with frameworks like Lombok 206 * that may automatically generate {@code ConstructorProperties} annotation 207 * but without necessarily meaning that constructor should be used as Creator 208 * for deserialization. 209 *<p> 210 * Feature is enabled by default. 211 * 212 * @since 2.9 213 */ 214 INFER_CREATOR_FROM_CONSTRUCTOR_PROPERTIES(true), 215 216 /** 217 * Feature that determines whether nominal property type of {@link Void} is 218 * allowed for Getter methods to indicate {@code null} valued pseudo-property 219 * or not. If enabled, such properties are recognized (see [databind#2675] for 220 * reasons -- mostly things related to frameworks, code generation); if disabled, 221 * such property accessors (or at least getters) are ignored. 222 *<p> 223 * Feature is disabled by default (in 2.12) for backwards compatibility. 224 * 225 * @since 2.12 226 */ 227 ALLOW_VOID_VALUED_PROPERTIES(false), 228 229 /* 230 /****************************************************** 231 /* Access modifier handling 232 /****************************************************** 233 */ 234 235 /** 236 * Feature that determines whether method and field access 237 * modifier settings can be overridden when accessing 238 * properties. If enabled, method 239 * {@link java.lang.reflect.AccessibleObject#setAccessible} 240 * may be called to enable access to otherwise unaccessible objects. 241 *<p> 242 * Note that this setting may have significant performance implications, 243 * since access override helps remove costly access checks on each 244 * and every Reflection access. If you are considering disabling 245 * this feature, be sure to verify performance consequences if usage 246 * is performance sensitive. 247 * Also note that performance effects vary between Java platforms 248 * (JavaSE vs Android, for example), as well as JDK versions: older 249 * versions seemed to have more significant performance difference. 250 *<p> 251 * Conversely, on some platforms, it may be necessary to disable this feature 252 * as platform does not allow such calls. For example, when developing 253 * Applets (or other Java code that runs on tightly restricted sandbox), 254 * it may be necessary to disable the feature regardless of performance effects. 255 *<p> 256 * Feature is enabled by default. 257 */ 258 CAN_OVERRIDE_ACCESS_MODIFIERS(true), 259 260 /** 261 * Feature that determines that forces call to 262 * {@link java.lang.reflect.AccessibleObject#setAccessible} even for 263 * <code>public</code> accessors -- that is, even if no such call is 264 * needed from functionality perspective -- if call is allowed 265 * (that is, {@link #CAN_OVERRIDE_ACCESS_MODIFIERS} is set to true). 266 * The main reason to enable this feature is possible performance 267 * improvement as JDK does not have to perform access checks; these 268 * checks are otherwise made for all accessors, including public ones, 269 * and may result in slower Reflection calls. Exact impact (if any) 270 * depends on Java platform (Java SE, Android) as well as JDK version. 271 *<p> 272 * Feature is enabled by default, for legacy reasons (it was the behavior 273 * until 2.6) 274 * 275 * @since 2.7 276 */ 277 OVERRIDE_PUBLIC_ACCESS_MODIFIERS(true), 278 279 /* 280 /****************************************************** 281 /* Type-handling features 282 /****************************************************** 283 */ 284 285 /** 286 * Feature that determines whether the type detection for 287 * serialization should be using actual dynamic runtime type, 288 * or declared static type. 289 * Note that deserialization always uses declared static types 290 * since no runtime types are available (as we are creating 291 * instances after using type information). 292 *<p> 293 * This global default value can be overridden at class, method 294 * or field level by using {@link JsonSerialize#typing} annotation 295 * property. 296 *<p> 297 * Feature is disabled by default which means that dynamic runtime types 298 * are used (instead of declared static types) for serialization. 299 */ 300 USE_STATIC_TYPING(false), 301 302 /** 303 * Feature that specifies whether the declared base type of a polymorphic value 304 * is to be used as the "default" implementation, if no explicit default class 305 * is specified via {@code @JsonTypeInfo.defaultImpl} annotation. 306 *<p> 307 * Note that feature only has effect on deserialization of regular polymorphic properties: 308 * it does NOT affect non-polymorphic cases, and is unlikely to work with Default Typing. 309 *<p> 310 * Feature is disabled by default for backwards compatibility. 311 * 312 * @since 2.10 313 */ 314 USE_BASE_TYPE_AS_DEFAULT_IMPL(false), 315 316 /** 317 * Feature that enables inferring builder type bindings from the value type 318 * being deserialized. This requires that the generic type declaration on 319 * the value type match that on the builder exactly: mismatched type declarations 320 * are not necessarily detected by databind. 321 *<p> 322 * Feature is enabled by default which means that deserialization does 323 * support deserializing types via builders with type parameters (generic types). 324 *<p> 325 * See: https://github.com/FasterXML/jackson-databind/issues/921 326 * 327 * @since 2.12 328 */ 329 INFER_BUILDER_TYPE_BINDINGS(true), 330 331 /* 332 /****************************************************** 333 /* View-related features 334 /****************************************************** 335 */ 336 337 /** 338 * Feature that determines whether properties that have no view 339 * annotations are included in JSON serialization views (see 340 * {@link com.fasterxml.jackson.annotation.JsonView} for more 341 * details on JSON Views). 342 * If enabled, non-annotated properties will be included; 343 * when disabled, they will be excluded. So this feature 344 * changes between "opt-in" (feature disabled) and 345 * "opt-out" (feature enabled) modes. 346 *<p> 347 * Default value is enabled, meaning that non-annotated 348 * properties are included in all views if there is no 349 * {@link com.fasterxml.jackson.annotation.JsonView} annotation. 350 *<p> 351 * Feature is enabled by default. 352 */ 353 DEFAULT_VIEW_INCLUSION(true), 354 355 /* 356 /****************************************************** 357 /* Generic output features 358 /****************************************************** 359 */ 360 361 /** 362 * Feature that defines default property serialization order used 363 * for POJO fields (note: does <b>not</b> apply to {@link java.util.Map} 364 * serialization!): 365 * if enabled, default ordering is alphabetic (similar to 366 * how {@link com.fasterxml.jackson.annotation.JsonPropertyOrder#alphabetic()} 367 * works); if disabled, order is unspecified (based on what JDK gives 368 * us, which may be declaration order, but is not guaranteed). 369 *<p> 370 * Note that this is just the default behavior, and can be overridden by 371 * explicit overrides in classes (for example with 372 * {@link com.fasterxml.jackson.annotation.JsonPropertyOrder} annotation) 373 *<p> 374 * Feature is disabled by default. 375 */ 376 SORT_PROPERTIES_ALPHABETICALLY(false), 377 378 /* 379 /****************************************************** 380 /* Name-related features 381 /****************************************************** 382 */ 383 384 /** 385 * Feature that will allow for more forgiving deserialization of incoming JSON. 386 * If enabled, the bean properties will be matched using their lower-case equivalents, 387 * meaning that any case-combination (incoming and matching names are canonicalized 388 * by lower-casing) should work. 389 *<p> 390 * Note that there is additional performance overhead since incoming property 391 * names need to be lower-cased before comparison, for cases where there are upper-case 392 * letters. Overhead for names that are already lower-case should be negligible. 393 *<p> 394 * Feature is disabled by default. 395 * 396 * @since 2.5 397 */ 398 ACCEPT_CASE_INSENSITIVE_PROPERTIES(false), 399 400 401 /** 402 * Feature that determines if Enum deserialization should be case sensitive or not. 403 * If enabled, Enum deserialization will ignore case, that is, case of incoming String 404 * value and enum id (depending on other settings, either `name()`, `toString()`, or 405 * explicit override) do not need to match. 406 * <p> 407 * Feature is disabled by default. 408 * 409 * @since 2.9 410 */ 411 ACCEPT_CASE_INSENSITIVE_ENUMS(false), 412 413 /** 414 * Feature that permits parsing some enumerated text-based value types but ignoring the case 415 * of the values on deserialization: for example, date/time type deserializers. 416 * Support for this feature depends on deserializer implementations using it. 417 *<p> 418 * Note, however, that regular {@code Enum} types follow {@link #ACCEPT_CASE_INSENSITIVE_ENUMS} 419 * setting instead. 420 *<p> 421 * Feature is disabled by default. 422 * 423 * @since 2.10 424 */ 425 ACCEPT_CASE_INSENSITIVE_VALUES(false), 426 427 /** 428 * Feature that can be enabled to make property names be 429 * overridden by wrapper name (usually detected with annotations 430 * as defined by {@link AnnotationIntrospector#findWrapperName}. 431 * If enabled, all properties that have associated non-empty Wrapper 432 * name will use that wrapper name instead of property name. 433 * If disabled, wrapper name is only used for wrapping (if anything). 434 *<p> 435 * Feature is disabled by default. 436 * 437 * @since 2.1 438 */ 439 USE_WRAPPER_NAME_AS_PROPERTY_NAME(false), 440 441 /** 442 * Feature that may be enabled to enforce strict compatibility with 443 * Bean name introspection, instead of slightly different mechanism 444 * Jackson defaults to. 445 * Specific difference is that Jackson always lower cases leading upper-case 446 * letters, so "getURL()" becomes "url" property; whereas standard Bean 447 * naming <b>only</b> lower-cases the first letter if it is NOT followed by 448 * another upper-case letter (so "getURL()" would result in "URL" property). 449 *<p> 450 * Feature is disabled by default for backwards compatibility purposes: earlier 451 * Jackson versions used Jackson's own mechanism. 452 * 453 * @since 2.5 454 */ 455 USE_STD_BEAN_NAMING(false), 456 457 /** 458 * Feature that when enabled will allow explicitly named properties (i.e., fields or methods 459 * annotated with {@link com.fasterxml.jackson.annotation.JsonProperty}("explicitName")) to 460 * be re-named by a {@link PropertyNamingStrategy}, if one is configured. 461 * <p> 462 * Feature is disabled by default. 463 * 464 * @since 2.7 465 */ 466 ALLOW_EXPLICIT_PROPERTY_RENAMING(false), 467 468 /* 469 /****************************************************** 470 /* Coercion features 471 /****************************************************** 472 */ 473 474 /** 475 * Feature that determines whether coercions from secondary representations are allowed 476 * for simple non-textual scalar types: numbers and booleans. This includes `primitive` 477 * types and their wrappers, but excludes `java.lang.String` and date/time types. 478 *<p> 479 * When feature is disabled, only strictly compatible input may be bound: numbers for 480 * numbers, boolean values for booleans. When feature is enabled, conversions from 481 * JSON String are allowed, as long as textual value matches (for example, String 482 * "true" is allowed as equivalent of JSON boolean token `true`; or String "1.0" 483 * for `double`). 484 *<p> 485 * Note that it is possible that other configurability options can override this 486 * in closer scope (like on per-type or per-property basis); this is just the global 487 * default. 488 *<p> 489 * Feature is enabled by default (for backwards compatibility since this was the 490 * default behavior) 491 * 492 * @since 2.9 493 */ 494 ALLOW_COERCION_OF_SCALARS(true), 495 496 /* 497 /****************************************************** 498 /* Other features 499 /****************************************************** 500 */ 501 502 /** 503 * Feature that determines whether multiple registrations of same module 504 * should be ignored or not; if enabled, only the first registration call 505 * results in module being called, and possible duplicate calls are silently 506 * ignored; if disabled, no checking is done and all registration calls are 507 * dispatched to module. 508 *<p> 509 * Definition of "same module" is based on using {@link Module#getTypeId()}; 510 * modules with same non-null <code>type id</code> are considered same for 511 * purposes of duplicate registration. This also avoids having to keep track 512 * of actual module instances; only ids will be kept track of (and only if 513 * this feature is enabled). 514 *<p> 515 * Feature is enabled by default. 516 * 517 * @since 2.5 518 */ 519 IGNORE_DUPLICATE_MODULE_REGISTRATIONS(true), 520 521 /** 522 * Setting that determines what happens if an attempt is made to explicitly 523 * "merge" value of a property, where value does not support merging; either 524 * merging is skipped and new value is created (<code>true</code>) or 525 * an exception is thrown (false). 526 *<p> 527 * Feature is enabled by default, to allow use of merge defaults even in presence 528 * of some unmergeable properties. 529 * 530 * @since 2.9 531 */ 532 IGNORE_MERGE_FOR_UNMERGEABLE(true), 533 534 /** 535 * Setting that may be enabled to reconfigure <b>default</b> 536 * {@link com.fasterxml.jackson.databind.jsontype.PolymorphicTypeValidator} 537 * used by legacy {@code ObjectMapper.enableDefaultTyping()} methods as well as default used 538 * for annotation-based polymorphic handling so that it uses 539 * {@link com.fasterxml.jackson.databind.jsontype.DefaultBaseTypeLimitingValidator}. 540 * This will block use of a set of "unsafe" base types such as {@link java.lang.Object} 541 * through methods that do not require passing of explicit {@link com.fasterxml.jackson.databind.jsontype.PolymorphicTypeValidator}. 542 * It is still possible to override one used; this only affects default settings. 543 *<p> 544 * Enabling of this setting is <b>strongly recommended</b>. 545 *<p> 546 * Feature is disabled by default in 2.x for backwards compatibility reasons: it will become 547 * default setting (and feature likely removed) in 3.0. 548 * 549 * @since 2.11 550 */ 551 BLOCK_UNSAFE_POLYMORPHIC_BASE_TYPES(false) 552 ; 553 554 private final boolean _defaultState; 555 private final int _mask; 556 MapperFeature(boolean defaultState)557 private MapperFeature(boolean defaultState) { 558 _defaultState = defaultState; 559 _mask = (1 << ordinal()); 560 } 561 562 @Override enabledByDefault()563 public boolean enabledByDefault() { return _defaultState; } 564 565 @Override getMask()566 public int getMask() { return _mask; } 567 568 @Override enabledIn(int flags)569 public boolean enabledIn(int flags) { return (flags & _mask) != 0; } 570 } 571