MiniTikaMiniExtractor v2 使用说明

一个精简版（面向嵌入式调用而不是命令行）的 Tika 抽取工具，仅保留常用输出能力，并新增 XMP_TEXT（正文 + XMP）模式。
特点：

不依赖复杂 CLI 逻辑、批处理、递归嵌入等高级功能
统一入口：extractToString(Path, Mode) 或 extract(Path, Mode, OutputStream, ...)
模式之间严格区分：正文 / 主体正文 / 全量文本 / 元数据 / JSON / XMP / 正文+XMP / 语言 / MIME 检测
XMP 生成失败时可自动降级（输出 _xmpFallback 标记的 JSON）

1. 支持的模式 (Mode 枚举)

模式	说明	输出内容示例
TEXT	正文纯文本（BodyContentHandler）	段落文本
TEXT_MAIN	主体正文（BoilerpipeContentHandler，需 boilerpipe 依赖；缺失时回退 TEXT）	网页主体/正文
TEXT_ALL	尽可能多的文本（WriteOutContentHandler）	全部可见字符
METADATA	仅元数据（`key: value` 多行）	`Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document`
JSON	元数据 JSON（多值字段为数组）	`{ "Content-Type":"application/pdf", ... }`
XMP	XMP XML（失败回退 `{ "_xmpFallback": true }`）	`<x:xmpmeta ...>`
XMP_TEXT	正文 + 分隔线 + XMP（失败回退为正文 + Fallback JSON）	`正文...\n-----XMP-BEGIN-----\n<x:xmpmeta ...>`
LANGUAGE	语言代码（依赖 `tika-langdetect-optimaize`）	`en`
DETECT	只输出 MIME 类型	`application/pdf`

分隔线固定：-----XMP-BEGIN-----（可按需在代码中改）

2. Maven 依赖建议

使用 统一版本（示例 3.2.2），避免混用不同 Tika 版本或 POI 版本导致 NoClassDefFoundError。

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.apache.tika</groupId>
      <artifactId>tika-bom</artifactId>
      <version>3.2.2</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <!-- 解析主体（含 core/parsers） -->
  <dependency>
    <groupId>org.apache.tika</groupId>
    <artifactId>tika-parsers-standard-package</artifactId>
  </dependency>

  <!-- TEXT_MAIN 模式需要 -->
  <dependency>
    <groupId>org.apache.tika</groupId>
    <artifactId>tika-handler-boilerpipe</artifactId>
  </dependency>

  <!-- LANGUAGE 模式需要 -->
  <dependency>
    <groupId>org.apache.tika</groupId>
    <artifactId>tika-langdetect-optimaize</artifactId>
  </dependency>

  <!-- XMP / XMP_TEXT 模式需要 -->
  <dependency>
    <groupId>org.apache.tika</groupId>
    <artifactId>tika-xmp</artifactId>
  </dependency>
</dependencies>

如项目中已有其它模块引入不同版本的 tika-core，请使用 <exclusions> 排除并用 BOM 统一。

3. 快速使用

import java.nio.file.Path;

public class Demo {
    public static void main(String[] args) throws Exception {
        Path file = Path.of("example.docx");

        // 1. 普通正文
        String text = MiniTikaMiniExtractor.extractToString(file, MiniTikaMiniExtractor.Mode.TEXT);
        System.out.println(text);

        // 2. 主体正文（若无 boilerpipe 依赖将回退 TEXT）
        String main = MiniTikaMiniExtractor.extractToString(file, MiniTikaMiniExtractor.Mode.TEXT_MAIN);

        // 3. JSON 元数据
        String json = MiniTikaMiniExtractor.extractToString(file, MiniTikaMiniExtractor.Mode.JSON);

        // 4. XMP
        String xmp = MiniTikaMiniExtractor.extractToString(file, MiniTikaMiniExtractor.Mode.XMP);

        // 5. 正文 + XMP
        String combo = MiniTikaMiniExtractor.extractToString(file, MiniTikaMiniExtractor.Mode.XMP_TEXT);

        // 6. MIME 检测
        String mime = MiniTikaMiniExtractor.extractToString(file, MiniTikaMiniExtractor.Mode.DETECT);
    }
}

