StreamReadFeatures

Jackson Streaming: StreamReadFeature

General

This set of features was added in Jackson 2.10, split off from earlier JsonParser.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 ObjectReader instance as shown below (using STRICT_DUPLICATE_DETECTION as an enable example and AUTO_CLOSE_SOURCE as a disable example):

// Option 1, modifying when constructing JsonFactory
JsonFactory f = JsonFactory.builder()
   .enable(StreamReadFeature.STRICT_DUPLICATE_DETECTION)
   .disable(StreamReadFeature.AUTO_CLOSE_SOURCE)
   .build();
// Option 2, modifying when constructing JsonMapper or base type ObjectMapper
JsonMapper m = JsonMapper.builder()
   .enable(StreamReadFeature.STRICT_DUPLICATE_DETECTION)
   .disable(StreamReadFeature.AUTO_CLOSE_SOURCE)
   .build();
ObjectMapper m = JsonMapper.builder();
   .enable(StreamReadFeature.STRICT_DUPLICATE_DETECTION)
   .disable(StreamReadFeature.AUTO_CLOSE_SOURCE)
   .build();
// Option 3: defining when creating ObjectReader instance
ObjectReader r = mapper.readerFor(MyType.class)
   .with(StreamReadFeature.STRICT_DUPLICATE_DETECTION)
   .without(StreamReadFeature.AUTO_CLOSE_SOURCE);

Features

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

Low-level I/O handling features

• AUTO_CLOSE_SOURCE (default: true)
  • Feature that determines whether parser will automatically close underlying input source that is NOT owned by the parser. If disabled, calling application has to separately close the underlying InputStream and Reader instances used to create the parser.
    • If enabled, parser will handle closing, as long as parser itself gets closed: this happens when end-of-input is encountered, or parser is closed by a call to JsonParser.close().
  • Feature is enabled by default
  • Maps to JsonParser.Feature.AUTO_CLOSE_SOURCE

Additional input validation

• STRICT_DUPLICATE_DETECTION (default: false)
  • Feature that determines whether JsonParser will explicitly check that no duplicate (JSON) Object field names are encountered.
    • If enabled, parser will check all names within context and report duplicates by throwing a JsonParseException; if disabled, parser will not do such checking. Assumption in latter case is that caller takes care of handling duplicates at a higher level: data-binding, for example, has features to specify detection to be done there.
  • Note that enabling this feature will incur performance overhead due to having to store and check additional information: this typically adds 20-30% to execution time for basic parsing (but less time if measured at databind-level, due to other overhead)
  • Maps to JsonParser.Feature.STRICT_DUPLICATE_DETECTION
• IGNORE_UNDEFINED (default: false)
  • With formats that require Schema for parsing (like Avro, Protobuf, CSV), determines what happens if decoded encounters content that Schema has no definition for: if disabled, exception is thrown; if enabled, such content is quietly ignored.
  • Maps to JsonParser.Feature.IGNORE_UNDEFINED

Misc Other

• INCLUDE_SOURCE_IN_LOCATION (default: false since 2.16)
  • Feature that determines whether JsonLocation instances should be constructed with reference to source or not.
    • If source reference is included, its type and contents are included when toString() method is called (most notably when printing out parse exception with that location information)
    • If feature is disabled, no source reference is passed and source is only indicated as "REDACTED" (since 2.16; "UNKNOWN" before 2.16).
    • Most common reason for disabling this feature is to avoid leaking information about internal information; this may be done for security reasons.
  • Maps to JsonParser.Feature.INCLUDE_SOURCE_IN_LOCATION
  • NOTE: default was true up until 2.15; changed in 2.16
• USE_FAST_DOUBLE_PARSER (default: false) (added in 2.14)
  • Feature that determines whether we use the built-in Double#parseDouble(String) code to parse doubles or if we use faster algorithm instead.
  • Feature is disabled by default for backwards-compatibility reasons (at least in Jackson 2.14)