Features for configuring low-level parsing
Following on/off features are defined in JsonParser.Feature: (note: disabled/enabled in parenthesis indicates default state of the feature if no explicit calls are made).
All features can be enabled either for JsonFactory (to determine default state for parsers factory creates) and for individual JsonParsers, unless specified otherwise.
- AUTO_CLOSE_SOURCE(enabled)
Feature that determines whether parser will automatically close underlying input source that is not owned by the parser. If disabled, application has to separately close the underlying InputStream and Reader instances passed to 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().
- INTERN_FIELD_NAMES (enabled) (since version 1.3)
Feature that determines whether JSON object field names are canonicalized using String.intern() or not: if enabled, all field names will be intern()ed (and caller can count on this being true for all such names); if disabled, no intern()ing is done. There may still be basic canonicalization (that is, same String will be used to represent all identical object property names for a single document).
- Usually this feature should be left enabled: only disable it if you have specific problems with intern()ing (such as unbounded number of JSON object property names)
NOTE: This feature can NOT be set for individual parsers; it has to be set for the factory to be used for all JsonParser it creates.
- CANONICALIZE_FIELD_NAMES (enabled) (since version 1.5)
- Feature that determines whether JSON object field names are canonicalized: if enabled, all field names will canonicalized (see above for actual method used for canonicalization); if false, no canonicalization is done and each field name is allocated as a new String
- NOTE: disabling this feature in general has negative performance consequences, so only disable it if you know what you are doing. The use case where it may make sense is that of parsing large JSON content with unique field names (where same name does not typically repeat).
NOTE: This feature can NOT be set for individual parsers; it has to be set for the factory.
Support for parsing non-standard "JSON"
By default Jackson conforms strictly to JSON specification. But because non-standard JSON(-like) content does exist in the wild (and regrettably in large quantities), Jackson does have set of features to support parsing of such non-standard content:
- ALLOW_COMMENTS(disabled) (since version 1.2)
- Feature that determines whether parser will allow use of Java/C++ style comments (both '/'+'*' and '//' varieties) within parsed content or not.
- ALLOW_UNQUOTED_FIELD_NAMES(disabled)
- Feature that determines whether parser will allow use of unquoted field names (as opposed to legal JSON field names that are always surrounded by double quotes)
- ALLOW_SINGLE_QUOTES (disabled) (since version 1.3)
- Feature that determines whether parser will allow use of single quotes (apostrophe, character "'") for quoting Strings (field names and String values), instead of double quotes (which are still also legal independent of state of this feature).
- ALLOW_UNQUOTED_CONTROL_CHARS(disabled) (since version 1.4)
- Feature that determines whether parser will allow JSON Strings (including field names) that contain unquotes control characters (ascii code below 32, including tab, line feed); if enabled, no parse exception is thrown on encountering such characters.
- ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTER(disabled) (since version 1.6)
- Feature that determines whether parser will allow parsing of non-standard backslash quotes (ones not specified as allowed by JSON spec).
ALLOW_NUMERIC_LEADING_ZEROS(disabled) (since 1.8)
Feature that determines whether it is legal to add leading zeroes for (integral) numbers: for example, whether value 003 would be acceptable alternative to 3. If enabled, leading zeroes are accepted but ignored (and removed, for purposes of JsonParser.getText()).
ALLOW_NON_NUMERIC_NUMBERS (disabled) (since 1.8)
- Feature that determines whether following tokens are allowed as floating-point numeric values: NaN, +INF, -INF, +Infinite, -Infinite
If allowed, will be returned as JsonToken.VALUE_NUMBER_FLOAT; double value being matching native Java constant from java.lang.Double
Users should only enable these features if they understand ramifications of supporting non-valid content, and at least not produce any such content, just consume (that is: always write valid JSON).