Skip to content

StreamWriteFeatures

Jump to bottom
Tatu Saloranta edited this page Jun 22, 2022 · 5 revisions

Jackson Streaming: StreamWriteFeature

General

This set of features was added in Jackson 2.10, split off from earlier JsonGenerator.Feature. It contains features that are "dataformat agnostic", that is, affect all (or at least more than one) format backends, not just JSON backend.

Note: with 2.10 and later 2.x version there is overlap between new and old features: Jackson will keep "same" settings in sync so you can whichever; but recommendation is to use newer set of features to ease migration to 3.0.

These features can be modified when constructing JsonFactory or JsonMapper (or ObjectMapper since JsonMapper is a subtype of ObjectMapper), or when creating ObjectWriter instance as shown below (using STRING_DUPLICATE_DETECTION as an enable example and AUTO_CLOSE_TARGET as a disable example):

// Option 1, modifying when constructing JsonFactory
JsonFactory f = JsonFactory.builder()
   .enable(StreamWriteFeature.STRICT_DUPLICATE_DETECTION)
   .disable(StreamWriteFeature.AUTO_CLOSE_TARGET)
   .build();
// Option 2, modifying when constructing JsonMapper or base type ObjectMapper
JsonMapper m = JsonMapper.builder()
   .enable(StreamWriteFeature.STRICT_DUPLICATE_DETECTION)
   .disable(StreamWriteFeature.AUTO_CLOSE_TARGET)
   .build();
ObjectMapper m = JsonMapper.builder()
   .enable(StreamWriteFeature.STRICT_DUPLICATE_DETECTION)
   .disable(StreamWriteFeature.AUTO_CLOSE_TARGET)
   .build();
// Option 3: defining when creating ObjectWriter instance
ObjectWriter r = mapper.writer()
   .with(StreamWriteFeature.STRICT_DUPLICATE_DETECTION)
   .without(StreamWriteFeature.AUTO_CLOSE_TARGET);

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
    • Maps to JsonGenerator.Feature.AUTO_CLOSE_TARGET
  • AUTO_CLOSE_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.
    • Maps to JsonGenerator.Feature.AUTO_CLOSE_JSON_CONTENT
  • 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.
    • Maps to JsonGenerator.Feature.FLUSH_PASSED_TO_STREAM

Format validation/schema features

  • IGNORE_UNKNOWN (default: false)
    • 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 any): if enabled, it is quietly ignored; if disable, an exception is thrown
    • Maps to JsonGenerator.Feature.STRICT_DUPLICATE_DETECTION
  • STRICT_DUPLICATE_DETECTION (default: false)
    • 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.
    • Maps to JsonGenerator.Feature.IGNORE_UNKNOWN

Datatype co(nv)ersions

  • WRITE_BIGDECIMAL_AS_PLAIN (default: false)
    • Feature that determines whether `java.math.BigDecimalentries are serialized usingjava.math.BigDecimal.toPlainString()``` to prevent values to be written using scientific notation.
    • Maps to JsonGenerator.Feature.WRITE_BIGDECIMAL_AS_PLAIN

Misc other features

  • USE_FAST_DOUBLE_WRITER (default: false) (added in 2.14)
    • Feature that determines whether to use standard Java code to write floats/doubles (default) or use the Schubfach algorithm which is faster
    • Enabling this feature may lead to small differences in the precision of the float/double values written to the JSON output.
    • Feature is disabled by default for backwards compatibility
Clone this wiki locally