Migrate JSON bindings to Jackson 3

.github/workflows/maven.yml

@@ -57,6 +57,17 @@ jobs:
             echo 'HC_BUILD_TOOLCHAIN_VERSION=${{ matrix.java }}' >> "$GITHUB_ENV"
             ;;
         esac
+        # The httpcore5-jackson3 module is compiled for Java 17 (Jackson 3
+        # requirement), so it must be excluded from the reactor whenever the
+        # selected toolchain is older than 17.
+        case '${{ matrix.java }}' in
+          8|11)
+            echo 'HC_PROFILE_ARGS=-Dhc.jackson3.skip=true' >> "$GITHUB_ENV"
+            ;;
+          *)
+            echo 'HC_PROFILE_ARGS=' >> "$GITHUB_ENV"
+            ;;
+        esac
     - name: Set up toolchain JDK ${{ matrix.java }}
       id: setup-java-toolchain
       uses: actions/setup-java@v5
@@ -88,4 +99,4 @@ jobs:
         </toolchains>
         EOF
     - name: Build with Maven
-      run: ./mvnw -V --file pom.xml --no-transfer-progress -DtrimStackTrace=false -Djunit.jupiter.execution.parallel.enabled=false -Dhc.build.toolchain.version="${HC_BUILD_TOOLCHAIN_VERSION}" -Pdocker
+      run: ./mvnw -V --file pom.xml --no-transfer-progress -DtrimStackTrace=false -Djunit.jupiter.execution.parallel.enabled=false -Dhc.build.toolchain.version="${HC_BUILD_TOOLCHAIN_VERSION}" ${HC_PROFILE_ARGS} -Pdocker

README.md

