-
-
Notifications
You must be signed in to change notification settings - Fork 799
JsonParser Features
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 JsonParser
instances, but more commonly default values are changed on JsonFactory
instances.
For example:
JsonFactory f = new JsonFactory();
f.enable(JsonParser.Feature.ALLOW_COMMENTS);
f.disable(JsonParser.Feature.ALLOW_SINGLE_QUOTES);
JsonParser p = f.createParser(jsonSource);
p.enable(JsonParser.Feature.STRICT_DUPLICATE_DETECTION);
Jackson 2.10 introduced Feature refactoring so that entries specified here we split into 2 new features
- StreamReadFeature: dataformat-agnostic features (usable on all format backends)
- JsonReadFeature (only usable on JSON backend)
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.
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. 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.
Settings can be divided in couple of loose categories, as follows.
-
AUTO_CLOSE_SOURCE (default: true)
- (in 2.10) Maps to
StreamReadFeature.AUTO_CLOSE_SOURCE
- (in 2.10) Maps to
-
ALLOW_COMMENTS (default: false) (for textual formats with concept of comments)
- For textual formats that do not have official comments, but for which "de facto" conventions exist (like JSON), determines whether use of such unofficial comments is allowed or not
- Supported for: JSON
- For JSON: enabling the feature allows recognition and handling of "C comments" (/* ... */) and "C++ comments" (// ....)
- YAML supports its own "hash comments" regardless of this setting
- (in 2.10) Maps to
JsonReadFeature.ALLOW_JAVA_COMMENTS
-
ALLOW_YAML_COMMENTS (default: false)
- Supported for: JSON (YAML allows by default)
- For JSON: enabling the feature allows recognition and handling of "hash comments" (# .... )
- (in 2.10) Maps to
JsonReadFeature.ALLOW_YAML_COMMENTS
-
ALLOW_UNQUOTED_FIELD_NAMES (default: false)
- Supported for: JSON
- (in 2.10) Maps to
JsonReadFeature.ALLOW_UNQUOTED_FIELD_NAMES
-
ALLOW_SINGLE_QUOTES (default: false)
- Supported for: JSON
- (in 2.10) Maps to
JsonReadFeature.ALLOW_SINGLE_QUOTES
-
ALLOW_UNQUOTED_CONTROL_CHARS (default: false)
- Supported for: JSON
- (in 2.10) Maps to
JsonReadFeature.ALLOW_UNESCAPED_CONTROL_CHARS
-
ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTER (default: false)
- Supported for: JSON
- (in 2.10) Maps to
JsonReadFeature.ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTER
-
ALLOW_NUMERIC_LEADING_ZEROS (default: false)
- Supported for: JSON
- (in 2.10) Maps to
JsonReadFeature.ALLOW_LEADING_ZEROS_FOR_NUMBERS
-
ALLOW_NON_NUMERIC_NUMBERS (default: false)
- Supported for: JSON
- (in 2.10) Maps to
JsonReadFeature.ALLOW_NON_NUMERIC_NUMBERS
-
ALLOW_MISSING_VALUES (default: false) (since 2.8)
- Allow translation of "missing" values (white-space between two commas, in JSON Array context) into
null
values, instead of an exception - Supported for: JSON
- (in 2.10) Maps to
JsonReadFeature.ALLOW_MISSING_VALUES
- Allow translation of "missing" values (white-space between two commas, in JSON Array context) into
-
ALLOW_TRAILING_COMMA (default: false) (since 2.9)
- Allow for a single "trailing" comma (one that comes after the last Array value or Object entry
- If enabled, would accept following non-standard values:
[ 1, 2, 3, ]
- `{ "value" : 42, }
- Supported for: JSON
- (in 2.10) Maps to
JsonReadFeature.ALLOW_TRAILING_COMMA
-
STRICT_DUPLICATE_DETECTION (default: false) (added in
2.3
)- (in 2.10) Maps to
StreamReadFeature.STRICT_DUPLICATE_DETECTION
- (in 2.10) Maps to
-
IGNORE_UNDEFINED (default: false) (added in
2.6
)- 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.
- Supported for: Avro, CSV
- Note: setting has no effect on
Avro
since it has no mechanism for recognizing such "unknown" content -- there is no way for decoder to ignore such content and instead a decoding error is thrown (or data corruption occurs) - (in 2.10) Maps to
StreamReadFeature.IGNORE_UNDEFINED
-
INCLUDE_SOURCE_IN_LOCATION (defalt: true) (added in
2.9
)- Feature that determines whether {@link JsonLocation} (for exceptions and direct location access) instances should be constructed with reference to source or not.
- If feature is disabled, no source reference is passed and source is only indicated as "UNKNOWN"
- Most common reason for disabling this feature is to avoid leaking internal information; this may be done for security reasons.
- (in 2.10) Maps to
StreamReadFeature.INCLUDE_SOURCE_IN_LOCATION