Migrate from Jackson 2.x to Jackson 3 (tools.jackson) (#430)

Move the codebase from com.fasterxml.jackson 2.x to tools.jackson 3.2.0.

- pom.xml: use tools.jackson.core:jackson-databind and
  tools.jackson.dataformat:jackson-dataformat-xml 3.2.0; remove the
  Jackson 2.x databind and dataformat-xml deps (woodstox-core retained);
  bump project version 2.6.4 -> 3.0.0.
- Package/class/method renames across main and test sources:
  com.fasterxml.jackson.* -> tools.jackson.*, TextNode -> StringNode,
  JsonFactory -> tools.jackson.core.json.JsonFactory,
  JsonProcessingException -> JacksonException,
  JsonMappingException -> DatabindException, immutable mapper builders.

Behavior-preserving fixes for Jackson 3 default/API changes (no test
assertion or expected value was changed):
- MatchFunction/ReplaceFunction: guard the pattern emptiness checks so a
  POJONode-wrapped RegularExpression never reaches the now-throwing
  asText(); logic is identical to Jackson 2.
- ArrayUtils.compare: pass "" default to asText() so container operands
  coerce to "" as they did under Jackson 2 instead of throwing.
- AgnosticTestSuite: normalize whole-number doubles with (long) d,
  replicating Jackson 2's silent narrowing (Jackson 3's asLong() throws
  on out-of-long-range values).
- Utils test mapper: disable FAIL_ON_TRAILING_TOKENS to restore the
  Jackson 2 default so existing test inputs parse identically.
- catch (IOException) -> catch (JacksonException) where Jackson 3 methods
  no longer throw checked IOException.
- README and launch scripts (tester.sh, testerui.sh, testerui.cmd):
  version 2.6.4 -> 3.0.0.

Verified: mvn clean test green (1223 tests, 0 failures, 93 skipped);
mvn package builds JSONata4Java-3.0.0.jar with an OSGi Import-Package
header referencing only tools.jackson.* [3.2,4); Tester CLI evaluation
and XML round-trip smoke-tested.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: wnm3

README.md

@@ -14,7 +14,7 @@ The easiest way to use this library is to include it as a dependency in your Mav
 <dependency>
   <groupId>com.ibm.jsonata4java</groupId>
   <artifactId>JSONata4Java</artifactId>
-  <version>2.6.4</version>
+  <version>3.0.0</version>
 </dependency>
 ```
 
@@ -51,8 +51,8 @@ Note: to build and deploy the jars to Maven Central you need to use a command li
 `mvn clean install deploy -Prelease`
 
 Once you have run the launcher, you can find the jar files in the /target directory. There are two&colon;
-* **JSONata4Java-2.6.4-jar-with-dependencies.jar** (thinks includes dependent jar files)
-* **JSONata4Java-2.6.4.jar** (only the JSONata4Java code)
+* **JSONata4Java-3.0.0-jar-with-dependencies.jar** (thinks includes dependent jar files)
+* **JSONata4Java-3.0.0.jar** (only the JSONata4Java code)
 
 The com.api.jsonata4java.Tester program enables you to enter an expression and run it 
 against the same JSON as is used at the https://try.jsonata.org site. You can also 

docs/plans/Jackson-3-Migration-Plan.md

@@ -92,15 +92,39 @@ find src/main/java src/test/java -name '*.java' -print0 | xargs -0 perl -pi -e '
 '
 ```
 
