Merge pull request #1250 from commercetools/BMU-2922_sdk_20_jackson_3

feat: support JVM SDK 20 and Jackson 3

Author: nicolasnieto92

.github/workflows/cd.yml

@@ -22,6 +22,10 @@ jobs:
     steps:
       - name: Git Checkout
         uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          java-version: 17
+          distribution: 'zulu'
       - name: Fetch Library version
         id: vars
         run: echo libVersion=${GITHUB_REF#refs/*/} >> $GITHUB_OUTPUT
@@ -45,7 +49,7 @@ jobs:
       - name: Set up Java
         uses: actions/setup-java@v4
         with:
-          java-version: 11
+          java-version: 17
           distribution: 'zulu'
       - name: status
         run: echo Build is tagged. Uploading artifact ${{ steps.vars.outputs.tag }} to maven central.

.github/workflows/ci.yml

@@ -9,6 +9,10 @@ jobs:
     steps:
       - name: Git Checkout
         uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          java-version: 17
+          distribution: 'zulu'
       - name: Generate Dependency Updates Report
         run: ./gradlew clean dependencyUpdates
       - name: Code formatting
@@ -28,7 +32,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-java@v4
         with:
-          java-version: 11
+          java-version: 17
           distribution: 'zulu'
       - name: Build with Gradle
         run: ./gradlew clean setLibraryVersion test integrationTest jacocoTestCoverageVerification jacocoTestReport
@@ -58,6 +62,10 @@ jobs:
     steps:
       - name: Git Checkout
         uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          java-version: 17
+          distribution: 'zulu'
       - name: Fetch Library version
         id: vars
         run: echo libVersion=${GITHUB_REF#refs/*/} >> $GITHUB_OUTPUT

README.md

@@ -2,7 +2,7 @@
 # commercetools sync java
 [![CI](https://github.com/commercetools/commercetools-sync-java/workflows/CI/badge.svg)](https://github.com/commercetools/commercetools-sync-java/actions?query=workflow%3ACI)
 [![codecov](https://codecov.io/gh/commercetools/commercetools-sync-java/branch/master/graph/badge.svg)](https://codecov.io/gh/commercetools/commercetools-sync-java)
-[![Javadoc](https://javadoc.io/badge2/com.commercetools/commercetools-sync-java/javadoc.svg?label=Javadoc)](https://commercetools.github.io/commercetools-sync-java/v/10.0.6/)
+[![Javadoc](https://javadoc.io/badge2/com.commercetools/commercetools-sync-java/javadoc.svg?label=Javadoc)](https://commercetools.github.io/commercetools-sync-java/v/11.0.0/)
 [![Known Vulnerabilities](https://snyk.io/test/github/commercetools/commercetools-sync-java/4b2e26113d591bda158217c5dc1cf80a88665646/badge.svg)](https://snyk.io/test/github/commercetools/commercetools-sync-java/4b2e26113d591bda158217c5dc1cf80a88665646)
 
 
@@ -47,8 +47,8 @@ Notes:
 
 ### Prerequisites
 
- - Library requires the min JDK version `>= 11`.
-   > The library tested with each major JDK version (i.e: 11, 12, 13...) as well as some specific updates of LTS versions (i.e: 11.0.3 and above).
+ - Library requires the min JDK version `>= 17`.
+   > Version 11.x of the library uses [JVM-SDK-V2](http://commercetools.github.io/commercetools-sdk-java-v2) 20.x, which is based on Jackson 3. If your application uses JVM SDK 19.x or earlier (based on Jackson 2), or runs on JDK 11 to 16, use version 10.x of this library.
  - A target commercetools project for syncing your source data to.
 
 ### Installation
@@ -62,26 +62,26 @@ Here are the most popular ones:
 <dependency>
   <groupId>com.commercetools</groupId>
   <artifactId>commercetools-sync-java</artifactId>
-  <version>10.0.7</version>
+  <version>11.0.0</version>
 </dependency>
 ````
 
 #### Gradle
 
 ````groovy
-implementation 'com.commercetools:commercetools-sync-java:10.0.7'
+implementation 'com.commercetools:commercetools-sync-java:11.0.0'
 ````
 
 #### SBT 
 
 ````
-libraryDependencies += "com.commercetools" % "commercetools-sync-java" % "10.0.7"
+libraryDependencies += "com.commercetools" % "commercetools-sync-java" % "11.0.0"
 ````
 
 #### Ivy 
 
 ````xml
-<dependency org="com.commercetools" name="commercetools-sync-java" rev="10.0.7"/>
+<dependency org="com.commercetools" name="commercetools-sync-java" rev="11.0.0"/>
 ````
 
 **Note**: To avoid `commercetools JVM SDK` libraries version mismatch between projects.
@@ -111,6 +111,7 @@ For Maven users, remove:
 
 If you want to use a different `commercetools JVM SDK` version than the version used in this project. 
 , below you will find examples on how to exclude `commercetools JVM SDK` from commercetools-sync-java library. Beware that library might not work with the older `commercetools JVM SDK` versions.
+In particular, version 10.x of the library doesn't work with JVM SDK 20.x, and version 11.x doesn't work with JVM SDK 19.x or earlier, because they are based on different major versions of Jackson.
 
 For Gradle:
 ````groovy

build.gradle

@@ -9,7 +9,7 @@ plugins {
 }
 
 ext{
-    commercetoolsJavaSdkV2Version = '19.3.0'
+    commercetoolsJavaSdkV2Version = '20.2.0'
     mockitoJunitJupiterVersion = '5.20.0'
     jupiterApiVersion = '5.14.1'
     jupiterPlatformVersion = '1.14.1'

docs/README.md

@@ -2,9 +2,9 @@
 # commercetools sync
 [![CI](https://github.com/commercetools/commercetools-sync-java/workflows/CI/badge.svg)](https://github.com/commercetools/commercetools-sync-java/actions?query=workflow%3ACI)
 [![codecov](https://codecov.io/gh/commercetools/commercetools-sync-java/branch/master/graph/badge.svg)](https://codecov.io/gh/commercetools/commercetools-sync-java)
-[![Benchmarks 10.0.7](https://img.shields.io/badge/Benchmarks-10.0.7-orange.svg)](https://commercetools.github.io/commercetools-sync-java/benchmarks/)
-[![Download from Maven Central](https://img.shields.io/badge/Maven_Central-10.0.7-blue.svg)](https://search.maven.org/artifact/com.commercetools/commercetools-sync-java/10.0.7/jar) 
-[![Javadoc](https://javadoc.io/badge2/com.commercetools/commercetools-sync-java/javadoc.svg?label=Javadoc)](https://commercetools.github.io/commercetools-sync-java/v/10.0.7/)
+[![Benchmarks 11.0.0](https://img.shields.io/badge/Benchmarks-11.0.0-orange.svg)](https://commercetools.github.io/commercetools-sync-java/benchmarks/)
+[![Download from Maven Central](https://img.shields.io/badge/Maven_Central-11.0.0-blue.svg)](https://search.maven.org/artifact/com.commercetools/commercetools-sync-java/11.0.0/jar) 
+[![Javadoc](https://javadoc.io/badge2/com.commercetools/commercetools-sync-java/javadoc.svg?label=Javadoc)](https://commercetools.github.io/commercetools-sync-java/v/11.0.0/)
 [![Known Vulnerabilities](https://snyk.io/test/github/commercetools/commercetools-sync-java/4b2e26113d591bda158217c5dc1cf80a88665646/badge.svg)](https://snyk.io/test/github/commercetools/commercetools-sync-java/4b2e26113d591bda158217c5dc1cf80a88665646)
 
 
@@ -28,8 +28,8 @@ Notes:
 
 ### Prerequisites
 
-- Library requires the min JDK version `>= 8`.
-  > The library tested with each major JDK version (i.e: 8, 9, 10, 11, 12, 13...) as well as some specific updates of LTS versions (i.e: 8.0.192, 11.0.3).
+- Library requires the min JDK version `>= 17`.
+  > Version 11.x of the library uses [JVM-SDK-V2](http://commercetools.github.io/commercetools-sdk-java-v2) 20.x, which is based on Jackson 3. If your application uses JVM SDK 19.x or earlier (based on Jackson 2), or runs on JDK 11 to 16, use version 10.x of this library.
 - A target commercetools project for syncing your source data to.
 
 ### Installation
@@ -40,18 +40,18 @@ Here are the most popular ones:
 <dependency>
   <groupId>com.commercetools</groupId>
   <artifactId>commercetools-sync-java</artifactId>
-  <version>10.0.7</version>
+  <version>11.0.0</version>
 </dependency>
 ````
 #### Gradle
 ````groovy
-implementation 'com.commercetools:commercetools-sync-java:10.0.7'
+implementation 'com.commercetools:commercetools-sync-java:11.0.0'
 ````
 #### SBT 
 ````
-libraryDependencies += "com.commercetools" % "commercetools-sync-java" % "10.0.7"
+libraryDependencies += "com.commercetools" % "commercetools-sync-java" % "11.0.0"
 ````
 #### Ivy 
 ````xml
-<dependency org="com.commercetools" name="commercetools-sync-java" rev="10.0.7"/>
+<dependency org="com.commercetools" name="commercetools-sync-java" rev="11.0.0"/>
 ````

docs/RELEASE_NOTES.md

@@ -27,6 +27,22 @@
 7. Add Migration guide section which specifies explicitly if there are breaking changes and how to tackle them.
 -->
 
+### 11.0.0 - Oct 19, 2026
+[Commits](https://github.com/commercetools/commercetools-sync-java/compare/10.5.0...11.0.0) |
+[Javadoc](https://commercetools.github.io/commercetools-sync-java/v/11.0.0/) |
+[Jar](https://search.maven.org/artifact/com.commercetools/commercetools-sync-java/11.0.0/jar)
+
+This release makes the library compatible with commercetools JVM SDK 20.x and Jackson 3. Use version 11.x with JVM SDK 20.x, and keep using version 10.x with JVM SDK 19.x or earlier.
+Unresolved references that version 10.x stored as custom objects keep working after the upgrade, because their JSON format didn't change.
+
+- 🚧 **Breaking Changes** (4)
+  - Minimum Java 17 or above is required.
+  - The library now uses commercetools JVM SDK 20.x, which is based on Jackson 3 (package `tools.jackson`) instead of Jackson 2 (package `com.fasterxml.jackson`). Using version 10.x of the library with JVM SDK 20.x fails at runtime with a `NoSuchMethodError`.
+  - Public methods that take or return Jackson types now use the Jackson 3 types, for example `tools.jackson.databind.JsonNode` instead of `com.fasterxml.jackson.databind.JsonNode`. This affects `CustomValueConverter`, `AttributeUtils`, `ResourceIdentifierUtils.isReferenceOfType(JsonNode, String)` and the protected helpers of `BaseTransformServiceImpl`. If you call them, update your Jackson imports, see the [Jackson 3 migration guide](https://github.com/FasterXML/jackson/blob/main/jackson3/MIGRATING_TO_JACKSON_3.md).
+  - Jackson 3 exceptions are unchecked: `JacksonException`, which extends `RuntimeException`, replaces the checked `JsonProcessingException`. Code that catches `JsonProcessingException`, for example around the SDK's `JsonUtils.toJsonString`, no longer compiles. Catch `JacksonException` instead, or remove the `try`/`catch` if it was only there because the exception was checked.
+- 🛠️ **Dependency Updates** (1)
+  - `commercetools-sdk-java-api` and `commercetools-http-client` `19.3.0` -> `20.2.0`
+
 ### 10.5.0 - Jan 07, 2026
 [Commits](https://github.com/commercetools/commercetools-sync-java/compare/10.4.0...10.5.0) |
 [Javadoc](https://commercetools.github.io/commercetools-sync-java/v/10.5.0/) |

docs/usage/QUICK_START.md

@@ -12,21 +12,21 @@
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ### 1. Installation
-- Make sure you have `JDK 11` or higher installed.
+- Make sure you have `JDK 17` or higher installed.
 - Add the following dependency in your application:
 - For Maven users: 
 ````xml
 <!-- Add commercetools-sync-java dependency. -->
 <dependency>
   <groupId>com.commercetools</groupId>
   <artifactId>commercetools-sync-java</artifactId>
-  <version>10.0.4</version>
+  <version>11.0.0</version>
 </dependency>
 ````
 - For Gradle users:
 ````groovy
 // Add commercetools-sync-java dependency.
-implementation 'com.commercetools:commercetools-sync-java:10.0.4'
+implementation 'com.commercetools:commercetools-sync-java:11.0.0'
 ````
 
 ### 2. Setup Syncing Options

gradle-scripts/java-compile.gradle

@@ -1,5 +1,5 @@
-sourceCompatibility = 11
-targetCompatibility = 11
+sourceCompatibility = 17
+targetCompatibility = 17
 tasks.withType(JavaCompile) {
     options.encoding = 'UTF-8'
     options.compilerArgs << "-Xlint:unchecked" << "-Xlint:deprecation"

src/benchmark/java/com/commercetools/sync/benchmark/BenchmarkUtils.java

@@ -2,16 +2,16 @@
 
 import static java.util.Optional.ofNullable;
 
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.databind.node.JsonNodeFactory;
-import com.fasterxml.jackson.databind.node.ObjectNode;
 import java.io.IOException;
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 import javax.annotation.Nonnull;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.node.JsonNodeFactory;
+import tools.jackson.databind.node.ObjectNode;
 
 final class BenchmarkUtils {
   private static final String BENCHMARK_RESULTS_FILE_NAME = "benchmarks.json";

src/integration-test/java/com/commercetools/sync/integration/commons/utils/ITUtils.java

@@ -38,11 +38,6 @@
 import com.commercetools.api.models.type.Type;
 import com.commercetools.api.models.type.TypeDraft;
 import com.commercetools.api.models.type.TypeDraftBuilder;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.databind.ObjectWriter;
-import com.fasterxml.jackson.databind.node.JsonNodeFactory;
-import com.fasterxml.jackson.databind.node.ObjectNode;
 import io.vrap.rmf.base.client.ApiHttpResponse;
 import io.vrap.rmf.base.client.error.BadGatewayException;
 import io.vrap.rmf.base.client.error.NotFoundException;
@@ -56,6 +51,11 @@
 import java.util.stream.IntStream;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.ObjectWriter;
+import tools.jackson.databind.node.JsonNodeFactory;
+import tools.jackson.databind.node.ObjectNode;
 
 /** This class is meant only meant for internal use of the library's integration tests. */
 public final class ITUtils {
@@ -534,7 +534,7 @@ private static String getErrorResponseJsonString(Integer errorCode) {
     String json;
     try {
       json = ow.writeValueAsString(errorResponse);
-    } catch (JsonProcessingException e) {
+    } catch (JacksonException e) {
       // ignore the error
       json = null;
     }