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)

    • 5272: change ObjectMapper.getRegisteredModuleIds() to getRegisteredModules() (not just rename)

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

Comment From: JooHyukKim

There is also JsonMapper.builderWithJackson2Defaults().build(); that we can add to JSTEP-2 doc

Comment From: cowtowncoder

@JooHyukKim Good idea. Could you do that?

Comment From: JooHyukKim

Yeah will do tonight!

Comment From: JooHyukKim

Added guide at bottom section, named "Using Jackson 2.x defaults in Jackson 3"

Comment From: JooHyukKim

Inspired by https://github.com/FasterXML/jackson-databind/issues/5161

I think we can still use migration guide. Since most information is documented/written already, I am considering to start one, just simply connect, patch things together. And improve on it.

Few questions/suggestions tho... @cowtowncoder @pjfanning

First, Wiki or codebase(PR) ? - +1 for codebase. So we can use PR as community-participation point - Wiki is not widely used. I haven't seen many open source projects using Wiki. - Meaning Wiki could be deprecated and be a risk in long term.

Second, where should it go? /jackson vs `/jackson-future-ideas - This one I am quite unsure.

Comment From: cowtowncoder

There's also jackson-docs, although I think main jackson is probably the way to go IMHO.

jackson-future-ideas more for planning, on-going changes.