3.x seems to introduce severe change to widely used interfaces, like removal of ObjectMapper.registerModule. It'd be nice to have a migration guide which offers an overview of such popular 2.x use cases, recipes and idioms and their 3.x counterpart in case they changed.

I'm aware that 3.x is not released, yet, so this is merely a reminder.

Comment From: cowtowncoder

Yes, absolutely.

More discussions will also be needed since I think my original idea of 2.x -> 3.x being smaller step than 1.x -> 2.x is proving incorrect.

Biggest change for ObjectMapper and JsonFactory will be change to fully immutable implementation, which makes use of Builder-pattern necessary. One (and about only) backwards-compatibility feature is that zero-argument constructors are left in place, to create "vanilla" instances.

Comment From: cowtowncoder

Things to include:

• JsonNode changes

  • 4875: Remove JsonNode.fields() from 3.0

  • 4879: Rename TextNode as StringNode; JsonNode.xxxTextYyy() as JsonNode.xxxStringYyy()

• ObjectMapper immutability changes:

  • 5270: removal of ObjectMapper.setSerializationInclusion()

• ObjectMapper changes, misc other:

  • 5263: drop ObjectMapper.readValue(URL, type), ObjectReader.readValue(URL)

Comment From: cowtowncoder

Possible high-level conversion workflow:

1. Change to Java packages as per JSTEP-1 -- need to change import statements
2. Renaming of Classes, Methods -- JSTEP-6 -- need to update names
3. All @Deprecated methods (as of 2.20.0) are removed from 3.0 -- convert as per 2.20.0 JavaDocs
4. Changes to default settings (esp various XxxFeatures) -- JSTEP-2): may need to override defaults
5. Immutable JsonFactory / TokenStreamFactory: convert direct configuration with Builder alternatives
6. Immutable ObjectMapper: convert direct configuration with Builder alternatives