+- [ ] **Step 1b: Apply Jackson 3 API class/method renames (verified against the 3.2.0 jar)**
+
+Jackson 3 renamed several `JsonNode` types and methods, not just packages. These were confirmed by inspecting `jackson-databind-3.2.0.jar` / `jackson-core-3.2.0.jar`:
+
+- `TextNode` → `StringNode` (the class `tools.jackson.databind.node.TextNode` does not exist; `StringNode` replaces it). Affects imports, `new TextNode(...)`, `TextNode.valueOf(...)`, and `(TextNode)` casts. ~106 refs.
+- `tools.jackson.core.JsonProcessingException` → `tools.jackson.core.JacksonException` (JsonProcessingException is gone from core; `JacksonException` is the unchecked base). Affects imports and `catch` clauses. ~28 refs.
+- `.fieldNames()` (returned `Iterator<String>` in 2.x) → `.propertyNames()` (returns `Collection<String>` in 3.x). To preserve `Iterator`-based loops, replace `X.fieldNames()` with `X.propertyNames().iterator()`. ~21 calls.
+- `.elements()` (returned `Iterator<JsonNode>` in 2.x) → `.values()` (returns `Collection<JsonNode>` in 3.x). Replace `X.elements()` with `X.values().iterator()`. ~5 calls.
+- `.fields()` → `.properties()` if present. (This codebase has **0** `.fields()` calls — nothing to do, but do not introduce any.)
+- NOTE: `textValue()` and `asText()` **still exist** on `JsonNode` in 3.x — do NOT rewrite those.
+
+Apply the safe global renames with word-boundary care, then let the compiler catch the rest:
+
+```bash
+find src/main/java src/test/java -name '*.java' -print0 | xargs -0 perl -pi -e '
+  s/\bTextNode\b/StringNode/g;
+  s/\bJsonProcessingException\b/JacksonException/g;
+  s/\.fieldNames\(\)/.propertyNames().iterator()/g;
+  s/\.elements\(\)/.values().iterator()/g;
+'
+```
+
+Note: `TextNode` → `StringNode` also renames the import line `import tools.jackson.databind.node.TextNode;` to `import tools.jackson.databind.node.StringNode;`, which is correct. Watch for identifiers that merely contain "TextNode" as a substring — the `\b` boundaries prevent partial-word hits, but verify at compile time.
+
 - [ ] **Step 2: Confirm no `com.fasterxml.jackson` core/databind/xml references remain**
 
 Run: `grep -rn "com.fasterxml.jackson.core\|com.fasterxml.jackson.databind\|com.fasterxml.jackson.dataformat" src/ || echo CLEAN`
 Expected: `CLEAN` (annotations, if any ever appear, are intentionally left; none exist today).
 
-- [ ] **Step 3: Compile to surface the hotspots**
+- [ ] **Step 3: Compile to surface the remaining hotspots**
 
-Run: `mvn -q -DskipTests clean compile 2>&1 | tee /tmp/j3-compile.log | tail -40`
-Expected: FAILS — errors concentrated in `Tester.java` (`getFactory().configure`, `JsonWriteFeature.mappedFeature()`) and `TesterUI.java` (`xmlMapper.enable`/`.configure`, `ToXmlGenerator.Feature`). Note each reported file:line.
+Run: `mvn -q -DskipTests clean compile 2>&1 | tee /tmp/j3-compile.log | grep -E "ERROR|\.java:" | head -50`
+Expected: FAILS — after Step 1b the remaining errors are concentrated in `Tester.java` (`getFactory().configure`, `JsonWriteFeature.mappedFeature()`) and `TesterUI.java` (`xmlMapper.enable`/`.configure`, `ToXmlGenerator.Feature`), plus any stragglers from the method renames. Note each reported file:line and fix iteratively.
 
 - [ ] **Step 4: Fix `Tester.java` mapper construction**
 

pom.xml

@@ -27,7 +27,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.ibm.jsonata4java</groupId>
   <artifactId>JSONata4Java</artifactId>
-  <version>2.6.4</version>
+  <version>3.0.0</version>
   <name>JSONata4Java</name>
   <description>Port of jsonata.js to Java to enable rules for JSON content</description>
   <url>https://github.com/IBM/JSONata4Java</url>
@@ -121,22 +121,19 @@
         <version>3.2.0</version>
         <scope>compile</scope>
     </dependency>
+    <!-- Source: https://mvnrepository.com/artifact/tools.jackson.dataformat/jackson-dataformat-xml -->
     <dependency>
