Skip to content

JsonGenerator Features

Jump to bottom
Tatu Saloranta edited this page Apr 19, 2020 · 6 revisions

Jackson Streaming: JsonGenerator.Feature

Jackson Streaming API has a set of on/off features that change the way streaming parsing is done. Features can be directly enabled/disabled on JsonGenerator instances, but more commonly default values are changed on JsonFactory instances. For example:

JsonFactory f = new JsonFactory();
f.enable(JsonGenerator.Feature.ESCAPE_NON_ASCII);
f.disable(JsonGenerator.Feature.AUTO_CLOSE_TARGET);
JsonGenerator g = f.createGenerator(destination);
g.enable(JsonGenerator.Feature.STRICT_DUPLICATE_DETECTION);

Status

Jackson 2.10 introduced Feature refactoring so that entries specified here we split into 2 new features

These new features are mapped to old ones, wherever those exist: for backward-compatibility reason you can use either new settings, or old ones described here. With 3.0, only new ones will be usable.

General notes

Although use of these features is shared by all data format modules (and despite many format modules specifying additional format-specific features), not all features listed here apply to all data formats. Sometimes choice of addition of a feature for specific format module, and generic generator feature is arbitrary. But the intent is for all features that are likely to be needed by more than one format should be included here, to reduce/remove overlapping features with same semantics.

Features

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

Low-level I/O handling features

  • AUTO_CLOSE_TARGET (default: true)
    • Feature that determines whether underlying target (OutputStream, Writer) should be automatically closed even if target is not "owned" by generator (owning means that target was constructed by Jackson, not caller, and Jackson is responsible for closing it), but close() is called on generator
  • AUTO_CLOSE_JSON_CONTENT (default: true)
    • Feature that determines what happens when generator is closed, but underlying token stream does not yet contain all closing tokens needed to construct balanced structure (for example: JSON content is missing closing ']' and/or '}' markers for Arrays and Objects).
    • If enabled, missing closing tokens are automatically written; if disabled, no additional work is done. No exception is thrown in either case.
    • Disabling this feature may be occasionally useful when writing "unbalanced" snippets of JSON.
  • FLUSH_PASSED_TO_STREAM (default: true)
    • Feature that determines whether call to JsonGenerator.flush() will also call flush() on underlying target; if disabled, flush() will only write unflushed content; if enabled, will also call flush() on it.

Content escaping/quoting/encoding

  • QUOTE_FIELD_NAMES (default: true)
    • Applicable to formats that use specific field name quoting mechanism, such as JSON
    • Currently supported for: JSON
    • Specifically for JSON, disabling this feature will prevent use of double-quotes when writing field names
  • QUOTE_NON_NUMERIC_NUMBERS (default: true)
    • Applicable to textual data formats that have distinction between quoted values (Strings), and unquoted numeric values.
    • Currently supported for: JSON
  • ESCAPE_NON_ASCII (default: false)
  • WRITE_NUMBERS_AS_STRINGS (default: false)
  • WRITE_BIGDECIMAL_AS_PLAIN (default: false) (since 2.3)

Format validation/schema features

  • STRICT_DUPLICATE_DETECTION (default: false) (since 2.3)
    • If enabled (and functionality supported by data format module), will keep track of field names within scope of an Object, and throw an exception if uniqueness is violated.
    • Currently supported for: JSON, Smile, CBOR
  • IGNORE_UNKNOWN (default: 2.5)
    • Feature that determines what happens if generator is asked to write a field with name that is not declared by Schema assigned to generator: if enabled, it is quietly ignored; if disable, an exception is thrown
    • Currently supported for: Avro, CSV, Protobuf (2.6)
Clone this wiki locally