Add a converter for Jackson 3

This mostly copies the existing Jackson (2) converter and does the
necessary migration [1]. Note that Jackson 3 requires Java 17.

[1]: https://github.com/FasterXML/jackson/blob/main/jackson3/MIGRATING_TO_JACKSON_3.md

Author: sschuberth

gradle/libs.versions.toml

@@ -22,6 +22,7 @@ autoService = "1.1.1"
 incap = "1.0.0"
 jackson = "2.20.1"
 jacksonAnnotations = "2.20"
+jackson3 = "3.0.1"
 
 [libraries]
 androidPlugin = { module = "com.android.tools.build:gradle", version = "8.13.0" }
@@ -73,6 +74,8 @@ gson = { module = "com.google.code.gson:gson", version = "2.13.2" }
 jacksonAnnotations = { module = "com.fasterxml.jackson.core:jackson-annotations", version.ref = "jacksonAnnotations" }
 jacksonDatabind = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" }
 jacksonDataformatCbor = { module = "com.fasterxml.jackson.dataformat:jackson-dataformat-cbor", version.ref = "jackson" }
+jackson3Databind = { module = "tools.jackson.core:jackson-databind", version.ref = "jackson3" }
+jackson3DataformatCbor = { module = "tools.jackson.dataformat:jackson-dataformat-cbor", version.ref = "jackson3" }
 jaxbApi = { module = "javax.xml.bind:jaxb-api", version = "2.3.1" }
 jaxbImpl = { module = "org.glassfish.jaxb:jaxb-runtime", version = "4.0.6" }
 jaxb3Api = { module = "jakarta.xml.bind:jakarta.xml.bind-api", version = "3.0.1" }

retrofit-converters/jackson3/README.md

