Skip to content

JSTEP 6

Jump to bottom
Tatu Saloranta edited this page Dec 31, 2024 · 42 revisions

(Back to JSTEP page)

Big Renaming of Core Entities for Jackson 3

Author

Tatu Saloranta (@cowtowncoder)

Version history

  • 2024-11-20: updated with the current state
  • 2024-06-02: updated with the current state
  • 2021-02-05: create first version based on existing changes

Status

Work-in-progress as of Jackson 2.18 (and will remain until 3.0.0 release)

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 was DeserializationContext for deserialization (reading Java Values out of token streams): but serialization side had 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 renaming).

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 (TokenStreamLocation)

Unify, Clarify Terminology

  • Object Values in token streams have "properties", not "fields" (not "entries" or "elements" or "values")
    • Note: term "value" is also used in context of JsonNode for Array elements and value part of Object properties.
  • 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

Entity renaming

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 (see JSTEP-4 for details)

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

Entity renaming work still being considered:

  • JsonEncoding: May want to change, but there are questions about whether it'd be necessary to extend choice of encodings
  • JsonParser: might want to rename as TokenStreamReader OR Token[Stream]Parser
    • Related: JsonParserDelegate, FilteringParserDelegate, JsonParserSequence -- get renamed if main class does
    • Might also want to rename: ParserBase, ParserMinimalBase (if Parser->Reader change made)
    • Ultimately might be too intrusive, considering NOT renaming
  • JsonGenerator: might want to rename as TokenStreamWriter OR Token[Stream]Generator
    • Related: JsonGeneratorDelegate, FilteringGeneratorDelegate to be renamed if main class is
    • Might also want to rename: GeneratorBase (if Generator->Writer change made)
    • Ultimately might be too intrusive, considering NOT renaming

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

Method/field renaming

Method/field name changes:

  • 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
  • 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
  • JsonLocation: renamed as TokenStreamLocationcore#1364
  • JsonToken: JsonToken.FIELD_NAME -> JsonToken.PROPERTY_NAME core#670

Databind

Entity renaming

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 (see JSTEP-4 for details)

  • JsonMappingException -> DatabindException #2828
  • 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

Field/method renaming

  • AnnotationIntrospector
    • databind#4818: Rename AnnotationIntrospector.findDefaultCreator() as findPreferredCreator()

Clone this wiki locally