Mapper Features

JoseCarlosMM edited this page Jun 28, 2016 · 8 revisions

Jackson on/off features: MapperFeature

Jackson defines a set of per-mapper configuration, which can ONLY be defined before using ObjectMapper -- meaning that these settings can not be changed on-the-fly, on per-request basis. They configure fundamental POJO introspection details, and resulting built objects (serializers, deserializers, related) are heavily cached. If you need differing settings for these, you have to use separate ObjectMapper instances.

Settings can be divided in couple of loose categories, as follows.

Annotation handling

  • USE_ANNOTATIONS (default: true): whether any annotation processing is used or not
    • may be useful on platforms where annotation-processing is hideously expensive (like Android)

Introspection, property detection

  • AUTO_DETECT_CREATORS (default: true)
    • If enabled, some Creator methods (constructor, static factory method that returns value of this type) may be automatically detected, without explicit @JsonCreator annotation
    • To be auto-detected, Creator method has to:
      • Be public
      • Take only one argument, of type: String, int, long or boolean
      • For factory methods, name of the method has to be valueOf; other factory methods are not auto-detected
    • Only "delegating" style is supported, as of Jackson 2.7 (this may change in future)
  • AUTO_DETECT_FIELDS (default: true)
  • AUTO_DETECT_GETTERS (default: true)
  • AUTO_DETECT_IS_GETTERS (default: true)
  • AUTO_DETECT_SETTERS (default: true)
  • REQUIRE_SETTERS_FOR_GETTERS (default: false)
  • USE_GETTERS_AS_SETTERS (default: true)
  • INFER_PROPERTY_MUTATORS (default: true) (since 2.2)
    • If enabled, mutators (field or setter used for changing POJO property value) may be inferred: that is, un-annotated, not-visible field or setter can be considered mutator if (and only if!) there is a fully visible or explicitly annotated (@JsonProperty) accessor (getter or field) with same logical name.
    • Enabled by default for convenience: may be disabled if fully explicit annotations are desired.
  • ALLOW_FINAL_FIELDS_AS_MUTATORS (default: true) (since 2.2): Feature that determines whether member fields declared as 'final' may be auto-detected to be used mutators (used to change value of the logical property) or not
    • If enabled, 'final' access modifier has no effect, and such fields may be detected according to usual visibility and inference rules; if disabled, such fields are NOT used as mutators except if explicitly annotated for such use.
    • Feature is enabled by default, for backwards compatibility reasons.

Reflection, access

  • CAN_OVERRIDE_ACCESS_MODIFIERS (default: true)
    • Feature that determines whether method and field access modifier settings can be overridden when accessing properties. If enabled, method AccessibleObject#setAccessible may be called to enable access to otherwise unaccessible objects.
  • OVERRIDE_PUBLIC_ACCESS_MODIFIERS (default: true) (since 2.7)
    • If CAN_OVERRIDE_ACCESS_MODIFIERS is enabled, this feature further determines whether setAccessible(true) is called on members (methods, fields, constructors):
      • For non-public members (or, public members of non-public classes), call is always made since Reflection access is not possible otherwise
      • For public members (of public classes), calls is only made if this feature is enabled

Name handling

  • SORT_PROPERTIES_ALPHABETICALLY (default: false): Feature that defines default property serialization order used: either alphabetic (true), or "whatever order JDK exposes fields in" (false).
    • Only applies to POJO fields, does not apply to java.util.Map serialization!
    • Note that this is just the default behavior, and can be overridden by explicit overrides in classes, for example with @JsonPropertyOrder
  • USE_WRAPPER_NAME_AS_PROPERTY_NAME (default: false) (since 2.2): Feature that can be enabled to make property names be overridden by wrapper name (usually detected with annotations as defined by {@link AnnotationIntrospector#findWrapperName}. If enabled, all properties that have associated non-empty Wrapper name will use that wrapper name instead of property name.
    • If disabled, wrapper name is only used for wrapping (if anything).
  • ACCEPT_CASE_INSENSITIVE_PROPERTIES (default: false) (since 2.5: Feature that will allow for more forgiving deserialization of incoming JSON.
    • If enabled, the bean properties will be matched using their lower-case equivalents, meaning that any case-combination (incoming and matching names are canonicalized by lower-casing) should work.
    • Note that there is additional performance overhead since incoming property names need to be lower-cased before comparison, for cases where there are upper-case letters. Overhead is more significant if non-lower-case characters are included (i.e. name needs to be changed on the fly)
  • USE_STD_BEAN_NAMING (default: false) (since 2.5: Feature that may be enabled to enforce strict compatibility with Bean name introspection, instead of slightly different mechanism Jackson defaults to.
    • Specific difference is that Jackson always lower cases leading upper-case letters, so "getURL()" becomes "url" property; whereas standard Bean naming only lower-cases the first letter if it is NOT followed by another upper-case letter (so "getURL()" would result in "URL" property).

Other

  • USE_STATIC_TYPING (default: false)
  • DEFAULT_VIEW_INCLUSION (default: true)
  • IGNORE_DUPLICATE_MODULE_REGISTRATIONS (default: true): Feature that determines whether multiple registrations of same module should be ignored or not
    • if enabled, only the first registration call results in module being called, and possible duplicate calls are silently ignored; if disabled, no checking is done and all registration calls are dispatched to module.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.