TIKA-4840: host-provided Jackson for pipes plugins; one strict PluginJson mapper for plugin configs

Author: tballison

CHANGES.txt

@@ -1,5 +1,15 @@
 Release 4.1.0 - unreleased
 
+   * Pipes plugins no longer bundle their own Jackson: jackson-core, -databind
+     and -annotations are provided by the host (tika-serialization) and the
+     plugins parent pom now bans bundling them, so a mapper can cross the
+     plugin boundary without a second copy of the Jackson classes (seven plugin
+     zips shipped one). Plugin configuration JSON is parsed by one shared
+     mapper, PluginJson (tika-plugins-core), which rejects unknown keys,
+     numbers for enums and duplicate keys, and accepts
+     // and /* */ comments; the 33 per-plugin *Config classes use it instead of
+     their own bare ObjectMapper (TIKA-4840).
+
    * The Kafka pipes iterator no longer stops at the first empty poll. A newly
      subscribed consumer spends its first poll(s) joining the group and returns
      empty even when the topic has a backlog, so the iterator could enqueue zero

docs/modules/ROOT/pages/pipes/plugins/writing-a-plugin.adoc

@@ -124,8 +124,12 @@ public class MyFetcher extends AbstractTikaExtension implements Fetcher {
     }
 }
 ----
-<1> Config arrives as a **JSON string**, and the plugin parses it with its own Jackson. Nothing
-richer crosses the boundary — see <<classloading>>.
+<1> Config arrives as a **JSON string**; nothing richer crosses the boundary — see
+<<classloading>>. The in-tree plugins parse it with `org.apache.tika.plugins.PluginJson`
+(`PluginJson.read(json, MyFetcherConfig.class)`), the host's strict mapper: comments allowed,
+unknown keys, duplicate keys and numbers-for-enums rejected. Using it is optional — the
+boundary is the `Fetcher`, not how it is configured — but see the Jackson rule under
+<<classloading>> before deciding.
 
 IMPORTANT: `Fetcher` implementations must be thread-safe. One instance serves every concurrent
 request against that fetcher id.
@@ -275,6 +279,20 @@ of a plugin that loads cleanly and then behaves as if it were not there — or o
 The same reasoning covers logging: leave `org.slf4j` and `org.apache.logging.log4j` to the host so
 plugin logs land in the host's configuration.
 
+Jackson is the one library with a choice, and it is either/or:
+
+* **Host Jackson (the default, what the in-tree plugins do):** `jackson-core`, `jackson-databind`
+  and `jackson-annotations` `provided`, absent from `lib/`. Every Tika host carries them (via
+  `tika-serialization`), and you may then use `PluginJson` and other host Jackson types.
+* **Your own Jackson:** only if a library you depend on needs a version the host does not ship.
+  Bundle it (`compile` scope), and then never touch a host Jackson object — not `PluginJson`, not
+  `JsonMetadataList`, nothing returning an `ObjectMapper` or `JsonNode`. Your `ObjectMapper` and
+  the host's are different `Class` objects, and the first assignment between them fails with a
+  `LinkageError` or `ClassCastException`. Parse `ExtensionConfig.json()` with your own mapper.
+
+Never both. The in-tree plugins' parent pom enforces the first choice; a third-party plugin
+choosing the second must not inherit that rule.
+
 Everything else — your own transitive libraries — belongs in `lib/`.
 
 == Installing and configuring
@@ -367,6 +385,8 @@ java -Dtika.plugin.dev.mode=true ...
 * `tika-core`, `tika-pipes-api`, `tika-plugins-core`, `tika-serialization`,
   `tika-pipes-core`, `tika-pipes-iterator-commons`, `pf4j` and the logging
   implementations `provided`, and absent from `lib/`.
+* Jackson either `provided` (and then `PluginJson` is yours to use) or bundled (and then no host
+  Jackson type is) — never a mix.
 * The zip — not an unpacked directory — dropped in a `plugin-roots` directory.
 * `getName()` unique against every other loaded plugin.
 

tika-pipes/tika-pipes-plugins/pom.xml

@@ -88,6 +88,23 @@
       <version>${project.version}</version>
       <scope>provided</scope>
     </dependency>
+    <!-- host-supplied via tika-serialization: a plugin that bundles its own Jackson gets a
+         second ObjectMapper class, and any mapper crossing the plugin boundary fails to link -->
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-core</artifactId>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-annotations</artifactId>
+      <scope>provided</scope>
+    </dependency>
     <!-- logging is host-supplied -->
     <dependency>
       <groupId>org.slf4j</groupId>
@@ -169,6 +186,7 @@
                   <excludes>
                     <exclude>org.slf4j</exclude>
                     <exclude>org.apache.logging.log4j</exclude>
+                    <exclude>com.fasterxml.jackson.core</exclude>
                   </excludes>
                   <!-- the artifacts this module declares provided; anything else in these
                        groups needs a provided declaration here before it may be depended on -->
@@ -178,8 +196,11 @@
                     <include>org.apache.logging.log4j:log4j-api</include>
                     <include>org.apache.logging.log4j:log4j-core</include>
                     <include>org.apache.logging.log4j:log4j-slf4j2-impl</include>
