TIKA-4562 -- refactor runtime configs in tika-server to json

Author: tballison

tika-annotation-processor/src/main/java/org/apache/tika/annotation/TikaComponentProcessor.java

@@ -34,7 +34,10 @@
 import javax.annotation.processing.SupportedAnnotationTypes;
 import javax.annotation.processing.SupportedSourceVersion;
 import javax.lang.model.SourceVersion;
+import javax.lang.model.element.AnnotationMirror;
+import javax.lang.model.element.AnnotationValue;
 import javax.lang.model.element.Element;
+import javax.lang.model.element.ExecutableElement;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.type.DeclaredType;
 import javax.lang.model.type.TypeMirror;
@@ -125,17 +128,31 @@ private void processComponent(TypeElement element) {
         // Check if component should be included in SPI
         boolean includeSpi = annotation.spi();
 
+        // Get contextKey if specified (need to use mirror API for Class types)
+        String contextKey = getContextKeyFromAnnotation(element);
+
         messager.printMessage(Diagnostic.Kind.NOTE,
                 "Processing @TikaComponent: " + className + " -> " + componentName +
-                " (SPI: " + includeSpi + ")");
+                " (SPI: " + includeSpi + ", contextKey: " + contextKey + ")");
 
         // Find all implemented service interfaces
         List<String> serviceInterfaces = findServiceInterfaces(element);
 
+        // Build the index entry value (className or className:key=X)
+        String indexValue = className;
+        if (contextKey != null) {
+            indexValue = className + ":key=" + contextKey;
+        }
+
         if (serviceInterfaces.isEmpty()) {
-            messager.printMessage(Diagnostic.Kind.WARNING,
-                    "Class " + className + " annotated with @TikaComponent " +
-                    "but does not implement any known Tika service interface", element);
+            // No known service interface - put in other-configs.idx
+            messager.printMessage(Diagnostic.Kind.NOTE,
+                    "Class " + className + " does not implement known service interface, " +
+                    "adding to other-configs.idx", element);
+
+            Map<String, String> index = indexFiles.computeIfAbsent("other-configs",
+                    k -> new LinkedHashMap<>());
+            addToIndex(index, componentName, indexValue, className, element);
             return;
         }
 
@@ -152,20 +169,57 @@ private void processComponent(TypeElement element) {
             if (indexFileName != null) {
                 Map<String, String> index = indexFiles.computeIfAbsent(indexFileName,
                         k -> new LinkedHashMap<>());
+                addToIndex(index, componentName, indexValue, className, element);
+            }
+        }
+    }
 
