Skip to content

Jackson Release 3.0

Jump to bottom
Tatu Saloranta edited this page Jan 7, 2025 · 200 revisions

Version 3.0 is under development, as of March 2021 (and since late 2017).

It is a major version update and thereby not API compatible with 2.x; however, since 2.10 new methods have been added in 2.x line to reduce incompatibilities.

Overall plans are outlined in JSTEP-1

Changes, compatibility

JDK

Java 17 is now required for all components, except for jackson-annotations that still requires just Java 8

Major changes/features in 3.0

  1. Removal of all deprecated methods, functionality, as of 2.x
    • Remove format-auto-detection (interesting idea but not widely used and few formats beyond JSON, XML, Smile, Avro support detection)
  2. Full immutability of core entities, via Builder-style construction
    • TokenStreamFactory (old JsonFactory)
    • ObjectMapper (addition of format-specific sub-classes, from JsonMapper to XmlMapper)
    • Note Jackson 2.10 and later will also support most of Builder-style construction but without strict guarantees of immutability of underlying entities (due to backwards-compatibility reasons)
    • See Jackson 3 immutability with builders
  3. Tighter integration between Streaming and Databinding to allow improved support of non-JSON formats
    • ObjectMapper remains shared API, but every format will have its own mapper subtype, including JsonMapper for JSON
      • Partly implemented in 2.x since 2.10, to support Builder-style construction (albeit without immutability)
    • Format-specific mapper will (have to) use format-specific TokenStreamFactory
  4. Unchecked exceptions (see JSTEP-4
    • Base 2.x exceptions will be replaced with new counterparts as follows (counterparts will be added in 2.x but mostly used in 3.0)
    • JsonProcessingException (root exception) becomes JacksonException
    • JsonParseException/JsonGenerationException (streaming) will become StreamReadException/StreamWriteException
    • JsonMappingException (root for databind exceptions) becomes DatabindException
    • While new exceptions will be added by Jackson 2.13, their use is limited: they CAN be caught but NOT thrown (sort of "read-only" upgrade) while retaining compatibility across minor versions

Changes, core

Annotations

  • #267: Raise minimum Java version for jackson-annotations to Java 8 for Jackson 3.x

Streaming

  • #378: Change default for TokenStreamFactory.Feature.INTERN_FIELD_NAMES to false
  • #402: Remove dataformat-auto-detection functionality
  • #411: Rename JsonStreamContext as TokenStreamContext
  • #413: Remove ObjectCodec: replace with ObjectWriteContext / ObjectReadContext
  • #432: Add new TreeNode subtypes: ArrayTreeNode, ObjectTreeNode
  • #433: Add Builder pattern for creating configured Stream factories
  • #456: Add JsonParser.readAsValue(ResolvedType)
  • #492: Ensure primitive type names in error message enclosed in backticks
  • #551: Remove JsonGenerator.setPrettyPrinter() from 3.0
  • #663: Rename JsonEOFException as UnexpectedEndOfInputException
  • #670: Replace references to "field" in JsonGenerator, JsonParser method names with "property"
  • #671: Replace getCurrentLocation()/getTokenLocation() with currentLocation()/currentTokenLocation()
  • #676: Remove JsonGenerator.canWriteBinaryNatively(), canWriteFormattedNumbers() (replaced by StreamWriteCapability equivalents)
  • #680: Allow use of java.nio.file.Path as parser source, generator target
  • #689: Remove existing "request payload" functionality
  • #785: Make JsonGenerator.writeXxx() methods chainable
  • #793: Rename "com.fasterxml.jackson" -> "tools.jackson"
  • #1090: Remove BufferRecyclers.SYSTEM_PROPERTY_TRACK_REUSABLE_BUFFERS
  • #1125: Remove TokenStreamFactory.Feature.USE_THREAD_LOCAL_FOR_BUFFER_RECYCLING
  • #1200: Change JsonWriteFeature.ESCAPE_FORWARD_SLASHES default to true for 3.0
  • #1231: Enable Fast Floating-Point reading/writing by default in 3.0
  • #1233: Lower default maxNestingDepth of StreamReadConstraints / StreamWriteConstraints to 500 in 3.0
  • #1269: Change JsonFactory.builder() configuration of RecyclerPool to avoid allocation default implementation (in 3.0)
  • #1364: rename JsonLocation as TokenStreamLocation [JSTEP-6]
  • #1373: Change TreeNode.propertyName() return type from Iterator<JsonNode> to Collection<JsonNode> (3.0)
  • #1378: Rename JsonParser.getText() as .getString() [JSTEP-6]
  • Rename JsonGenerator.Feature.AUTO_CLOSE_JSON_CONTENT as AUTO_CLOSE_CONTENT
  • Add TreeCodec.nullNode(), TreeNode.isNull() methods
  • Change the way JsonLocation.NA is included in exception messages

Databind

Functionality removal

  • #1772: Remove MapperFeature. USE_STD_BEAN_NAMING
  • #1773: Remove MapperFeature.AUTO_DETECT_xxx features
  • #1917: Remove canSerialize and canDeserialize methods from ObjectMapper
  • #1973: Remove support for "default [Map] key serializer" configuration from SerializerProvider
  • #2040: Remove JsonSerializer.isEmpty()
  • #4160: Deprecate DefaultTyping.EVERYTHING in 2.x and remove in 3.0
  • Remove MappingJsonFactory
  • #4659: Remove use of global static TypeFactory singleton from 3.0
  • #4875: Remove JsonNode.fields() from 3.0

Functionality changes

  • #493: Change DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES default to false
  • #1600: Serializing locale with underscore, not standard hyphen
  • #1762: StdDateFormat: serialize time offset using colon
  • #1774: Merge Java8 datatype (Optional, Stream) support in core databind
  • #1775: Merge Java8 parameter name support (jackson-module-parameter-names) in core databind
  • #1781: Return ObjectNode from ObjectNode set-methods in order to allow better chaining
  • #1829: JsonNode.deepCopy() ClassCastException`s
  • #1888: Merge ResolvableSerializer into JsonSerializer, ResolvableDeserializer into JsonDeserializer
  • #1889: Merge ContextualSerializer into JsonSerializer, ContextualDeserializer into JsonDeserializer
  • #1916: Change MapperFeature.USE_GETTERS_AS_SETTERS) default to false
  • #1994: Limit size of SerializerCache, auto-flush on exceeding
  • #1995: Limit size of DeserializerCache, auto-flush on exceeding
  • #2177: Change parent type of JsonProcessingException to be RuntimeException
  • #2593: StackTraceElement w/ >= Java 9 doesn't deserialize properly
  • #2713: Change wording of UnrecognizedPropertyException to refer to "property" not "field"
  • #3028: Change UUIDSerializer to use StreamWriteCapability check instead of JsonGenerator.canWriteBinaryNatively()
  • #3070: Disable SerializationFeature.FAIL_ON_EMPTY_BEANS by default
  • #4381: Prevent construction of null-valued JsonNodes (like TextNode)
  • #4566: Enable DeserializationFeature.READ_ENUMS_USING_TO_STRING by default
  • #4567: Enable SerializationFeature.WRITE_ENUMS_USING_TO_STRING by default
  • #4572: Change MapperFeature.SORT_PROPERTIES_ALPHABETICALLY default to true (3.x)
  • #4589: Remove MapperFeature.SORT_CREATOR_PROPERTIES_BY_DECLARATION_ORDER from 3.0; make logic default
  • #4664: Change EnumNamingStrategy.convertEnumToExternalName() to take MapperConfig argument
  • #4835: Remove dynamic work-arounds wrt accessing Record definition
  • #4858: Change default of DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES to true for 3.0

Naming changes

  • #3037: Rename Module as JacksonModule in 3.0 (to avoid overlap with java.lang.Module)
  • #3043: Rename SerializerProvider as SerializationContext
  • #3044: Rename JsonDeserializer/JsonSerializer as ValueDeserializer/ValueSerializer
  • #3046: Rename JsonSerializable as JacksonSerializable
  • #3047: Rename Bean[De]SerializerModifier as Value[De]SerializerModifier
  • #4818: Rename AnnotationIntrospector.findDefaultCreator() as findPreferredCreator()

New features

  • #1789: Add createGenerator methods in ObjectMapper, ObjectWriter
  • #1790: Add createParser methods in ObjectMapper, ObjectReader
  • #1883: Add "abstract type mapping" for deserialization from Map<ENUMTYPE,V> into EnumMap (and Set<ENUMTYPE> to EnumSet<EnumType>)
  • #1954: Add Builder pattern for creating configured ObjectMapper instances
  • #1955: Change the way Modules configure, interact with ObjectMapper
  • #2013: Allow use of java.nio.file.Path for readValue(), writeValue()
  • #2382: Support AutoCloseable with SerializationFeature.CLOSE_CLOSEABLE
  • #2411: valueToTree() during serialization (via SerializerProvider())
  • #2828: Add DatabindException as intermediate subtype of JsonMappingException
  • #3522: Support serializing ByteArrayOutputStream as "simple" Binary value
  • #3536: Create new exception type JsonNodeException for use by JsonNode-related problems

Changes, dataformats

Avro

  • #522: JSTEP-8: rename AvroParser.Feature as AvroReadFeature, AvroGenerator.Feature as AvroWriteFeature

CBOR

  • #524: JSTEP-8: rename CBORGenerator.Feature as CBORWriteFeature

CSV

  • #510: JSTEP-8: rename CsvParser.Feature as CsvReadFeature, CsvGenerator.Feature as CsvWriteFeature

Ion

  • #526: JSTEP-8: rename IonParser.Feature as IonReadFeature, IonGenerator.Feature as IonWriteFeature

Smile

  • #528: JSTEP-8: rename SmileParser.Feature as SmileReadFeature, SmileGenerator.Feature as SmileWriteFeature

XML

  • #687: JSTEP-8: rename FromXmlParser.Feature as XmlReadFeature, ToXmlGenerator.Feature as XmlWriteFeature

YAML

  • #512: JSTEP-8: rename YAMLParser.Feature as YAMLReadFeature, YAMLGenerator.Feature as YAMLWriteFeature

Changes, datatypes

Guava

  • #24: Support for Guava's Immutable{Double,Int,Long}Array
  • #69: Add support for Guava primitives during deserialization

Changes, Providers

JAX-RS Providers

  • #123: Change jackson-module-jaxb-annotations dependency to optional in pom.xmls

Jakarta-RS Providers

  • Change jackson-module-jakarta-xmlbind-annotations dependency to optional in pom.xmls

Changes, JVM Languages

Changes, Other modules

Clone this wiki locally