Apache XML Graphics Commons 2.11 介绍与选型指南

一、信息基准

本章列明本文事实性信息的核查时间与来源，全部信息取自 Apache XML Graphics 官方渠道与公开发行目录，不含本地实测推算。

1.1 版本基准

1.2 官方来源清单

二、软件概述

本文介绍的是 Apache XML Graphics Commons 2.11。官方定义：XML Graphics Commons 是一个由多个可复用组件构成的库，供 Apache Batik 与 Apache FOP 共同使用；其中许多组件可以在 SVG 与 XSL-FO 领域之外独立使用，例如 PDF 库、RTF 库，以及能直接生成 PDF 与 PostScript 文件的 Graphics2D 实现等。

该项目是 Batik（SVG 工具集）与 FOP（XSL-FO 转 PDF 排版引擎）的共享底层：从 Batik 与 FOP 移植而来的公共能力沉淀于此，包括图像编解码、位图输出抽象、Java2D 辅助类与图像加载框架（官网特性表）。首个正式版 1.0 发布于 2006 年 4 月 17 日（官方 Changes 页），当前线为 2.x，最新 2.11 于 2025 年 5 月 6 日发布。

三、核心架构

3.1 组件构成

官网特性表列出的主要组件与来源：

3.2 图像加载框架

官方图像加载框架文档给出的处理链：ImageContext 提供全局上下文，ImageManager 为统一入口，ImageSessionContext 描述单次会话上下文；通过 getImageInfo(uri, sessionContext) 先取图像元信息（尺寸、格式等），再按目标 ImageFlavor（如 RENDERED_IMAGE）请求实际图像对象，框架内部完成格式探测与必要转换，位图与矢量图（如 EPS）统一处理。

3.3 输出端抽象

• Graphics2D 实现：PSGenerator 一侧面向 PostScript 输出（官网 PostScript 工具文档），另有面向 PDF 的 Graphics2D 实现，使既有 Java2D 绘制代码可直接产出 PDF/PostScript 文件。
• XMP 元数据框架：自 1.1 起提供 XMP 元数据处理能力（官方 Changes 页历史记录）。

四、功能特性

4.1 图像读写

• PNG/TIFF 编解码器（Batik 移植）与位图 ImageWriter 抽象：同一套 API 覆盖内置编解码器与标准 Image I/O 插件（官网特性表）。
• 2.11 变更包含"新增将图像转换为 CMYK 的选项"（官方 Changes 页 FOP-3241）。

4.2 生成 PDF/PostScript

• Graphics2D 实现让 Java 绘图代码无需改动即可输出打印级格式；PDF 组件亦可作为独立 PDF 生成库使用（官网概述）。

4.3 图像加载与转换

• 统一处理位图与矢量图：格式自动探测、按需转换、可扩展的图像提供者机制（1.3 版本起引入，官方 Changes 页）。
• 2.10 引入可配置的源解析（source resolution）能力（官方 Changes 页 FOP-3135）。

五、快速上手

以下示例引自官方图像加载框架文档（https://xmlgraphics.apache.org/commons/image-loader.html），本文不做本地实测。

5.1 Maven 引入

<dependency>
    <groupId>org.apache.xmlgraphics</groupId>
    <artifactId>xmlgraphics-commons</artifactId>
    <version>2.11</version>
</dependency>

运行要求：Java 8 及以上（官方 2.11 POM 声明）。

5.2 用图像加载框架取图像信息

官方文档示例（节选）：

import org.apache.xmlgraphics.image.loader.ImageContext;
import org.apache.xmlgraphics.image.loader.ImageManager;
import org.apache.xmlgraphics.image.loader.impl.DefaultImageContext;

ImageManager imageManager = new ImageManager(new DefaultImageContext());

会话上下文与元信息：

import org.apache.xmlgraphics.image.loader.ImageInfo;
import org.apache.xmlgraphics.image.loader.ImageSessionContext;
import org.apache.xmlgraphics.image.loader.impl.DefaultImageSessionContext;

ImageSessionContext sessionContext = new DefaultImageSessionContext(
        imageManager.getImageContext(), null);
ImageInfo info = imageManager.getImageInfo(uri, sessionContext);

5.3 按目标形态加载图像

官方文档示例（节选）：按 RENDERED_IMAGE 形态请求，得到 RenderedImage 后即可交给 Java2D 处理：

Image img = this.imageManager.getImage(
        info, ImageFlavor.RENDERED_IMAGE, sessionContext);
ImageRendered imageRend = (ImageRendered)img;
RenderedImage ri = imageRend.getRenderedImage();

六、适用场景与限制

6.1 适用场景

• 为 Batik/FOP 做二次开发或深度定制：理解 XGC 即理解两者的共享底座。
• 纯 Java 环境生成 PDF/PostScript：用其 Graphics2D 实现复用既有绘图代码。
• 需要统一处理多格式图像输入（位图+矢量）的服务端管线：图像加载框架提供格式探测与按需转换。

6.2 已知限制

• 定位是"基础组件库"而非端到端工具：没有现成的报表/文档生成器外壳，需要自行组装。
• 2.x 线仅要求并按 Java 8 基线维护，不提供模块化（JPMS）官方声明；新运行时特性跟进有限。
• 社区规模小：GitHub 官方仓库 apache/xmlgraphics-commons stars 约 22（GitHub 页面，2026-10-18 抓取），问题排查主要依赖官网文档与邮件列表。
• 独立使用场景主要覆盖图像编解码、加载与 PDF/PS 输出；SVG 渲染请用 Batik，排版引擎请用 FOP。

七、同类选型对比

7.1 对比对象与数据基准

按"共享底座"的定位选取三个可比对象：Java2D（JDK 内置的标准二维图形与图像 API）、Apache Batik（SVG 渲染与处理）、Apache FOP（XSL-FO 排版输出）。三者构成与 XGC 的上下游关系，量化数据于 2026-10-18 取自官方渠道（Maven Central 元数据、GitHub 仓库页面、JDK 官方文档）。

7.2 量化对比

定位说明：XGC 与 Batik/FOP 是"共享底座-上层应用"关系，而非竞争关系——FOP 的图像输入、Batik 的部分图像能力都落在 XGC 上。Java2D 提供 JDK 级通用绘图与图像处理，但没有 PDF/PostScript 输出与多格式统一加载等打印领域组件，这正是 XGC 的存在价值。

7.3 选型建议

已在用 Batik/FOP 或需要 Java 直出 PDF/PostScript 时选 XML Graphics Commons 2.11；只要标准绘图与图像处理且不涉及打印格式，直接用 Java2D；SVG 场景用 Batik，文档排版场景用 FOP——它们与 XGC 常常是同时引入而非二选一。

八、参考链接

• 项目官网：https://xmlgraphics.apache.org/commons/
• 官方下载页：https://xmlgraphics.apache.org/commons/download.html
• 官方 Changes 页：https://xmlgraphics.apache.org/commons/changes.html
• 图像加载框架文档：https://xmlgraphics.apache.org/commons/image-loader.html
• PostScript 工具文档：https://xmlgraphics.apache.org/commons/postscript.html
• GitHub 仓库：https://github.com/apache/xmlgraphics-commons
• Maven Central 构件目录：https://repo1.maven.org/maven2/org/apache/xmlgraphics/xmlgraphics-commons/