-      <groupId>com.fasterxml.jackson.core</groupId>
-      <artifactId>jackson-databind</artifactId>
-      <version>2.22.0</version>
+        <groupId>tools.jackson.dataformat</groupId>
+        <artifactId>jackson-dataformat-xml</artifactId>
+        <version>3.2.0</version>
+        <scope>compile</scope>
     </dependency>
     <!-- https://mvnrepository.com/artifact/com.fasterxml.woodstox/woodstox-core -->
     <dependency>
       <groupId>com.fasterxml.woodstox</groupId>
       <artifactId>woodstox-core</artifactId>
       <version>7.2.1</version>
     </dependency>
-    <dependency>
-      <groupId>com.fasterxml.jackson.dataformat</groupId>
-      <artifactId>jackson-dataformat-xml</artifactId>
-      <version>2.22.0</version>
-    </dependency>
     <!-- https://mvnrepository.com/artifact/org.apache.commons/commons-text -->
     <dependency>
       <groupId>org.apache.commons</groupId>

src/main/java/com/api/jsonata4java/Binding.java

@@ -22,8 +22,8 @@
 import com.api.jsonata4java.expressions.generated.MappingExpressionParser.NullContext;
 import com.api.jsonata4java.expressions.generated.MappingExpressionParser.NumberContext;
 import com.api.jsonata4java.expressions.generated.MappingExpressionParser.StringContext;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
 
 /**
  * Class mapping a variable name to a variable or function declaration

src/main/java/com/api/jsonata4java/Expression.java

@@ -20,9 +20,9 @@
 import com.api.jsonata4java.expressions.functions.DeclaredFunction;
 import com.api.jsonata4java.expressions.generated.MappingExpressionParser.ExprContext;
 import com.api.jsonata4java.expressions.regex.RegexEngine;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.databind.node.JsonNodeFactory;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.node.JsonNodeFactory;
 
 /**
  * Class to provide embedding and extending JSONata features
@@ -42,7 +42,7 @@ public class Expression implements Serializable {
 	public static List<Binding> createBindings(JsonNode bindingObj) throws ParseException {
 		ObjectMapper objectMapper = new ObjectMapper();
 		List<Binding> bindings = new ArrayList<Binding>();
-		for (Iterator<String> it = bindingObj.fieldNames(); it.hasNext();) {
+		for (Iterator<String> it = bindingObj.propertyNames().iterator(); it.hasNext();) {
 			String key = it.next();
 			JsonNode testObj = bindingObj.get(key);
 			String expression = "";

src/main/java/com/api/jsonata4java/JSONataUtils.java

@@ -53,10 +53,10 @@
 //import java.rmi.dgc.VMID;
 import java.util.UUID;
 import javax.management.modelmbean.InvalidTargetObjectTypeException;
-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.NullNode;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.node.JsonNodeFactory;
+import tools.jackson.databind.node.NullNode;
 
 public class JSONataUtils implements Serializable {
 

src/main/java/com/api/jsonata4java/Sequence.java

@@ -24,10 +24,10 @@
 
 import java.io.Serializable;
 import java.util.List;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.node.ArrayNode;
-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.JsonNodeFactory;
+import tools.jackson.databind.node.ObjectNode;
 
 public class Sequence implements Serializable {
 

src/main/java/com/api/jsonata4java/Signature.java

@@ -33,10 +33,10 @@
 import com.api.jsonata4java.expressions.functions.DeclaredFunction;
 import com.api.jsonata4java.expressions.generated.MappingExpressionParser.ExprContext;
 import com.api.jsonata4java.expressions.generated.MappingExpressionParser.ExprListContext;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.node.ArrayNode;
-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.JsonNodeFactory;
+import tools.jackson.databind.node.ObjectNode;
 
 /**
  * Manages signature related functions

src/main/java/com/api/jsonata4java/Test.java

@@ -6,9 +6,9 @@
 import com.api.jsonata4java.expressions.EvaluateRuntimeException;
 import com.api.jsonata4java.expressions.Expressions;
 import com.api.jsonata4java.expressions.ParseException;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
 
 public class Test implements Serializable {
 
@@ -22,7 +22,7 @@ public static void main(String[] args) {
         String expression = "$sum(c)";
         try {
             jsonObj = mapper.readTree(json);
-        } catch (IOException e1) {
+        } catch (JacksonException e1) {
             e1.printStackTrace();
         }
 
@@ -34,7 +34,7 @@ public static void main(String[] args) {
             System.err.println(e.getLocalizedMessage());
         } catch (EvaluateRuntimeException ere) {
             System.err.println(ere.getLocalizedMessage());
-        } catch (JsonProcessingException e) {
+        } catch (JacksonException e) {
             e.printStackTrace();
         } catch (IOException ioe) {
             System.err.println(ioe.getLocalizedMessage());
@@ -47,7 +47,7 @@ public static void main(String[] args) {
             } else {
                 System.out.println("" + mapper.writerWithDefaultPrettyPrinter().writeValueAsString(result));
             }
-        } catch (EvaluateException | JsonProcessingException e) {
+        } catch (EvaluateException | JacksonException e) {
             System.err.println(e.getLocalizedMessage());
         }
     }

src/main/java/com/api/jsonata4java/Tester.java

@@ -29,11 +29,11 @@
 import com.api.jsonata4java.expressions.EvaluateRuntimeException;
 import com.api.jsonata4java.expressions.Expressions;
 import com.api.jsonata4java.expressions.ParseException;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.core.json.JsonWriteFeature;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.databind.node.TextNode;
+import tools.jackson.core.JacksonException;
+import tools.jackson.core.json.JsonWriteFeature;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.json.JsonMapper;
+import tools.jackson.databind.node.StringNode;
 
 /**
  * Expression evaluation test utility
@@ -120,12 +120,13 @@ public class Tester implements Serializable {
      * @param args a fully qualified path and filename for test JSON could be provided
      */
     public static void main(String[] args) {
-        ObjectMapper mapper = new ObjectMapper();
-        mapper.getFactory().configure(JsonWriteFeature.ESCAPE_NON_ASCII.mappedFeature(), true);
+        JsonMapper mapper = JsonMapper.builder()
+            .enable(JsonWriteFeature.ESCAPE_NON_ASCII)
+            .build();
         JsonNode jsonObj = null;
         try {
             jsonObj = mapper.readTree(json);
-        } catch (IOException e1) {
+        } catch (JacksonException e1) {
             e1.printStackTrace();
         }
         if (args.length > 0) {
@@ -135,21 +136,19 @@ public static void main(String[] args) {
                     System.out.println("Attempting to load JSON from file: " + args[0]);
                     try {
                         jsonObj = mapper.readTree(file);
-                    } catch (JsonProcessingException e) {
-                        System.err.println(e.getLocalizedMessage());
-                    } catch (IOException e) {
+                    } catch (JacksonException e) {
                         System.err.println(e.getLocalizedMessage());
                     }
                 } else {
-                    jsonObj = new TextNode(args[0]);
+                    jsonObj = new StringNode(args[0]);
                 }
             } else {
                 jsonObj = null;
             }
         }
         try {
             System.out.println("Using json:\n" + mapper.writerWithDefaultPrettyPrinter().writeValueAsString(jsonObj));
-        } catch (JsonProcessingException e1) {
+        } catch (JacksonException e1) {
             e1.printStackTrace();
         }
         while (true) {
@@ -187,7 +186,7 @@ public static void main(String[] args) {
                 } else {
                     System.out.println("" + mapper.writerWithDefaultPrettyPrinter().writeValueAsString(result));
                 }
-            } catch (EvaluateException | JsonProcessingException e) {
+            } catch (EvaluateException | JacksonException e) {
                 System.err.println(e.getLocalizedMessage());
             }
         }