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 /******************************************************
218 /* Access modifier handling
219 /******************************************************
220 */
221
222 /**
223 * Feature that determines whether method and field access
224 * modifier settings can be overridden when accessing
225 * properties. If enabled, method
226 * {@link java.lang.reflect.AccessibleObject#setAccessible}
227 * may be called to enable access to otherwise unaccessible objects.
228 *<p>
229 * Note that this setting may have significant performance implications,
230 * since access override helps remove costly access checks on each
231 * and every Reflection access. If you are considering disabling
232 * this feature, be sure to verify performance consequences if usage
233 * is performance sensitive.
234 * Also note that performance effects vary between Java platforms
235 * (JavaSE vs Android, for example), as well as JDK versions: older
236 * versions seemed to have more significant performance difference.
237 *<p>
238 * Conversely, on some platforms, it may be necessary to disable this feature
239 * as platform does not allow such calls. For example, when developing
240 * Applets (or other Java code that runs on tightly restricted sandbox),
241 * it may be necessary to disable the feature regardless of performance effects.
242 *<p>
243 * Feature is enabled by default.
244 */
245 CAN_OVERRIDE_ACCESS_MODIFIERS(true),
246
247 /**
248 * Feature that determines that forces call to
249 * {@link java.lang.reflect.AccessibleObject#setAccessible} even for
250 * <code>public</code> accessors -- that is, even if no such call is
251 * needed from functionality perspective -- if call is allowed
252 * (that is, {@link #CAN_OVERRIDE_ACCESS_MODIFIERS} is set to true).
253 * The main reason to enable this feature is possible performance
254 * improvement as JDK does not have to perform access checks; these
255 * checks are otherwise made for all accessors, including public ones,
256 * and may result in slower Reflection calls. Exact impact (if any)
257 * depends on Java platform (Java SE, Android) as well as JDK version.
258 *<p>
259 * Feature is enabled by default, for legacy reasons (it was the behavior
260 * until 2.6)
261 *
262 * @since 2.7
263 */
264 OVERRIDE_PUBLIC_ACCESS_MODIFIERS(true),
265
266 /*
267 /******************************************************
268 /* Type-handling features
269 /******************************************************
270 */
271
272 /**
273 * Feature that determines whether the type detection for
274 * serialization should be using actual dynamic runtime type,
275 * or declared static type.
276 * Note that deserialization always uses declared static types
277 * since no runtime types are available (as we are creating
278 * instances after using type information).
279 *<p>
280 * This global default value can be overridden at class, method
281 * or field level by using {@link JsonSerialize#typing} annotation
282 * property.
283 *<p>
284 * Feature is disabled by default which means that dynamic runtime types
285 * are used (instead of declared static types) for serialization.
286 */
287 USE_STATIC_TYPING(false),
288
289 /**
290 * Feature that specifies whether the declared base type of a polymorphic value
291 * is to be used as the "default" implementation, if no explicit default class
292 * is specified via {@code @JsonTypeInfo.defaultImpl} annotation.
293 *<p>
294 * Note that feature only has effect on deserialization of regular polymorphic properties:
295 * it does NOT affect non-polymorphic cases, and is unlikely to work with Default Typing.
296 *<p>
297 * Feature is disabled by default for backwards compatibility.
298 *
299 * @since 2.10
300 */
301 USE_BASE_TYPE_AS_DEFAULT_IMPL(false),
302
303 /*
304 /******************************************************
305 /* View-related features
306 /******************************************************
307 */
308
309 /**
310 * Feature that determines whether properties that have no view
311 * annotations are included in JSON serialization views (see
312 * {@link com.fasterxml.jackson.annotation.JsonView} for more
313 * details on JSON Views).
314 * If enabled, non-annotated properties will be included;
315 * when disabled, they will be excluded. So this feature
316 * changes between "opt-in" (feature disabled) and
317 * "opt-out" (feature enabled) modes.
318 *<p>
319 * Default value is enabled, meaning that non-annotated
320 * properties are included in all views if there is no
321 * {@link com.fasterxml.jackson.annotation.JsonView} annotation.
322 *<p>
323 * Feature is enabled by default.
324 */
325 DEFAULT_VIEW_INCLUSION(true),
326
327 /*
328 /******************************************************
329 /* Generic output features
330 /******************************************************
331 */
332
333 /**
334 * Feature that defines default property serialization order used
335 * for POJO fields (note: does <b>not</b> apply to {@link java.util.Map}
336 * serialization!):
337 * if enabled, default ordering is alphabetic (similar to
338 * how {@link com.fasterxml.jackson.annotation.JsonPropertyOrder#alphabetic()}
339 * works); if disabled, order is unspecified (based on what JDK gives
340 * us, which may be declaration order, but is not guaranteed).
341 *<p>
342 * Note that this is just the default behavior, and can be overridden by
343 * explicit overrides in classes (for example with
344 * {@link com.fasterxml.jackson.annotation.JsonPropertyOrder} annotation)
345 *<p>
346 * Feature is disabled by default.
347 */
348 SORT_PROPERTIES_ALPHABETICALLY(false),
349
350 /*
351 /******************************************************
352 /* Name-related features
353 /******************************************************
354 */
355
356 /**
357 * Feature that will allow for more forgiving deserialization of incoming JSON.
358 * If enabled, the bean properties will be matched using their lower-case equivalents,
359 * meaning that any case-combination (incoming and matching names are canonicalized
360 * by lower-casing) should work.
361 *<p>
362 * Note that there is additional performance overhead since incoming property
363 * names need to be lower-cased before comparison, for cases where there are upper-case
364 * letters. Overhead for names that are already lower-case should be negligible.
365 *<p>
366 * Feature is disabled by default.
367 *
368 * @since 2.5
369 */
370 ACCEPT_CASE_INSENSITIVE_PROPERTIES(false),
371
372
373 /**
374 * Feature that determines if Enum deserialization should be case sensitive or not.
375 * If enabled, Enum deserialization will ignore case, that is, case of incoming String
376 * value and enum id (depending on other settings, either `name()`, `toString()`, or
377 * explicit override) do not need to match.
378 * <p>
379 * Feature is disabled by default.
380 *
381 * @since 2.9
382 */
383 ACCEPT_CASE_INSENSITIVE_ENUMS(false),
384
385 /**
386 * Feature that permits parsing some enumerated text-based value types but ignoring the case
387 * of the values on deserialization: for example, date/time type deserializers.
388 * Support for this feature depends on deserializer implementations using it.
389 *<p>
390 * Note, however, that regular {@code Enum} types follow {@link #ACCEPT_CASE_INSENSITIVE_ENUMS}
391 * setting instead.
392 *<p>
393 * Feature is disabled by default.
394 *
395 * @since 2.10
396 */
397 ACCEPT_CASE_INSENSITIVE_VALUES(false),
398
399 /**
400 * Feature that can be enabled to make property names be
401 * overridden by wrapper name (usually detected with annotations
402 * as defined by {@link AnnotationIntrospector#findWrapperName}.
403 * If enabled, all properties that have associated non-empty Wrapper
404 * name will use that wrapper name instead of property name.
405 * If disabled, wrapper name is only used for wrapping (if anything).
406 *<p>
407 * Feature is disabled by default.
408 *
409 * @since 2.1
410 */
411 USE_WRAPPER_NAME_AS_PROPERTY_NAME(false),
412
413 /**
414 * Feature that may be enabled to enforce strict compatibility with
415 * Bean name introspection, instead of slightly different mechanism
416 * Jackson defaults to.
417 * Specific difference is that Jackson always lower cases leading upper-case
418 * letters, so "getURL()" becomes "url" property; whereas standard Bean
419 * naming <b>only</b> lower-cases the first letter if it is NOT followed by
420 * another upper-case letter (so "getURL()" would result in "URL" property).
421 *<p>
422 * Feature is disabled by default for backwards compatibility purposes: earlier
423 * Jackson versions used Jackson's own mechanism.
424 *
425 * @since 2.5
426 */
427 USE_STD_BEAN_NAMING(false),
428
429 /**
430 * Feature that when enabled will allow explicitly named properties (i.e., fields or methods
431 * annotated with {@link com.fasterxml.jackson.annotation.JsonProperty}("explicitName")) to
432 * be re-named by a {@link PropertyNamingStrategy}, if one is configured.
433 * <p>
434 * Feature is disabled by default.
435 *
436 * @since 2.7
437 */
438 ALLOW_EXPLICIT_PROPERTY_RENAMING(false),
439
440 /*
441 /******************************************************
442 /* Coercion features
443 /******************************************************
444 */
445
446 /**
447 * Feature that determines whether coercions from secondary representations are allowed
448 * for simple non-textual scalar types: numbers and booleans. This includes `primitive`
449 * types and their wrappers, but excludes `java.lang.String` and date/time types.
450 *<p>
451 * When feature is disabled, only strictly compatible input may be bound: numbers for
452 * numbers, boolean values for booleans. When feature is enabled, conversions from
453 * JSON String are allowed, as long as textual value matches (for example, String
454 * "true" is allowed as equivalent of JSON boolean token `true`; or String "1.0"
455 * for `double`).
456 *<p>
457 * Note that it is possible that other configurability options can override this
458 * in closer scope (like on per-type or per-property basis); this is just the global
459 * default.
460 *<p>
461 * Feature is enabled by default (for backwards compatibility since this was the
462 * default behavior)
463 *
464 * @since 2.9
465 */
466 ALLOW_COERCION_OF_SCALARS(true),
467
468 /*
469 /******************************************************
470 /* Other features
471 /******************************************************
472 */
473
474 /**
475 * Feature that determines whether multiple registrations of same module
476 * should be ignored or not; if enabled, only the first registration call
477 * results in module being called, and possible duplicate calls are silently
478 * ignored; if disabled, no checking is done and all registration calls are
479 * dispatched to module.
480 *<p>
481 * Definition of "same module" is based on using {@link Module#getTypeId()};
482 * modules with same non-null <code>type id</code> are considered same for
483 * purposes of duplicate registration. This also avoids having to keep track
484 * of actual module instances; only ids will be kept track of (and only if
485 * this feature is enabled).
486 *<p>
487 * Feature is enabled by default.
488 *
489 * @since 2.5
490 */
491 IGNORE_DUPLICATE_MODULE_REGISTRATIONS(true),
492
493 /**
494 * Setting that determines what happens if an attempt is made to explicitly
495 * "merge" value of a property, where value does not support merging; either
496 * merging is skipped and new value is created (<code>true</code>) or
497 * an exception is thrown (false).
498 *<p>
499 * Feature is enabled by default, to allow use of merge defaults even in presence
500 * of some unmergeable properties.
501 *
502 * @since 2.9
503 */
504 IGNORE_MERGE_FOR_UNMERGEABLE(true),
505
506 /**
507 * Setting that may be enabled to reconfigure <b>default</b>
508 * {@link com.fasterxml.jackson.databind.jsontype.PolymorphicTypeValidator}
509 * used by legacy {@code ObjectMapper.enableDefaultTyping()} methods as well as default used
510 * for annotation-based polymorphic handling so that it uses
511 * {@link com.fasterxml.jackson.databind.jsontype.DefaultBaseTypeLimitingValidator}.
512 * This will block use of a set of "unsafe" base types such as {@link java.lang.Object}
513 * through methods that do not require passing of explicit {@link com.fasterxml.jackson.databind.jsontype.PolymorphicTypeValidator}.
514 * It is still possible to override one used; this only affects default settings.
515 *<p>
516 * Enabling of this setting is <b>strongly recommended</b>.
517 *<p>
518 * Feature is disabled by default in 2.x for backwards compatibility reasons: it will become
519 * default setting (and feature likely removed) in 3.0.
520 *
521 * @since 2.11
522 */
523 BLOCK_UNSAFE_POLYMORPHIC_BASE_TYPES(false)
524 ;
525
526 private final boolean _defaultState;
527 private final int _mask;
528
529 private MapperFeature(boolean defaultState) {
530 _defaultState = defaultState;
531 _mask = (1 << ordinal());
532 }
533
534 @Override
535 public boolean enabledByDefault() { return _defaultState; }
536
537 @Override
538 public int getMask() { return _mask; }
539
540 @Override
541 public boolean enabledIn(int flags) { return (flags & _mask) != 0; }
542 }
543