-                // Check for duplicate names
-                if (index.containsKey(componentName)) {
-                    String existingClass = index.get(componentName);
-                    if (!existingClass.equals(className)) {
-                        messager.printMessage(Diagnostic.Kind.ERROR,
-                                "Duplicate component name '" + componentName + "' for classes: " +
-                                existingClass + " and " + className, element);
+    /**
+     * Adds an entry to an index, checking for duplicates.
+     */
+    private void addToIndex(Map<String, String> index, String componentName,
+                           String indexValue, String className, TypeElement element) {
+        if (index.containsKey(componentName)) {
+            String existingValue = index.get(componentName);
+            // Extract class name from value (may have :key= suffix)
+            String existingClass = existingValue.contains(":")
+                    ? existingValue.substring(0, existingValue.indexOf(":"))
+                    : existingValue;
+            if (!existingClass.equals(className)) {
+                messager.printMessage(Diagnostic.Kind.ERROR,
+                        "Duplicate component name '" + componentName + "' for classes: " +
+                        existingClass + " and " + className, element);
+            }
+        } else {
+            index.put(componentName, indexValue);
+        }
+    }
+
+    /**
+     * Gets the contextKey value from the annotation using the mirror API.
+     * Returns null if contextKey is void.class (the default).
+     */
+    private String getContextKeyFromAnnotation(TypeElement element) {
+        for (AnnotationMirror mirror : element.getAnnotationMirrors()) {
+            DeclaredType annotationType = mirror.getAnnotationType();
+            if (annotationType.toString().equals(TikaComponent.class.getName())) {
+                for (Map.Entry<? extends ExecutableElement, ? extends AnnotationValue> entry
+                        : mirror.getElementValues().entrySet()) {
+                    if (entry.getKey().getSimpleName().toString().equals("contextKey")) {
+                        // The value is a TypeMirror for Class types
+                        Object value = entry.getValue().getValue();
+                        if (value instanceof TypeMirror) {
+                            String typeName = value.toString();
+                            // void.class is the default, meaning "auto-detect"
+                            if (!"void".equals(typeName) && !"java.lang.Void".equals(typeName)) {
+                                return typeName;
+                            }
+                        }
                     }
-                } else {
-                    index.put(componentName, className);
                 }
             }
         }
+        return null;
     }
 
     /**
@@ -267,7 +321,7 @@ private void writeIndexFiles() {
                     writeApacheLicenseHeader(writer);
                     writer.write("# Generated by TikaComponentProcessor\n");
                     writer.write("# Do not edit manually\n");
-                    writer.write("# Format: component-name=fully.qualified.ClassName\n");
+                    writer.write("# Format: component-name=fully.qualified.ClassName[:key=contextKeyClass]\n");
                     for (Map.Entry<String, String> component : components.entrySet()) {
                         writer.write(component.getKey());
                         writer.write("=");

tika-annotation-processor/src/main/java/org/apache/tika/config/TikaComponent.java

@@ -53,6 +53,11 @@
  * public class DWGReadParser extends AbstractParser {
  *     // available by name, but NOT auto-loaded by default-parser
  * }
+ *
+ * {@code @TikaComponent(contextKey = MetadataFilter.class)}
+ * public class MyFilter implements MetadataFilter, AnotherInterface {
+ *     // explicit ParseContext key when class implements multiple known interfaces
+ * }
  * </pre>
  *
  * @since 3.1.0
@@ -81,4 +86,24 @@
      * @return true to include in SPI (default), false to require explicit config
      */
     boolean spi() default true;
+
+    /**
+     * The class to use as the key when adding this component to ParseContext.
+     * <p>
+     * By default ({@code void.class}), the key is auto-detected:
+     * <ul>
+     *   <li>If the component implements a known interface (e.g., MetadataFilter),
+     *       that interface is used as the key</li>
+     *   <li>Otherwise, the component's own class is used as the key</li>
+     * </ul>
+     * <p>
+     * Use this attribute to explicitly specify the key when:
+     * <ul>
+     *   <li>The component implements multiple known interfaces (ambiguous)</li>
+     *   <li>You need a specific interface/class that isn't auto-detected</li>
+     * </ul>
+     *
+     * @return the class to use as ParseContext key, or void.class for auto-detection
+     */
+    Class<?> contextKey() default void.class;
 }

tika-app/src/main/java/org/apache/tika/cli/XmlToJsonConfigConverter.java

@@ -40,6 +40,7 @@
 import org.w3c.dom.Node;
 import org.w3c.dom.NodeList;
 
+import org.apache.tika.config.loader.ComponentInfo;
 import org.apache.tika.config.loader.ComponentRegistry;
 import org.apache.tika.config.loader.KebabCaseConverter;
 import org.apache.tika.exception.TikaConfigException;
@@ -585,8 +586,8 @@ private static String classNameToComponentName(String fullClassName, ComponentRe
             Class<?> clazz = Thread.currentThread().getContextClassLoader().loadClass(fullClassName);
 
             // Reverse lookup: find the component name for this class
-            for (Map.Entry<String, Class<?>> entry : registry.getAllComponents().entrySet()) {
-                if (entry.getValue().equals(clazz)) {
+            for (Map.Entry<String, ComponentInfo> entry : registry.getAllComponents().entrySet()) {
+                if (entry.getValue().componentClass().equals(clazz)) {
                     return entry.getKey();
                 }
             }

tika-core/src/main/java/org/apache/tika/config/ConfigContainer.java

@@ -16,6 +16,7 @@
  */
 package org.apache.tika.config;
 
+import java.io.Serializable;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
@@ -32,7 +33,9 @@
  * and other components to look up their config by friendly name (e.g., "pdf-parser",
  * "fs-fetcher-1") and deserialize it on-demand.
  */
-public class ConfigContainer {
+public class ConfigContainer implements Serializable {
+
+    private static final long serialVersionUID = 1L;
 
     private final Map<String, String> configs = new HashMap<>();
 
@@ -83,4 +86,14 @@ public Set<String> getKeys() {
     public boolean isEmpty() {
         return configs.isEmpty();
     }
+
+    /**
+     * Removes the configuration with the specified key.
+     *
+     * @param key the friendly name of the config to remove
+     * @return the previous value associated with the key, or null if there was no mapping
+     */
+    public String remove(String key) {
+        return configs.remove(key);
+    }
 }

tika-core/src/main/java/org/apache/tika/config/ParseContextConfig.java

@@ -67,12 +67,19 @@ public class ParseContextConfig {
     }
 
     /**
-     * Retrieves runtime configuration from ParseContext's ConfigContainer.
+     * Retrieves runtime configuration from ParseContext.
+     * <p>
+     * This method first checks if the config is already resolved in ParseContext
+     * (via {@code context.get(configClass)}). If found, it returns immediately without
+     * re-deserializing. This is efficient for embedded documents where the config
+     * was already deserialized for the parent document.
+     * <p>
+     * If not found, it checks ConfigContainer for the config key and deserializes
+     * the JSON. The deserialized config is also set in ParseContext for future lookups.
      * <p>
      * This method performs defensive checking: if the ConfigContainer has configuration
      * for the requested key but the ConfigDeserializer is not available on the classpath,
-     * it throws IllegalStateException. This prevents silent failures where users expect
-     * their runtime config to be used but it's silently ignored.
+     * it throws TikaConfigException to prevent silent failures.
      *
      * @param context the parse context (may be null)
      * @param configKey the configuration key (e.g., "pdf-parser", "html-parser")
@@ -90,6 +97,13 @@ public static <T> T getConfig(ParseContext context, String configKey,
             return defaultConfig;
         }
 
+        // First check if config is already resolved in ParseContext
+        // (may have been set by a previous call or by user code)
+        T existingConfig = context.get(configClass);
+        if (existingConfig != null) {
+            return existingConfig;
+        }
+
         ConfigContainer configContainer = context.get(ConfigContainer.class);
         if (configContainer == null) {
             return defaultConfig;
@@ -113,6 +127,7 @@ public static <T> T getConfig(ParseContext context, String configKey,
         }
 
         // ConfigDeserializer is available - delegate to it
+        // (ConfigDeserializer.getConfig also sets the config in ParseContext for future lookups)
         try {
             @SuppressWarnings("unchecked")
             T result = (T) GET_CONFIG_METHOD.invoke(null, context, configKey, configClass, defaultConfig);
@@ -122,7 +137,7 @@ public static <T> T getConfig(ParseContext context, String configKey,
             if (cause instanceof IOException) {
                 throw (IOException) cause;
             }
-            throw new IOException("Failed to deserialize config for '" + configKey + "': " + 
+            throw new IOException("Failed to deserialize config for '" + configKey + "': " +
                 cause.getMessage(), cause);
         }
     }

tika-core/src/main/java/org/apache/tika/config/SelfConfiguring.java

@@ -0,0 +1,56 @@
+/*
+ * 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.
+ */
+package org.apache.tika.config;
+
+/**
+ * Marker interface indicating that a component reads its own configuration
+ * from {@link ConfigContainer} at runtime.
+ * <p>
+ * Components implementing this interface will NOT be automatically resolved
+ * by ParseContextUtils. Instead, the JSON configuration will remain in
+ * ConfigContainer, and the component is responsible for reading and applying
+ * its own configuration during execution.
+ * <p>
+ * This is typically used by parsers and other components that need fine-grained
+ * control over how their configuration is loaded and merged with defaults.
+ * <p>
+ * Example:
+ * <pre>
+ * {@literal @}TikaComponent
+ * public class PDFParser implements Parser, SelfConfiguring {
+ *
+ *     private final PDFParserConfig defaultConfig;
+ *
+ *     public void parse(..., ParseContext context) {
+ *         // Component reads its own config from ConfigContainer
+ *         PDFParserConfig config = ParseContextConfig.getConfig(
+ *             context, "pdf-parser", PDFParserConfig.class, defaultConfig);
+ *         // use config...
+ *     }
+ * }
+ * </pre>
+ * <p>
+ * Components that do NOT implement this interface will have their configuration
+ * automatically deserialized and added to ParseContext by ParseContextUtils.
+ *
+ * @since Apache Tika 4.0
+ * @see ConfigContainer
+ * @see ParseContextConfig
+ */
+public interface SelfConfiguring {
+    // Marker interface - no methods
+}

tika-core/src/main/java/org/apache/tika/config/TikaTaskTimeout.java

@@ -20,10 +20,34 @@
 
 import org.apache.tika.parser.ParseContext;
 
+/**
+ * Configuration class for specifying parse task timeout.
+ * <pre>
+ * {
+ *   "parse-context": {
+ *     "tika-task-timeout": {
+ *       "timeoutMillis": 30000
+ *     }
+ *   }
+ * }
+ * </pre>
+ */
+@TikaComponent(spi = false)
 public class TikaTaskTimeout implements Serializable {
 
-    private final long timeoutMillis;
+    private long timeoutMillis;
+
+    /**
+     * No-arg constructor for Jackson deserialization.
+     */
+    public TikaTaskTimeout() {
+    }
 
+    /**
+     * Constructor with timeout value.
+     *
+     * @param timeoutMillis timeout in milliseconds
+     */
     public TikaTaskTimeout(long timeoutMillis) {
         this.timeoutMillis = timeoutMillis;
     }
@@ -32,6 +56,10 @@ public long getTimeoutMillis() {
         return timeoutMillis;
     }
 
+    public void setTimeoutMillis(long timeoutMillis) {
+        this.timeoutMillis = timeoutMillis;
+    }
+
     public static long getTimeoutMillis(ParseContext context, long defaultTimeoutMillis) {
         if (context == null) {
             return defaultTimeoutMillis;