+                    <include>com.fasterxml.jackson.core:jackson-core</include>
+                    <include>com.fasterxml.jackson.core:jackson-databind</include>
+                    <include>com.fasterxml.jackson.core:jackson-annotations</include>
                   </includes>
-                  <message>logging is host-supplied: add a provided-scope declaration in tika-pipes-plugins/pom.xml (and to this rule's include list) rather than bundling this artifact in the plugin zip</message>
+                  <message>logging and Jackson are host-supplied: add a provided-scope declaration in tika-pipes-plugins/pom.xml (and to this rule's include list) rather than bundling this artifact in the plugin zip. A plugin whose SDK genuinely needs its own Jackson may bundle it (compile scope, skip this execution in its pom) but must then use no host Jackson type -- not PluginJson -- since the two ObjectMapper classes cannot be assigned to each other.</message>
                 </bannedDependencies>
               </rules>
               <fail>true</fail>

tika-pipes/tika-pipes-plugins/tika-pipes-atlassian-jwt/pom.xml

@@ -53,14 +53,6 @@
       <groupId>com.google.guava</groupId>
       <artifactId>guava</artifactId>
     </dependency>
-    <dependency>
-      <groupId>com.fasterxml.jackson.core</groupId>
-      <artifactId>jackson-databind</artifactId>
-    </dependency>
-    <dependency>
-      <groupId>com.fasterxml.jackson.core</groupId>
-      <artifactId>jackson-annotations</artifactId>
-    </dependency>
     <dependency>
       <groupId>org.mockito</groupId>
       <artifactId>mockito-core</artifactId>

tika-pipes/tika-pipes-plugins/tika-pipes-atlassian-jwt/src/main/java/org/apache/tika/pipes/fetcher/atlassianjwt/config/AtlassianJwtFetcherConfig.java

@@ -25,10 +25,11 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 
 import org.apache.tika.exception.TikaConfigException;
+import org.apache.tika.plugins.PluginJson;
 
 public class AtlassianJwtFetcherConfig {
 
-    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+    private static final ObjectMapper OBJECT_MAPPER = PluginJson.mapper();
 
     public static AtlassianJwtFetcherConfig load(final String json)
             throws TikaConfigException {

tika-pipes/tika-pipes-plugins/tika-pipes-az-blob/pom.xml

@@ -46,10 +46,6 @@
       <groupId>com.azure</groupId>
       <artifactId>azure-storage-blob</artifactId>
     </dependency>
-    <dependency>
-      <groupId>com.fasterxml.jackson.core</groupId>
-      <artifactId>jackson-databind</artifactId>
-    </dependency>
   </dependencies>
 
   <build>

tika-pipes/tika-pipes-plugins/tika-pipes-az-blob/src/main/java/org/apache/tika/pipes/emitter/azblob/AZBlobEmitterConfig.java

@@ -21,6 +21,7 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 
 import org.apache.tika.exception.TikaConfigException;
+import org.apache.tika.plugins.PluginJson;
 
 public record AZBlobEmitterConfig(
         String sasToken,
@@ -31,7 +32,7 @@ public record AZBlobEmitterConfig(
         @JsonProperty(defaultValue = "false") boolean overwriteExisting
 ) {
 
-    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+    private static final ObjectMapper OBJECT_MAPPER = PluginJson.mapper();
 
     public static AZBlobEmitterConfig load(final String json)
             throws TikaConfigException {

tika-pipes/tika-pipes-plugins/tika-pipes-az-blob/src/main/java/org/apache/tika/pipes/fetcher/azblob/config/AZBlobFetcherConfig.java

@@ -20,10 +20,11 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 
 import org.apache.tika.exception.TikaConfigException;
+import org.apache.tika.plugins.PluginJson;
 
 public class AZBlobFetcherConfig {
 
-    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+    private static final ObjectMapper OBJECT_MAPPER = PluginJson.mapper();
 
     public static AZBlobFetcherConfig load(final String json)
             throws TikaConfigException {

tika-pipes/tika-pipes-plugins/tika-pipes-az-blob/src/main/java/org/apache/tika/pipes/iterator/azblob/AZBlobPipesIteratorConfig.java

@@ -23,10 +23,11 @@
 
 import org.apache.tika.exception.TikaConfigException;
 import org.apache.tika.pipes.pipesiterator.PipesIteratorConfig;
+import org.apache.tika.plugins.PluginJson;
 
 public class AZBlobPipesIteratorConfig extends PipesIteratorConfig {
 
-    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+    private static final ObjectMapper OBJECT_MAPPER = PluginJson.mapper();
 
     public static AZBlobPipesIteratorConfig load(final String json)
             throws TikaConfigException {

tika-pipes/tika-pipes-plugins/tika-pipes-csv/src/main/java/org/apache/tika/pipes/iterator/csv/CSVPipesIteratorConfig.java

@@ -24,10 +24,11 @@
 
 import org.apache.tika.exception.TikaConfigException;
 import org.apache.tika.pipes.pipesiterator.PipesIteratorConfig;
+import org.apache.tika.plugins.PluginJson;
 
 public class CSVPipesIteratorConfig extends PipesIteratorConfig {
 
-    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+    private static final ObjectMapper OBJECT_MAPPER = PluginJson.mapper();
 
     public static CSVPipesIteratorConfig load(final String json)
             throws TikaConfigException {