JsonFactory Features

Jackson Streaming: JsonFactory.Feature

Jackson Streaming API has a set of on/off features that change aspects that have effect on both reading and writing JSON. Settings are set on JsonFactory, and generally can NOT be dynamically changed after first JsonParser or JsonGenerator has been created.

JsonFactory f = new JsonFactory();
f.disable(JsonFactory.Feature.CANONICALIZE_FIELD_NAMES);

Name canonicalization

These features determine if and how canonicalization of JSON Object property names is done.

• CANONICALIZE_FIELD_NAMES (default: true)
  • Means that once name String is decoded from input (byte or char stream), it will be added in a symbol table, to reduce overhead of decoding same name next time it is seen (by any parser constructed by same factory)
• INTERN_FIELD_NAMES (default: true)
  • If canonicalization is enabled, this feature determines whether String decoded is also interned (using String.intern()) or not -- doing that can help further improve deserialization performance since identity comparison may be used.
  • If names are unlikely to repeat, or if sheer number of distinct names is huge (in tens of thousands or above), it may make sense to disable this feature.
• FAIL_ON_SYMBOL_HASH_OVERFLOW (default: true) (added in 2.4)
  • Since canonicalization uses hash-based approach for resolving byte-/char-sequences into names, it is theoretically possible to construct sets of names that have exceptionally high rate of collision. If so, performance of hash lookups may be severely degraded. To guard against this possibility, symbol table uses heuristics to detect likely attack, based on unusually high number of collisions.
  • NOTE: hashing in use is NOT the same as what java.lang.String used with JDK 7 and before, and is therefore NOT vulnerable to the same attack (i.e. need attack specifically tailored to attack Jackson's hashing scheme)
  • In unlikely event that the exception is triggered for valid data, it may make sense to either disable this feature, or to disable canonicalization. However, Jackson authors would also like to be notified for such usage as it may point to an issue with hashing scheme -- so please file an issue if you encounter this problem.
  • Only relevant if canonicalization is enabled
• USE_THREAD_LOCAL_FOR_BUFFER_RECYCLING (default: true) (added in 2.6)
  • Since allocation of char[] and byte[] buffers for content reading/writing has significant impact, especially when handling relatively small documents, by default JsonFactory uses a ThreadLocal with SoftReference to refer to BufferRecycler: this allows reuse of underlying buffers across multiple read/write operations.
  • During most usage on J2SE/J2EE platforms, this recycling is highly efficient and can speed up processing significantly for smaller documents
  • On some platforms, however -- notably, Android -- handling of SoftReferences is sub-optimal (or even broken), leading to recycling not helping and potentially just adding some amount of overhead. On Android, you may consider disabling this feature and see if you get measurable performance improvement (not necessarily likely, but possible)
  • There may be other cases where use of ThreadLocal leads to unintended Class retention; this may also be avoid by disabling the feature.
  • Regardless: only disable this feature if you (a) know what you are doing and (b) get measurable improvement regarding problem you are trying solve -- do not simply disable it assuming it will help

Related

• Generator Features
• Parser Features
• Links to All Generic Jackson Features