databricks/jackson-module-scala

databricks/jackson-module-scala

Description: Add-on module for Jackson (https://github.com/FasterXML/jackson) to support Scala-specific datatypes

License: Apache-2.0

Stars: 1

Forks: 0

Open issues: 0

Created: 2023-05-16T21:32:53Z

Pushed: 2023-05-22T16:53:29Z

Default branch: 2.16

Fork: yes

Parent repository: FasterXML/jackson-module-scala

Archived: no

README: !Build Status  

Overview

[Jackson] is a fast JSON processor for Java that supports three models: streaming, node, and object mapping (akin to the three independent models [SAX]/[Stax], [DOM] and [JAXB] for XML processing).

The object mapping model is a high-level processing model that allows the user to project JSON data onto a domain-specific data model appropriate for their application, without having to deal with the low-level mechanics of JSON parsing. It is the standard object mapping parser implementaton in [Jersey], the reference implementation for JSR-311 (Java API for Restful Web Services).

[Scala] is a functional programming language for the JVM that supports Java interoperability. Its standard library is quite distinct from Java, and does not fulfill the expectations of Jacksons default mappings. Notably, Scala collections do not derive from java.util.Collection or its subclasses, and Scala properties do not (by default) look like Java Bean properties.

The Scala Module supports serialization and limited deserialization of Scala Case Classes, Sequences, Maps, Tuples, Options, and Enumerations.

Version Support

Jackson-module-scala follows the same release strategy of jackson-databind. Master branch is used for Jackson 3 development. The latest releases are v2.12.x.

Scala 2.11, 2.12 and 2.13 are supported. Scala 2.10 support was dropped in v2.12.0. Java 8 is the minimum supported version now.

Scala 3

Scala 3 support was added in v2.13.0. This support is still deemed to be experimental. Code contributions are welcomed.

• ScalaObjectMapper is not supported for Scala 3 but ClassTagExtensions is its replacement. (https://github.com/FasterXML/jackson-module-scala/issues/503)
• There are still a few tests that work with Scala 2 that fail with Scala 3
• It is expected that most use cases should work ok with Scala 3
• Known issues with using jackson-module-scala with Scala 3 are tracked at https://github.com/FasterXML/jackson-module-scala/labels/scala3
• There has been no testing of using Scala 3 classes with Scala 2 jackson-module-scala or Scala 2 classes with Scala 3 jackson-module-scala

Usage

To use the Scala Module in Jackson, simply register it with the ObjectMapper instance:

// With 2.10 and later
val mapper = JsonMapper.builder()
.addModule(DefaultScalaModule)
.build()

// versions before 2.10 (also support for later 2.x but not 3.0)
val mapper = new ObjectMapper()
mapper.registerModule(DefaultScalaModule)

DefaultScalaModule is a Scala object that includes support for all currently supported Scala data types. If only partial support is desired, the component traits can be included individually:

val module = new OptionModule with TupleModule {}
val mapper = JsonMapper.builder()
.addModule(module)
.build()

One Scala module that isn't part of DefaultScalaModule is ScalaObjectDeserializerModule. This module is used to ensure that deserialization to a Scala object does not create a new instance of the object. This latter module is not yet included in DefaultScalaModule for backward compatibility reasons. It is included in the v3.0.0, which is still under development.

DeserializationFeature.FAIL_ON_NULL_CREATOR_PROPERTIES

It is recommended that Scala users enable DeserializationFeature.FAIL_ON_NULL_CREATOR_PROPERTIES. This feature means that when you deserialize JSON and bind to a Scala/Java class and a required field is missing (or null), then the deserialization call will fail with a com.fasterxml.jackson.databind.exc.MismatchedInputException. By default, the deserialization call will succeed and a null value will be set for the field.

val mapper = JsonMapper.builder()
.addModule(DefaultScalaModule)
.enable(DeserializationFeature.FAIL_ON_NULL_CREATOR_PROPERTIES)
.build()

ClassTagExtensions

You can also mixin ClassTagExtensions to get rich wrappers that automatically convert scala ClassTags directly into TypeReferences for Jackson to use:

val mapper = JsonMapper.builder().addModule(DefaultScalaModule).build() :: ClassTagExtensions
// or using old style
//val mapper = new ObjectMapper() with ClassTagExtensions
//mapper.registerModule(DefaultScalaModule)
val myMap = mapper.readValue[Map[String, Tuple2[Int,Int]]](src)

ClassTagExtensions is a replacement for ScalaObjectMapper, which was recently deprecated because it relies on Manifests and they are not supported in Scala 3.

This is the equivalent of

val mapper = JsonMapper.builder().addModule(DefaultScalaModule).build()
val myMap = mapper.readValue(src, new TypeReference[Map[String,Tuple2[Int,Int]]]{})

Consult the Scaladoc for further details.

Sbt

To import in sbt:

libraryDependencies += "com.fasterxml.jackson.module" %% "jackson-module-scala" % "2.14.1"

Java/Kotlin users

DefaultScalaModule is a Scala Object and to access it when you are not compiling with Scala compiler, you will need to use DefaultScalaModule$.MODULE$ instead.

import com.fasterxml.jackson.module.scala.DefaultScalaModule$;

ObjectMapper mapper = JsonMapper.builder().addModule(DefaultScalaModule$.MODULE$).build();

Building

The master branch often depends on…