@@ -0,0 +1,34 @@
+Jackson Converter
+=================
+
+A `Converter` which uses [Jackson][1] 3 for serialization to and from JSON.
+
+A default `ObjectMapper` instance will be created or one can be configured and passed to the
+`JacksonConverterFactory` construction to further control the serialization.
+
+
+Download
+--------
+
+Download [the latest JAR][2] or grab via [Maven][3]:
+```xml
+<dependency>
+  <groupId>com.squareup.retrofit2</groupId>
+  <artifactId>converter-jackson3</artifactId>
+  <version>latest.version</version>
+</dependency>
+```
+or [Gradle][3]:
+```groovy
+implementation 'com.squareup.retrofit2:converter-jackson3:latest.version'
+```
+
+Snapshots of the development version are available in [Sonatype's `snapshots` repository][snap].
+
+
+
+ [1]: https://github.com/FasterXML/jackson
+ [2]: https://search.maven.org/remote_content?g=com.squareup.retrofit2&a=converter-jackson3&v=LATEST
+ [3]: http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.squareup.retrofit2%22%20a%3A%22converter-jackson3%22
+ [snap]: https://s01.oss.sonatype.org/content/repositories/snapshots/
+

retrofit-converters/jackson3/build.gradle

@@ -0,0 +1,27 @@
+apply plugin: 'java-library'
+apply plugin: 'com.vanniktech.maven.publish'
+
+dependencies {
+  api projects.retrofit
+  api libs.jackson3Databind
+  compileOnly libs.findBugsAnnotations
+
+  testImplementation libs.junit
+  testImplementation libs.truth
+  testImplementation libs.okhttp.mockwebserver
+  testImplementation libs.testParameterInjector
+  testImplementation libs.jacksonAnnotations
+  testImplementation libs.jackson3DataformatCbor
+}
+
+jar {
+  manifest {
+    attributes  'Automatic-Module-Name': 'retrofit2.converter.jackson3'
+  }
+}
+
+java {
+  toolchain {
+    languageVersion = JavaLanguageVersion.of(17)
+  }
+}

retrofit-converters/jackson3/gradle.properties

@@ -0,0 +1,3 @@
+POM_ARTIFACT_ID=converter-jackson3
+POM_NAME=Converter: Jackson3
+POM_DESCRIPTION=A Retrofit Converter which uses Jackson 3 for serialization.

retrofit-converters/jackson3/src/main/java/retrofit2/converter/jackson3/JacksonConverterFactory.java

@@ -0,0 +1,99 @@
+/*
+ * Copyright (C) 2015 Square, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package retrofit2.converter.jackson3;
+
+import tools.jackson.databind.JavaType;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.ObjectReader;
+import tools.jackson.databind.ObjectWriter;
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Type;
+import okhttp3.MediaType;
+import okhttp3.RequestBody;
+import okhttp3.ResponseBody;
+import retrofit2.Call;
+import retrofit2.Converter;
+import retrofit2.Retrofit;
+
+/**
+ * A {@linkplain Converter.Factory converter} which uses Jackson.
+ *
+ * <p>Because Jackson is so flexible in the types it supports, this converter assumes that it can
+ * handle all types. If you are mixing JSON serialization with something else (such as protocol
+ * buffers), you must {@linkplain Retrofit.Builder#addConverterFactory(Converter.Factory) add this
+ * instance} last to allow the other converters a chance to see their types.
+ */
+public final class JacksonConverterFactory extends Converter.Factory {
+  private static final MediaType DEFAULT_MEDIA_TYPE =
+      MediaType.get("application/json; charset=UTF-8");
+
+  /** Create an instance using a default {@link ObjectMapper} instance for conversion. */
+  public static JacksonConverterFactory create() {
+    return new JacksonConverterFactory(new ObjectMapper(), DEFAULT_MEDIA_TYPE, false);
+  }
+
+  /** Create an instance using {@code mapper} for conversion. */
+  public static JacksonConverterFactory create(ObjectMapper mapper) {
+    return create(mapper, DEFAULT_MEDIA_TYPE);
+  }
+
+  /** Create an instance using {@code mapper} and {@code mediaType} for conversion. */
+  @SuppressWarnings("ConstantConditions") // Guarding public API nullability.
+  public static JacksonConverterFactory create(ObjectMapper mapper, MediaType mediaType) {
+    if (mapper == null) throw new NullPointerException("mapper == null");
+    if (mediaType == null) throw new NullPointerException("mediaType == null");
+    return new JacksonConverterFactory(mapper, mediaType, false);
+  }
+
+  private final ObjectMapper mapper;
+  private final MediaType mediaType;
+  private final boolean streaming;
+
+  private JacksonConverterFactory(ObjectMapper mapper, MediaType mediaType, boolean streaming) {
+    this.mapper = mapper;
+    this.mediaType = mediaType;
+    this.streaming = streaming;
+  }
+
+  /**
+   * Return a new factory which streams serialization of request messages to bytes on the HTTP thread
+   * This is either the calling thread for {@link Call#execute()}, or one of OkHttp's background
+   * threads for {@link Call#enqueue}. Response bytes are always converted to message instances on
+   * one of OkHttp's background threads.
+   */
+  public JacksonConverterFactory withStreaming() {
+    return new JacksonConverterFactory(mapper, mediaType, true);
+  }
+
+  @Override
+  public Converter<ResponseBody, ?> responseBodyConverter(
+      Type type, Annotation[] annotations, Retrofit retrofit) {
+    JavaType javaType = mapper.getTypeFactory().constructType(type);
+    ObjectReader reader = mapper.readerFor(javaType);
+    return new JacksonResponseBodyConverter<>(reader);
+  }
+
+  @Override
+  public Converter<?, RequestBody> requestBodyConverter(
+      Type type,
+      Annotation[] parameterAnnotations,
+      Annotation[] methodAnnotations,
+      Retrofit retrofit) {
+    JavaType javaType = mapper.getTypeFactory().constructType(type);
+    ObjectWriter writer = mapper.writerFor(javaType);
+    return new JacksonRequestBodyConverter<>(writer, mediaType, streaming);
+  }
+}

retrofit-converters/jackson3/src/main/java/retrofit2/converter/jackson3/JacksonRequestBodyConverter.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright (C) 2015 Square, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package retrofit2.converter.jackson3;
+
+import tools.jackson.databind.ObjectWriter;
+import java.io.IOException;
+import okhttp3.MediaType;
+import okhttp3.RequestBody;
+import retrofit2.Converter;
+
+final class JacksonRequestBodyConverter<T> implements Converter<T, RequestBody> {
+  private final ObjectWriter adapter;
+  private final MediaType mediaType;
+  private final boolean streaming;
+
+  JacksonRequestBodyConverter(ObjectWriter adapter, MediaType mediaType, boolean streaming) {
+    this.adapter = adapter;
+    this.mediaType = mediaType;
+    this.streaming = streaming;
+  }
+
+  @Override
+  public RequestBody convert(T value) throws IOException {
+    if (streaming) {
+      return new JacksonStreamingRequestBody(adapter, value, mediaType);
+    }
+
+    byte[] bytes = adapter.writeValueAsBytes(value);
+    return RequestBody.create(mediaType, bytes);
+  }
+}

retrofit-converters/jackson3/src/main/java/retrofit2/converter/jackson3/JacksonResponseBodyConverter.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright (C) 2015 Square, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package retrofit2.converter.jackson3;
+
+import tools.jackson.databind.ObjectReader;
+import java.io.IOException;
+import okhttp3.ResponseBody;
+import retrofit2.Converter;
+
+final class JacksonResponseBodyConverter<T> implements Converter<ResponseBody, T> {
+  private final ObjectReader adapter;
+
+  JacksonResponseBodyConverter(ObjectReader adapter) {
+    this.adapter = adapter;
+  }
+
+  @Override
+  public T convert(ResponseBody value) throws IOException {
+    try {
+      return adapter.readValue(value.byteStream());
+    } finally {
+      value.close();
+    }
+  }
+}

retrofit-converters/jackson3/src/main/java/retrofit2/converter/jackson3/JacksonStreamingRequestBody.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright (C) 2025 Square, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package retrofit2.converter.jackson3;
+
+import tools.jackson.databind.ObjectWriter;
+import java.io.IOException;
+import okhttp3.MediaType;
+import okhttp3.RequestBody;
+import okio.BufferedSink;
+
+final class JacksonStreamingRequestBody extends RequestBody {
+  private final ObjectWriter adapter;
+  private final Object value;
+  private final MediaType mediaType;
+
+  public JacksonStreamingRequestBody(ObjectWriter adapter, Object value, MediaType mediaType) {
+    this.adapter = adapter;
+    this.value = value;
+    this.mediaType = mediaType;
+  }
+
+  @Override
+  public MediaType contentType() {
+    return mediaType;
+  }
+
+  @Override
+  public void writeTo(BufferedSink sink) throws IOException {
+    adapter.writeValue(sink.outputStream(), value);
+  }
+}

retrofit-converters/jackson3/src/main/java/retrofit2/converter/jackson3/package-info.java

@@ -0,0 +1,2 @@
+@retrofit2.internal.EverythingIsNonNull
+package retrofit2.converter.jackson3;

retrofit-converters/jackson3/src/test/java/retrofit2/converter/jackson3/JacksonCborConverterFactoryTest.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright (C) 2024 Square, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package retrofit2.converter.jackson3;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import tools.jackson.dataformat.cbor.CBORMapper;
+import java.io.IOException;
+import okhttp3.MediaType;
+import okhttp3.mockwebserver.MockResponse;
+import okhttp3.mockwebserver.MockWebServer;
+import okhttp3.mockwebserver.RecordedRequest;
+import okio.Buffer;
+import okio.ByteString;
+import org.junit.Before;
+import org.junit.Rule;
+import org.junit.Test;
+import retrofit2.Call;
+import retrofit2.Response;
+import retrofit2.Retrofit;
+import retrofit2.http.Body;
+import retrofit2.http.POST;
+
+public class JacksonCborConverterFactoryTest {
+  static class IntWrapper {
+    public int value;
+
+    public IntWrapper(int v) {
+      value = v;
+    }
+
+    protected IntWrapper() {}
+  }
+
+  interface Service {
+    @POST("/")
+    Call<IntWrapper> post(@Body IntWrapper person);
+  }
+
+  @Rule public final MockWebServer server = new MockWebServer();
+
+  private Service service;
+
+  @Before
+  public void setUp() {
+    Retrofit retrofit =
+        new Retrofit.Builder()
+            .baseUrl(server.url("/"))
+            .addConverterFactory(
+                JacksonConverterFactory.create(new CBORMapper(), MediaType.get("application/cbor")))
+            .build();
+    service = retrofit.create(Service.class);
+  }
+
+  @Test
+  public void post() throws IOException, InterruptedException {
+    server.enqueue(
+        new MockResponse()
+            .setBody(new Buffer().write(ByteString.decodeHex("bf6576616c7565182aff"))));
+
+    Call<IntWrapper> call = service.post(new IntWrapper(12));
+    Response<IntWrapper> response = call.execute();
+    assertThat(response.body().value).isEqualTo(42);
+
+    RecordedRequest request = server.takeRequest();
+    assertThat(request.getBody().readByteString())
+        .isEqualTo(ByteString.decodeHex("bf6576616c75650cff"));
+    assertThat(request.getHeader("Content-Type")).isEqualTo("application/cbor");
+  }
+}