JSON Features

Jackson jr: Features

The main configuration method of Jackson jr is used of simple on/off features. These features are defined as JSON.feature, and can be enabled/disabled by calls to JSON; result is a new JSON object and typical usage is by chaining calls like:

byte[] bytes = JSON.std
    .with(Feature.PRETTY_PRINT_OUTPUT)
    .without(Feature.WRITE_NULL_PROPERTIES)
    .asBytes(bean);

but it is also possible to store and reuse previously configured JSON instances:

JSON configuredJson = JSON.std
    .with(Feature.PRETTY_PRINT_OUTPUT)
    .without(Feature.WRITE_NULL_PROPERTIES);
byte[] bytes = configuredJson.asBytes(bean);

Note that cost of creating new JSON instances is marginal. Also worth noting is that JSON instances are fully immutable, so with() and without() calls never change state of existing instances but create new instances. This means that JSON is fully and completely thread-safe, and usage never needs to be synchronized.

Writer features

Writer features: type-specific

• WRITE_DATES_AS_TIMESTAMP (default: false) (since 2.7)
  • Feature that determines how java.util.Calendar and java.util.Date are serialized; if false, a textual representation is used; if true, 64-bit Java timestamp
• WRITE_ENUMS_USING_INDEX (default: false)
  • Feature that determines whether Enum values are written using numeric index (true), or String representation from calling Enum.toString() (false)
• WRITE_NULL_PROPERTIES (default: false)
  • Feature that defines what to do with java.util.Map entries and Java Bean properties that have null as value: if enabled, they will be written out normally; if disabled, such entries and properties will be ignored.
• WRITE_READONLY_BEAN_PROPERTIES (default: true)
  • Feature that determines whether "read-only" properties of Beans (properties that only have a getter but no matching setter) are to be included in Bean serialization or not; if disabled,only properties have have both setter and getter are serialized. Note that feature is only used if Feature.HANDLE_JAVA_BEANS is also enabled.

Writer features: other

• FAIL_ON_UNKNOWN_TYPE_WRITE (default: false)
  • Feature that determines what happens when we encounter a value of unrecognized type for which we do not have a standard handler: if enabled, will throw a JSONObjectException; if disabled simply calls Object.toString() and uses that JSON String as serialization.
  • NOTE: if HANDLE_JAVA_BEANS is enabled, this setting typically has no effect, since otherwise unknown types are recognized as Bean types and handled appropriately.
• FLUSH_AFTER_WRITE_VALUE (default: true)
  • Feature that determines whether JsonGenerator.flush() is called after write() method that takes JsonGenerator as an argument completes (that is, does NOT affect methods that use other destinations).
  • Flushing usually makes sense; but there are cases where flushing should not be forced: for example when underlying stream is compressing and flush() causes compression state to be flushed (which occurs with some compression codecs).
• PRETTY_PRINT_OUTPUT (default: false)
  • Feature that can be enabled to use "pretty-printing", basic indentation to make resulting JSON easier to read by humans by adding white space such as line feeds and indentation.
  • NOTE: details of pretty-printing are handled by underlying JsonGenerator

Reader features

• FAIL_ON_DUPLICATE_MAP_KEYS (default: true)
  • When encountering duplicate keys for JSON Objects, should an exception be thrown or not? If exception is not thrown, the last instance from input document will be used.
• FAIL_ON_UNKNOWN_BEAN_PROPERTY (default: false)
  • When encountering a JSON Object property name for which there is no matching Bean property, should an exception be thrown (true), or should JSON Property value be quietly skipped (false)?
• PRESERVE_FIELD_ORDERING (default: true)
  • This feature can be used to indicate that the reader should preserve order of the properties same as what input document has. Note that it is up to com.fasterxml.jackson.jr.ob.impl.MapBuilder to support this feature; custom implementations may ignore the setting.
• READ_JSON_ARRAYS_AS_JAVA_ARRAYS (default: false)
  • When reading JSON Arrays, should matching Java value be of type Object[] (true) or java.util.List (false)?
• READ_ONLY (default: false)
  • This feature can be enabled to reduce memory usage for use cases where resulting container objects (java.util.Maps and java.util.Collections) do not need to mutable (that is, their contents can not changed). If set, reader is allowed to construct immutable (read-only) container objects; and specifically empty java.util.Maps and java.util.Collections can be used to reduce number of objects allocated. In addition, sizes of non-empty containers can be trimmed to exact size.
  • NOTE: enabling the feature will make attempts to modify Maps, Collections will fail with an exception.
• USE_BIG_DECIMAL_FOR_FLOATS (default: false)
  • When reading JSON Numbers, should java.math.BigDecimal be used for floating-point numbers; or should java.lang.Double be used. Trade-off is between accuracy -- only java.math.BigDecimal is guaranteed to store the EXACT decimal value parsed -- and performance (java.lang.Double is typically faster to parse).
• USE_DEFERRED_MAPS (default: true)
  • This feature determines whether java.util.Map instances constructed use deferred materialization (as implemented by {@link DeferredMap}), in case user has not specified custom java.util.Map implementation.
  • Enabling feature typically reduces initial value read time and moves overhead to actual access of contents (materialization occurs when first key or value access happens); this makes sense when only a subset of data is accessed. Conversely, when traversing full object hierarchy, it makes sense to disable this feature.
• USE_IS_GETTERS (default: true)
  • Whether "is-getters" (like public boolean isValuable()) are detected for use or not. Note that in addition to naming, and lack of arguments, return value also has to be boolean or java.lang.Boolean.

Other features

• FORCE_REFLECTION_ACCESS (default: true)
  • Feature that determines whether access to {@link java.lang.reflect.Method}s and java.lang.reflect.Constructors that are used with dynamically introspected Beans may be forced using java.lang.reflect.AccessibleObject.setAccessible() or not.
  • Note that disabling this setting will typically add overhead and slow down access.
• HANDLE_JAVA_BEANS (default: true)
  • Feature that determines whether Bean types (Java objects with getters and setters that expose state to serialize) will be recognized and handled or not. When enabled, any types that are not recognized as standard JDK data structures, primitives or wrapper values will be introspected and handled as Java Beans (can be read/written as long as JSON matches properties discovered); when disabled, they may only be serialized (using Object.toString() method), and can not be deserialized.