@@ -33,7 +33,8 @@ For building from source instructions please refer to [BUILDING.txt](./BUILDING.
 Dependencies
 ------------
 
-HttpCore requires Java 1.8 compatible runtime.
+HttpCore requires Java 1.8 compatible runtime. The optional `httpcore5-jackson3`
+module depends on Jackson 3 and requires Java 17.
 
 Protocol conformance
 --------------------

httpcore5-jackson2/pom.xml → httpcore5-jackson3/pom.xml

@@ -31,12 +31,29 @@
   </parent>
   <modelVersion>4.0.0</modelVersion>
 
-  <artifactId>httpcore5-jackson2</artifactId>
-  <name>Jackson 2 bindings for Apache HttpComponents Core</name>
+  <artifactId>httpcore5-jackson3</artifactId>
+  <name>Jackson 3 bindings for Apache HttpComponents Core</name>
   <description>Apache HttpComponents JSON bindings</description>
 
   <properties>
     <Automatic-Module-Name>org.apache.httpcomponents.core5.httpcore5.json</Automatic-Module-Name>
+    <!--
+      Jackson 3 is compiled for Java 17 and cannot be read by javac 8 or 11.
+      This module therefore builds against a Java 17 toolchain, while the rest
+      of HttpCore continues to target Java 8. The root POM keeps the module out
+      of the reactor when an older toolchain is selected.
+    -->
+    <maven.compiler.source>17</maven.compiler.source>
+    <maven.compiler.target>17</maven.compiler.target>
+    <maven.compiler.release>17</maven.compiler.release>
+    <hc.build.toolchain.version>17</hc.build.toolchain.version>
+    <!--
+      Animal Sniffer derives its signature artifact from the compiler target
+      (java${major}${minor}); target 17 resolves to the non-existent
+      "java170" signature. The API-level check is moot for a module that
+      deliberately targets Java 17, so it is disabled here.
+    -->
+    <animal.sniffer.skip>true</animal.sniffer.skip>
   </properties>
 
   <dependencies>
@@ -45,9 +62,9 @@
       <artifactId>httpcore5</artifactId>
     </dependency>
     <dependency>
-      <groupId>com.fasterxml.jackson.core</groupId>
+      <groupId>tools.jackson.core</groupId>
       <artifactId>jackson-databind</artifactId>
-      <version>2.21.3</version>
+      <version>${jackson.version}</version>
     </dependency>
     <dependency>
       <groupId>org.junit.jupiter</groupId>

httpcore5-jackson3/src/main/java/org/apache/hc/core5/jackson3/JacksonSupport.java

@@ -0,0 +1,61 @@
+/*
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+package org.apache.hc.core5.jackson3;
+
+import java.io.IOException;
+
+import org.apache.hc.core5.annotation.Internal;
+
+import tools.jackson.core.JacksonException;
+
+/**
+ * Translates Jackson exceptions into {@link IOException} at the boundary between Jackson
+ * and the HttpCore I/O contracts. Jackson 3 reports stream and databind failures as
+ * unchecked {@link JacksonException}, whereas HttpCore producers and consumers declare
+ * {@link IOException}. Every Jackson call made behind such a contract must be converted
+ * here rather than allowed to escape as a runtime exception.
+ *
+ * @since 5.5
+ */
+@Internal
+public final class JacksonSupport {
+
+    private JacksonSupport() {
+    }
+
+    /**
+     * Wraps a Jackson exception as an {@link IOException}, preserving it as the cause.
+     *
+     * @param ex the Jackson exception to translate
+     * @return an {@link IOException} carrying the same message and the given cause
+     * @since 5.5
+     */
+    public static IOException asIOException(final JacksonException ex) {
+        return new IOException(ex.getMessage(), ex);
+    }
+
+}

httpcore5-jackson2/src/main/java/org/apache/hc/core5/jackson2/JsonAsyncTokenizer.java → httpcore5-jackson3/src/main/java/org/apache/hc/core5/jackson3/JsonAsyncTokenizer.java

@@ -24,16 +24,17 @@
  * <http://www.apache.org/>.
  *
  */
-package org.apache.hc.core5.jackson2;
+package org.apache.hc.core5.jackson3;
 
 import java.io.IOException;
 import java.nio.ByteBuffer;
 
-import com.fasterxml.jackson.core.JsonFactory;
-import com.fasterxml.jackson.core.JsonParser;
-import com.fasterxml.jackson.core.JsonToken;
-import com.fasterxml.jackson.core.JsonTokenId;
-import com.fasterxml.jackson.core.async.ByteArrayFeeder;
+import tools.jackson.core.TokenStreamFactory;
+import tools.jackson.core.JsonParser;
+import tools.jackson.core.JsonToken;
+import tools.jackson.core.JsonTokenId;
+import tools.jackson.core.ObjectReadContext;
+import tools.jackson.core.async.ByteArrayFeeder;
 
 import org.apache.hc.core5.util.Args;
 
@@ -45,13 +46,13 @@
  */
 public final class JsonAsyncTokenizer {
 
-    private final JsonFactory jsonFactory;
+    private final TokenStreamFactory jsonFactory;
 
     private JsonTokenConsumer consumer;
     private JsonParser parser;
     private ByteArrayFeeder inputFeeder;
 
-    public JsonAsyncTokenizer(final JsonFactory jsonFactory) {
+    public JsonAsyncTokenizer(final TokenStreamFactory jsonFactory) {
         this.jsonFactory = jsonFactory;
     }
 
@@ -62,8 +63,8 @@ public JsonAsyncTokenizer(final JsonFactory jsonFactory) {
      */
     public void initialize(final JsonTokenConsumer consumer) throws IOException {
         Args.notNull(consumer, "Consumer");
-        this.parser = jsonFactory.createNonBlockingByteArrayParser();
-        this.inputFeeder = (ByteArrayFeeder) parser.getNonBlockingInputFeeder();
+        this.parser = jsonFactory.createNonBlockingByteArrayParser(ObjectReadContext.empty());
+        this.inputFeeder = (ByteArrayFeeder) parser.nonBlockingInputFeeder();
         this.consumer = consumer;
     }
 

httpcore5-jackson2/src/main/java/org/apache/hc/core5/jackson2/JsonConsumer.java → httpcore5-jackson3/src/main/java/org/apache/hc/core5/jackson3/JsonConsumer.java

@@ -24,7 +24,7 @@
  * <http://www.apache.org/>.
  *
  */
-package org.apache.hc.core5.jackson2;
+package org.apache.hc.core5.jackson3;
 
 import java.io.IOException;
 

httpcore5-jackson2/src/main/java/org/apache/hc/core5/jackson2/JsonNodeAssembler.java → httpcore5-jackson3/src/main/java/org/apache/hc/core5/jackson3/JsonNodeAssembler.java

@@ -24,17 +24,17 @@
  * <http://www.apache.org/>.
  *
  */
-package org.apache.hc.core5.jackson2;
+package org.apache.hc.core5.jackson3;
 
 import java.util.LinkedList;
 import java.util.function.Consumer;
 
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.node.ArrayNode;
-import com.fasterxml.jackson.databind.node.ContainerNode;
-import com.fasterxml.jackson.databind.node.JsonNodeCreator;
-import com.fasterxml.jackson.databind.node.JsonNodeFactory;
-import com.fasterxml.jackson.databind.node.ObjectNode;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.node.ArrayNode;
+import tools.jackson.databind.node.ContainerNode;
+import tools.jackson.databind.node.JsonNodeCreator;
+import tools.jackson.databind.node.JsonNodeFactory;
+import tools.jackson.databind.node.ObjectNode;
 
 /**
  * {@link JsonTokenEventHandler} implementation that assembles an {@link JsonNode}

httpcore5-jackson2/src/main/java/org/apache/hc/core5/jackson2/JsonResultSink.java → httpcore5-jackson3/src/main/java/org/apache/hc/core5/jackson3/JsonResultSink.java

@@ -24,7 +24,7 @@
  * <http://www.apache.org/>.
  *
  */
-package org.apache.hc.core5.jackson2;
+package org.apache.hc.core5.jackson3;
 
 import java.util.function.Consumer;
 

httpcore5-jackson2/src/main/java/org/apache/hc/core5/jackson2/JsonTokenConsumer.java → httpcore5-jackson3/src/main/java/org/apache/hc/core5/jackson3/JsonTokenConsumer.java

@@ -24,11 +24,11 @@
  * <http://www.apache.org/>.
  *
  */
-package org.apache.hc.core5.jackson2;
+package org.apache.hc.core5.jackson3;
 
 import java.io.IOException;
 
-import com.fasterxml.jackson.core.JsonParser;
+import tools.jackson.core.JsonParser;
 
 /**
  * Represents an event recipient that can react to a stream of consecutive JSON tokens.
@@ -43,7 +43,7 @@ public interface JsonTokenConsumer {
      *
      * @param tokenId    Id representing of the current token held by the parser.
      * @param jsonParser the JSON parser.
-     * @see com.fasterxml.jackson.core.JsonTokenId
+     * @see tools.jackson.core.JsonTokenId
      */
     void accept(int tokenId, JsonParser jsonParser) throws IOException;
 

httpcore5-jackson2/src/main/java/org/apache/hc/core5/jackson2/JsonTokenEventHandler.java → httpcore5-jackson3/src/main/java/org/apache/hc/core5/jackson3/JsonTokenEventHandler.java

@@ -24,7 +24,7 @@
  * <http://www.apache.org/>.
  *
  */
-package org.apache.hc.core5.jackson2;
+package org.apache.hc.core5.jackson3;
 
 /**
  * Represents a handler of JSON token events.

httpcore5-jackson2/src/main/java/org/apache/hc/core5/jackson2/JsonTokenEventHandlerAdaptor.java → httpcore5-jackson3/src/main/java/org/apache/hc/core5/jackson3/JsonTokenEventHandlerAdaptor.java

@@ -24,12 +24,13 @@
  * <http://www.apache.org/>.
  *
  */
-package org.apache.hc.core5.jackson2;
+package org.apache.hc.core5.jackson3;
 
 import java.io.IOException;
 
-import com.fasterxml.jackson.core.JsonParser;
-import com.fasterxml.jackson.core.JsonTokenId;
+import tools.jackson.core.JsonParser;
+import tools.jackson.core.JsonTokenId;
+import tools.jackson.core.exc.InputCoercionException;
 
 /**
  * {@link JsonTokenConsumer} implementation that converts JSON tokens into
@@ -59,11 +60,11 @@ public void accept(final int tokenId, final JsonParser jsonParser) throws IOExce
             case JsonTokenId.ID_END_ARRAY:
                 eventHandler.arrayEnd();
                 break;
-            case JsonTokenId.ID_FIELD_NAME:
-                eventHandler.field(jsonParser.getText());
+            case JsonTokenId.ID_PROPERTY_NAME:
+                eventHandler.field(jsonParser.currentName());
                 break;
             case JsonTokenId.ID_STRING:
-                eventHandler.value(jsonParser.getText());
+                eventHandler.value(jsonParser.getString());
                 break;
             case JsonTokenId.ID_NUMBER_INT:
                 final JsonParser.NumberType numberType = jsonParser.getNumberType();
@@ -72,8 +73,8 @@ public void accept(final int tokenId, final JsonParser jsonParser) throws IOExce
                 } else if (numberType == JsonParser.NumberType.BIG_INTEGER) {
                     try {
                         eventHandler.value(jsonParser.getLongValue());
-                    } catch (final IOException ex) {
-                        throw new IOException("Integer value is out of range for 64-bit signed long: " + jsonParser.getText(), ex);
+                    } catch (final InputCoercionException ex) {
+                        throw new IOException("Integer value is out of range for 64-bit signed long: " + jsonParser.getString(), ex);
                     }
                 } else {
                     eventHandler.value(jsonParser.getIntValue());

httpcore5-jackson2/src/main/java/org/apache/hc/core5/jackson2/JsonTokenizer.java → httpcore5-jackson3/src/main/java/org/apache/hc/core5/jackson3/JsonTokenizer.java

@@ -24,15 +24,16 @@
  * <http://www.apache.org/>.
  *
  */
-package org.apache.hc.core5.jackson2;
+package org.apache.hc.core5.jackson3;
 
 import java.io.IOException;
 import java.io.InputStream;
 
-import com.fasterxml.jackson.core.JsonFactory;
-import com.fasterxml.jackson.core.JsonParser;
-import com.fasterxml.jackson.core.JsonToken;
-import com.fasterxml.jackson.core.JsonTokenId;
+import tools.jackson.core.TokenStreamFactory;
+import tools.jackson.core.JsonParser;
+import tools.jackson.core.JsonToken;
+import tools.jackson.core.JsonTokenId;
+import tools.jackson.core.ObjectReadContext;
 
 import org.apache.hc.core5.util.Args;
 
@@ -44,16 +45,16 @@
  */
 public final class JsonTokenizer {
 
-    private final JsonFactory jsonFactory;
+    private final TokenStreamFactory jsonFactory;
 
-    public JsonTokenizer(final JsonFactory jsonFactory) {
+    public JsonTokenizer(final TokenStreamFactory jsonFactory) {
         this.jsonFactory = jsonFactory;
     }
 
     public void tokenize(final InputStream inputStream,
                          final JsonTokenConsumer consumer) throws IOException {
         Args.notNull(consumer, "Consumer");
-        final JsonParser parser = jsonFactory.createParser(inputStream);
+        final JsonParser parser = jsonFactory.createParser(ObjectReadContext.empty(), inputStream);
         while (!parser.isClosed()) {
             final JsonToken jsonToken = parser.nextToken();
             if (jsonToken != null) {

httpcore5-jackson2/src/main/java/org/apache/hc/core5/jackson2/TokenBufferAssembler.java → httpcore5-jackson3/src/main/java/org/apache/hc/core5/jackson3/TokenBufferAssembler.java

@@ -25,13 +25,13 @@
  *
  */
 
-package org.apache.hc.core5.jackson2;
+package org.apache.hc.core5.jackson3;
 
 import java.io.IOException;
 
-import com.fasterxml.jackson.core.JsonParser;
-import com.fasterxml.jackson.core.JsonTokenId;
-import com.fasterxml.jackson.databind.util.TokenBuffer;
+import tools.jackson.core.JsonParser;
+import tools.jackson.core.JsonTokenId;
+import tools.jackson.databind.util.TokenBuffer;
 
 import org.apache.hc.core5.util.Args;
 
@@ -52,7 +52,7 @@ public final class TokenBufferAssembler implements JsonTokenConsumer {
     public TokenBufferAssembler(final JsonResultSink<TokenBuffer> sink) {
         Args.notNull(sink, "Result sink");
         this.sink = sink;
-        this.buffer = new TokenBuffer(null, false);
+        this.buffer = TokenBuffer.forGeneration();
     }
 
     public void accept(final int tokenId, final JsonParser jsonParser) throws IOException {
@@ -74,7 +74,7 @@ public void accept(final int tokenId, final JsonParser jsonParser) throws IOExce
                 if (depth == 0) {
                     buffer.close();
                     sink.accept(buffer);
-                    buffer = new TokenBuffer(null, false);
+                    buffer = TokenBuffer.forGeneration();
                 }
                 break;
             case JsonTokenId.ID_NO_TOKEN: