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 模式说明

流程：

1. 首次解析使用 BodyContentHandler 抽取纯文本；
2. 输出文本原文；
3. 输出分隔符 -----XMP-BEGIN-----；
4. 尝试构建 XMPMetadata 并输出；
5. 若构建失败（缺依赖/版本冲突），输出 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 / 每页切分 / 结构化返回），可再补充需求。