(Back to JSTEP page)

Big Renaming of Core Entities for Jackson 3

Author

Tatu Saloranta (@cowtowncoder)

Version history

• 2021-02-05: create first version based on existing changes

Overview

Due to historical reasons, naming of entities, methods and fields in Jackson is in places inconsistent and/or misleading. For example: since the original Jackson 1.0 only worked on JSON, term "Json" is included in many entity names, and even if Databind package is completely format-agnostic, naming there would suggest that things are very Json-centric.

Similarly there are things that are referred using different terms in places. For example:

• Name used for key/value pairs of content Object Values (like JSON Objects in JSON input) are variously known as "properties" (mostly in databind) and "fields" (often in streaming core package).
• Term "Object" may refer to content Object Values (JSON Objects) and its in-memory representations (ObjectNode of Tree Model); but also to Java Objects. But Java Objects also also known as "POJOs" and "Beans" in other cases (in databind, mostly).
• For databind, there is DeserializationContext for deserialization (reading Java Values out of token streams): but serialization side has SerializerProvider for similar context object

Although there has been progress over Jackson 2.x development cycle -- new abstractions, entities, methods, tend to be named with less issues -- backwards-compatibility prevents renaming in most cases.

But now that we are planning a major version, it is possible to make compatibility-breaking changes. Benefits of such renaming need to be balanced with the added effort for developers; benefits of more consistent and less-misleading naming over drawbacks for more changes when making necessary changes (code will require some amount of changes for 3.x even without any renamings).

General Goals

Remove use of "Json" in non-format-specific places

Due to historical reasons, many entities have "Json" as a prefix or included in names. It would be good to remove these in cases where handling is format-agnostic, and leave it for truly JSON-specific handlers.

NOTE: for practical reasons, we will NOT change names of jackson-annotations; there @JsonXxx usage will continue.

Reduce use of "get"/"set" for metadata/handler-property access

• Retain "get"/"set" when needed by serialization (by Jackson itself)
  • For example, location object (currently JsonLocation)

Unify, Clarify Terminology

• Object Values in token streams have "properties", not "fields" (not "entries" or "elements" or "values")
• Array Values in token streams have "elements"
• POJOs (Java Value types), Beans, have "properties" as well
• Core (streaming) concepts:
  • "Token Streams" are used for reading and writing sequences of tokens (JsonToken)
• Databinding concepts:
  • Value and Type Serializers/Deserializers are handlers read from/write to Token Streams to convert Java Values to/from content like JSON
• "Object" has been overloaded: with 3.x refers to values in Token Streams (like "JSON Object Values") and their representations in Tree Model -- but NOT to any Java values (like java.lang.Object)
  • Java Values are referred to as POJOs at core (streaming level), and as "Beans" at Databind level
  • NOTE: while we can and should use POJO (or sometimes, Bean) for Java Values, there is one specific set of entities we should NOT touch: ObjectMapper / ObjectReader / ObjectWriter -- see next section

Minimize changes for some common usage patterns

Since the vast majority of Jackson is through databinding -- and in particular using ObjectMapper (or its light-weight relatives, ObjectReader and ObjectWriter) -- we should not rename these entities. This despite the fact that "Object" in this case is misleading, and ideally these should probably be called ValueMapper / ValueReader / ValueWriter.

Another such use case is use of "Tree Model", and especially its base type JsonNode. While reference to "Json" is misleading in this case -- it is used as general-purpose Tree Model regardless of underlying dataformat being read/written -- changing name of this type seems too intrusive for the user base.

But one user-visible change we will make is renaming of most exceptions (to remove Json from names): this because as per JSTEP-4, changes to method signatures are needed anyway now that JacksonException no longer extends IOException.

---

Changes by component

Note that some changes to naming have been introduced earlier (methods added in 2.10, 2.11, 2.12; older version removed from 3.0 branch as part of general "remove deprecated methods" work).

Streaming

Renamed Entities (in com.fasterxml.jackson.core unless otherwise stated):

• JsonFactory -> TokenStreamFactory (base class; there is actual JsonFactory but now in com.fasterxml.jackson.core.json)
• JsonStreamContext -> TokenStreamContext core#411

Renamed Exceptions:

• JsonProcessingException -> JacksonException (ultimate base exception) core#640
  • JsonParseException -> StreamReadException
    • JsonEOFException -> UnexpectedEndOfInputException core#663
  • JsonGenerationException -> StreamWriteException

Method/field name changes:

• JsonParser
  • replace references to "field" with "property" core#670
  • replace getCurrentLocation()/getTokenLocation() with currentLocation()/currentTokenLocation() core#671
  • replace getCurrentValue()/setCurrentValue() with currentValue()/assignCurrentValue() core#674
• JsonGenerator
  • replace references to "field" with "property" core#670
  • replace JsonGenerator.writeObject() (and related) with writePOJO() core#673
  • replace getCurrentValue()/setCurrentValue() with currentValue()/assignCurrentValue() core#674
• JsonToken: JsonToken.FIELD_NAME -> JsonToken.PROPERTY_NAME core#670

Entity renaming work considered:

• JsonEncoding: May want to change, but there are questions about whether it'd be necessary to extend choice of encodings
• JsonLocation: likely to get rename as TokenStreamLocation
• JsonParser: possibly want to rename as TokenStreamReader OR Token[Stream]Parser
  • Related: JsonParserDelegate, FilteringParserDelegate, JsonParserSequence -- get renamed if main class does
  • Also likely to rename: ParserBase, ParserMinimalBase
• JsonGenerator: possibly want to rename as TokenStreamWriter OR Token[Stream]Generator
  • Related: JsonGeneratorDelegate, FilteringGeneratorDelegate to be renamed if main class is
  • Also likely to rename: GeneratorBase

No plans to rename:

• JsonPointer: named after JSON Pointer expressions, not content
• JsonToken/JsonTokenId: while it might make sense otherwise probably too intrusive at this point?
  • But note the somewhat intrusive change already made: JsonToken.FIELD_NAME -> JsonToken.PROPERTY_NAME
• JsonpCharacterEscapes: related to JSONP escaping, format-specific
• JsonStringEncoder: specific to escaping of characters for JSON String values

Databind

Renamed Entities (in com.fasterxml.jackson.databind unless otherwise stated):

• Bean[De]SerializerModifier/Value[De]SerializerModifier #3047
  • Although parts are Bean-specific, also handles non-Bean serializers/deserializers
• JsonSerializer/JsonDeserializer -> ValueSerializer/ValueDeserializer #3044
• JsonSerializable -> JacksonSerializable? #3046
  • not JSON-specific; also seems good for just this case to outline it's Jackson-specific, due to typical usage
• Module -> JacksonModule #3037
  • one-off, due to conflict with java.lang.Module (added in Java 9)

Renamed Exceptions:

• JsonMappingException -> DatabindException #2828

Entity renaming work considered:

• SerializerProvider -> SerializationContext #3043

No plans to rename:

• ObjectMapper/ObjectReader/ObjectWriter: while ambiguous wrt POJO/Bean, too intrusive for "regular" users
• JsonNode (and related): similarly too intrusive
• JsonSchema (and related visitors): specific to JSON Schema so valid -- although these types may get deprecated altogether
• BeanDeserializerBuilder/BeanSerializerBuilder: these are specific to Bean/POJO case and not just general value (de)serialization