Jackson3 Changes

NOTE: (20-Aug-2017) -- will be moved to https://github.com/FasterXML/jackson3-dev Very Soon Now.

---

Proposed Jackson 3.0 changes

JVM/JDK Compatibility

• Jackson 3.x will require and be based on Java 8
  • with possible exception of jackson-core and jackson-annotations (?)

Structural

Maven modules (jars)

• Embed some/all Java8 modules
  • Embed "parameter names", "datatypes" (Optional)
  • Need to think of Java 8 date/time module (size)

Git Repos

• Should we combine databind with "base modules" (mr-bean, afterburner, jaxb-annotations) for easier tracking of API change effects?

Things to Remove

Anything deprecated by 2.9

Plan is to immediately remove all things deprecated (but not yet removed) by version 2.9, including things that are part of Public API (which have been retained throughout whole 2.x cycle, unlike internal/package APIs).

This includes:

1. Old JSON Schema generation that builds JsonNode (already deprecated)
   • Not actively maintained since at least 2.4, deprecated by visitor-based approach since then
   • May want to rewrite visitor-introspection interface as well; too JSON Schema centric

Major Functionality

Following are things that are thought to be removed as of now:

1. Dataformat auto-detection (most in streaming, some in databind)
   • supported by some formats, but complicated to make work at higher level
2. Ability to re-configure ObjectMapper with different codec factory (JsonFactory)
   • If codec factory is fixed since construction, allows databind/core to be more optimized, esp. for binary formats where name is not decoded from input but inferred from schema (protobuf, avro) -- could lead to non-trivial performance improvements

Further following features are up for discussion

1. Serializability of components (from ObjectMapper on)
   • Original justification was to allow "thaw"/"unthaw" for Android, but it is questionable whether observed improvement was due to use of JDK serialization, or something else (perf problem in setup)
   • In general, idea of serializing active components is not a good idea: and making it explicit these are not serializable can even help resolve problems on systems like distributed data streaming processors (Spark, Storm etc)
   • Lots of bits of extra code, removal of which would clean up codebase a bit; but more importantly, less code to maintain, test
   • May still want to offer some level of explicit support for passing configuration of ObjectMapper / ObjectReader / ObjectWriter? That is, allow some form of externalizing settings, if possible (but may not be... perhaps only for some of settings)

XxxFeatures

MapperFeature:

• USE_STD_BEAN_NAMING: should always be used, no need for old slightly differing algorithm
• AUTO_DETECT_xxx: old limited settings superceded by more granular settings -- can be deleted, frees up 5 features

DeserializationFeature:

• Although all features still make sense, would make sense to try to combine some, and/or create new type of configuration to use instead of feature -- for example
  • FAIL_xxx are all kind of similar. DeserializationFail, or "check" or... ?
  • READ_xxx_as_yyy, similarly
  • ACCEPT_xxx_as_yyy, similarly

SerializationFeature:

• Most if not all features seem to make sense, but there are groups that could use unification of some kind
  • FAIL_ON_xxx
  • WRITE_xxx_as_yyy

Entities

• ContextualSerializer / ContextualDeserializer, ResolvableSerializer / ResolvableDeserializer
  • just embed as part of JsonSerializer / JsonDeserializer, with no-op implementation

(Re)Naming

jackson-core renamings

In general, we would want to reduce mentions of "json" in cases where API is not JSON-specific. This is pretty much of all jackson-databind, and most of jackson-core too -- after all, other dataformats use same abstractions and there should be separate JSON implementation. However: some of existing entities with json in their name -- say, JsonProcessingException, JsonParser and JsonGenerator -- are so widely used that renaming would cause so much work that it is questionable whether change would be worth the trouble. So, question becomes: what are the places where we could improve naming with limited amount of compatibility breakage (small amount is fine: 3.0 is backwards-incompatible).

• JsonFactory -> StreamFactory? (alts: "CodecFactory", "StreamingFactory"?)
  • Unlike JsonParser and JsonGenerator, factory itself is not exposed in all that many places
  • Additional change: current JsonFactory would be split in two parts: general-purpose abstract StreamFactory, and JSON-specific JsonStreamFactory -- we do want to get rid of JsonFactory to avoid/reduce collision (since the new version is NOT a base class of other factories any more)
• Possibly rename exceptions, esp. JsonProcessingException (StreamException?) -- base type not that often used
  • JsonParseException -> StreamDecodingException?
  • JsonGenerationException -> StreamEncodingException?

Major API change areas

• JsonNode needs major rework; can do binary-incompatible return value changes

Changes to defaults

(will require wiki sub-page)

• MapperFeature
  • SORT_PROPERTIES_ALPHABETICALLY: default to true (false really doesn't make much sense since it is unstable, and arbitrary based on JVM/JDK)
• DeserializationFeature
  • READ_ENUMS_USING_TO_STRING: default to true (instead of false that relies on name())
  • FAIL_ON_UNKNOWN_PROPERTIES: default to false? (TOP REQUEST by users)
• SerializationFeature
  • FAIL_ON_EMPTY_BEANS: default to false
• Other
  • Date/time
    • Disable lenient setting (that is: default to "strict")
    • Check defaults of date/time handling

Misc Impl Changes

• JsonStreamContext: implement "currentValue" access in base class (remove from sub-classes)