输出示例（XMP_TEXT）：

这是文档正文第一段
这是第二段

-----XMP-BEGIN-----
<x:xmpmeta xmlns:x="adobe:ns:meta/">
  ...
</x:xmpmeta>

4. XMP_TEXT 模式说明

流程：

首次解析使用 BodyContentHandler 抽取纯文本；
输出文本原文；
输出分隔符 -----XMP-BEGIN-----；
尝试构建 XMPMetadata 并输出；
若构建失败（缺依赖/版本冲突），输出 Fallback JSON（带 _xmpFallback:true 标记）。

5. 常见问题

问题	可能原因	解决
XMP / XMP_TEXT 报 `NoClassDefFoundError: OOXMLParser`	Tika/POI 多版本冲突	统一版本，使用 BOM；移除旧 POI
TEXT_MAIN 回退为普通文本	缺少 `tika-handler-boilerpipe`	添加依赖
LANGUAGE 输出空	文本太短或缺语言模型	确认 langdetect 依赖；测试长文本
JSON 中少字段	解析器未产出该元数据	检查文档内容本身或换另一模式 (METADATA) 验证
PDF 内嵌图片文字未识别	未开启 OCR（该精简器未集成 OCR 选项）	如需 OCR 可在代码中添加 `TesseractOCRConfig` 支持

6. 扩展建议（可按需自行添加）

需求	建议方案
加 OCR	在构造函数中 set `TesseractOCRConfig` 到 `ParseContext`
递归嵌入 JSON	使用 `RecursiveParserWrapper` 替换当前一次性解析
分页 (PDF 每页)	使用 `PDFParserConfig#setExtractAcroFormContent` + 自定义 Handler 或直接分割文本
PPT 每页分离	解析后按 `Slide` 标记拆分，或使用 POI 回退逻辑
限制最大文本长度	改用 `BodyContentHandler(int writeLimit)`

7. 代码结构概要

枚举 Mode：声明所有输出模式
内部抽象类 OutputType：与 TikaCLI 类似，定义 process + getContentHandler 模板
多个匿名或私有内部类实现元数据 / JSON / XMP Handler
XMP_TEXT 模式自定义双阶段：正文采集 + XMP 输出
工具方法：
extractToString(Path, Mode)
extract(Path, Mode, OutputStream, ..., password, enablePDFInlineImages)

8. 返回格式对比速览

Mode	典型首行示例
TEXT	`这是正文第一段`
TEXT_MAIN	`（可能更短的核心正文）`
TEXT_ALL	`（含更多隐藏文本/脚注等）`
METADATA	`Content-Type: application/pdf`
JSON	`{ "Content-Type":"application/pdf", ... }`
XMP	`<x:xmpmeta ...>`
XMP_TEXT	`正文...\n-----XMP-BEGIN-----\n<x:xmpmeta ...>`
LANGUAGE	`en`
DETECT	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`

9. 许可证与免责声明

本文件示例代码基于 Apache Tika（Apache License 2.0）。你可自由修改和整合。请注意：

在生产环境处理来路不明文件时，需做好资源限制（内存/CPU/超时）。
对特大文件建议增加写入限制或流式处理，避免内存溢出。

10. 变更记录（简写）

版本	说明
v1	初始：TEXT / TEXT_MAIN / TEXT_ALL / METADATA / JSON / XMP / LANGUAGE / DETECT
v2	新增 XMP_TEXT；XMP 支持 Fallback；文本与 XMP 组合输出

如需后续增强（OCR / 递归 JSON / 每页切分 / 结构化返回），可再补充需求。