Class OpenXml

java.lang.Object
cloud.opencode.base.xml.OpenXml
public final class OpenXml extends Object
OpenXml - Unified facade for XML operations OpenXml - XML 操作的统一门面

This class provides a unified entry point for all XML operations in the opencode-base-xml module.

此类为 opencode-base-xml 模块中的所有 XML 操作提供统一入口点。

Features | 主要功能:

  • XML parsing from String, File, InputStream - 从字符串、文件、输入流解析 XML
  • Fluent XML document building - 流式 XML 文档构建
  • XPath querying with namespace support - 支持命名空间的 XPath 查询
  • XML Schema and DTD validation - XML Schema 和 DTD 验证
  • XSLT transformation - XSLT 转换
  • XML-to-object binding and marshalling - XML 到对象绑定和编组
  • SAX and StAX streaming parsers - SAX 和 StAX 流式解析器
  • Namespace management utilities - 命名空间管理工具
  • XML diff and comparison - XML 差异比较
  • XML document merging - XML 文档合并
  • Dot-notation path access - 点表示法路径访问
  • Stream-based XML splitting - 基于流的 XML 拆分
  • XML canonicalization - XML 规范化

Usage Examples | 使用示例:

// Parse XML
XmlDocument doc = OpenXml.parse(xmlString);
XmlDocument doc = OpenXml.parseFile(path);

// Build XML
XmlDocument doc = OpenXml.builder("root")
    .element("child", "value")
    .build();

// XPath queries
String value = OpenXml.xpath(doc, "//name/text()");
List<XmlElement> elements = OpenXml.xpathElements(doc, "//item");

// Validate
boolean valid = OpenXml.isWellFormed(xml);
ValidationResult result = OpenXml.validateSchema(xml, schemaPath);

// Transform
String formatted = OpenXml.format(xml, 4);
String result = OpenXml.xslt(xml, xsltPath);

// Bind to objects
User user = OpenXml.unmarshal(xml, User.class);
String xml = OpenXml.marshal(user);

Security | 安全性:

  • Thread-safe: Yes (all static methods, no shared mutable state) - 线程安全: 是（全部静态方法，无共享可变状态）
  • Null-safe: No (null inputs throw exceptions) - 空值安全: 否（空值输入抛出异常）
  • XXE protection enabled by default - 默认启用 XXE 防护
Since:
JDK 25, opencode-base-xml V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • parse

      public static XmlDocument parse(String xml)
      Parses an XML string to XmlDocument. 将 XML 字符串解析为 XmlDocument。
      Parameters:
      xml - the XML string | XML 字符串
      Returns:
      the parsed document | 解析后的文档

    • parseFile

      public static XmlDocument parseFile(Path path)
      Parses an XML file to XmlDocument. 将 XML 文件解析为 XmlDocument。
      Parameters:
      path - the file path | 文件路径
      Returns:
      the parsed document | 解析后的文档

    • parse

      public static XmlDocument parse(InputStream input)
      Parses an XML input stream to XmlDocument. 将 XML 输入流解析为 XmlDocument。
      Parameters:
      input - the input stream | 输入流
      Returns:
      the parsed document | 解析后的文档

    • builder

      public static XmlBuilder builder(String rootName)
      Creates an XML builder with the given root element name. 使用给定的根元素名称创建 XML 构建器。
      Parameters:
      rootName - the root element name | 根元素名称
      Returns:
      a new builder | 新构建器

    • builder

      public static XmlBuilder builder(String namespaceUri, String rootName)
      Creates an XML builder with namespace. 使用命名空间创建 XML 构建器。
      Parameters:
      namespaceUri - the namespace URI | 命名空间 URI
      rootName - the root element name | 根元素名称
      Returns:
      a new builder | 新构建器

    • element

      public static ElementBuilder element(String name)
      Creates an element builder. 创建元素构建器。
      Parameters:
      name - the element name | 元素名称
      Returns:
      a new element builder | 新元素构建器

    • xpath

      public static String xpath(XmlDocument doc, String xpath)
      Evaluates an XPath expression and returns a string. 计算 XPath 表达式并返回字符串。
      Parameters:
      doc - the document | 文档
      xpath - the XPath expression | XPath 表达式
      Returns:
      the result string | 结果字符串

    • xpath

      public static String xpath(XmlDocument doc, String xpath, Map<String,String> namespaces)
      Evaluates an XPath expression with namespaces. 使用命名空间计算 XPath 表达式。
      Parameters:
      doc - the document | 文档
      xpath - the XPath expression | XPath 表达式
      namespaces - the namespace map | 命名空间映射
      Returns:
      the result string | 结果字符串

    • xpathElements

      public static List<XmlElement> xpathElements(XmlDocument doc, String xpath)
      Evaluates an XPath expression and returns elements. 计算 XPath 表达式并返回元素列表。
      Parameters:
      doc - the document | 文档
      xpath - the XPath expression | XPath 表达式
      Returns:
      list of matching elements | 匹配元素列表

    • xpath

      public static String xpath(XmlElement element, String xpath)
      Evaluates an XPath expression on an element. 在元素上计算 XPath 表达式。
      Parameters:
      element - the element | 元素
      xpath - the XPath expression | XPath 表达式
      Returns:
      the result string | 结果字符串

    • isWellFormed

      public static boolean isWellFormed(String xml)
      Checks if XML is well-formed. 检查 XML 是否格式良好。
      Parameters:
      xml - the XML string | XML 字符串
      Returns:
      true if well-formed | 如果格式良好则返回 true

    • validateWellFormedness

      public static ValidationResult validateWellFormedness(String xml)
      Validates XML well-formedness. 验证 XML 格式良好性。
      Parameters:
      xml - the XML string | XML 字符串
      Returns:
      the validation result | 验证结果

    • validateSchema

      public static ValidationResult validateSchema(String xml, Path schemaPath)
      Validates XML against a schema. 针对模式验证 XML。
      Parameters:
      xml - the XML string | XML 字符串
      schemaPath - the schema path | 模式路径
      Returns:
      the validation result | 验证结果

    • schemaValidator

      public static SchemaValidator schemaValidator(Path schemaPath)
      Creates a schema validator. 创建模式验证器。
      Parameters:
      schemaPath - the schema path | 模式路径
      Returns:
      a new validator | 新验证器

    • format

      public static String format(String xml, int indent)
      Formats XML with indentation. 使用缩进格式化 XML。
      Parameters:
      xml - the XML string | XML 字符串
      indent - the indent spaces | 缩进空格数
      Returns:
      the formatted XML | 格式化的 XML

    • format

      public static String format(String xml)
      Formats XML with default indentation (4 spaces). 使用默认缩进（4 空格）格式化 XML。
      Parameters:
      xml - the XML string | XML 字符串
      Returns:
      the formatted XML | 格式化的 XML

    • minify

      public static String minify(String xml)
      Minifies XML by removing whitespace. 通过删除空白来压缩 XML。
      Parameters:
      xml - the XML string | XML 字符串
      Returns:
      the minified XML | 压缩的 XML

    • xslt

      public static String xslt(String xml, Path xsltPath)
      Transforms XML using XSLT. 使用 XSLT 转换 XML。
      Parameters:
      xml - the XML string | XML 字符串
      xsltPath - the XSLT path | XSLT 路径
      Returns:
      the transformed result | 转换结果

    • xsltTransformer

      public static XsltTransformer xsltTransformer(Path xsltPath)
      Creates an XSLT transformer. 创建 XSLT 转换器。
      Parameters:
      xsltPath - the XSLT path | XSLT 路径
      Returns:
      a new transformer | 新转换器

    • xsltTransformer

      public static XsltTransformer xsltTransformer(String xslt)
      Creates an XSLT transformer from string. 从字符串创建 XSLT 转换器。
      Parameters:
      xslt - the XSLT string | XSLT 字符串
      Returns:
      a new transformer | 新转换器

    • unmarshal

      public static <T> T unmarshal(String xml, Class<T> clazz)
      Unmarshals XML to an object. 将 XML 解组为对象。
      Type Parameters:
      T - the type parameter | 类型参数
      Parameters:
      xml - the XML string | XML 字符串
      clazz - the target class | 目标类
      Returns:
      the unmarshalled object | 解组的对象

    • unmarshal

      public static <T> T unmarshal(XmlDocument document, Class<T> clazz)
      Unmarshals XmlDocument to an object. 将 XmlDocument 解组为对象。
      Type Parameters:
      T - the type parameter | 类型参数
      Parameters:
      document - the document | 文档
      clazz - the target class | 目标类
      Returns:
      the unmarshalled object | 解组的对象

    • marshal

      public static String marshal(Object obj)
      Marshals an object to XML string. 将对象编组为 XML 字符串。
      Parameters:
      obj - the object | 对象
      Returns:
      the XML string | XML 字符串

    • marshal

      public static String marshal(Object obj, int indent)
      Marshals an object to formatted XML string. 将对象编组为格式化的 XML 字符串。
      Parameters:
      obj - the object | 对象
      indent - the indent spaces | 缩进空格数
      Returns:
      the XML string | XML 字符串

    • binder

      public static XmlBinder binder()
      Creates an XML binder. 创建 XML 绑定器。
      Returns:
      a new binder | 新绑定器

    • saxParser

      public static SaxParser saxParser()
      Creates a SAX parser. 创建 SAX 解析器。
      Returns:
      a new SAX parser | 新 SAX 解析器

    • staxReader

      public static StaxReader staxReader(String xml)
      Creates a StAX reader. 创建 StAX 读取器。
      Parameters:
      xml - the XML string | XML 字符串
      Returns:
      a new StAX reader | 新 StAX 读取器

    • staxReader

      public static StaxReader staxReader(Path path)
      Creates a StAX reader from file. 从文件创建 StAX 读取器。
      Parameters:
      path - the file path | 文件路径
      Returns:
      a new StAX reader | 新 StAX 读取器

    • staxWriter

      public static StaxWriter staxWriter()
      Creates a StAX writer. 创建 StAX 写入器。
      Returns:
      a new StAX writer | 新 StAX 写入器

    • staxWriter

      public static StaxWriter staxWriter(Path path)
      Creates a StAX writer to file. 创建写入文件的 StAX 写入器。
      Parameters:
      path - the file path | 文件路径
      Returns:
      a new StAX writer | 新 StAX 写入器

    • namespaceContext

      public static OpenNamespaceContext namespaceContext()
      Creates a namespace context. 创建命名空间上下文。
      Returns:
      a new namespace context | 新命名空间上下文

    • namespaceContext

      public static OpenNamespaceContext namespaceContext(XmlDocument document)
      Creates a namespace context from a document. 从文档创建命名空间上下文。
      Parameters:
      document - the document | 文档
      Returns:
      a namespace context | 命名空间上下文

    • extractNamespaces

      public static Map<String,String> extractNamespaces(XmlDocument document)
      Extracts namespaces from a document. 从文档提取命名空间。
      Parameters:
      document - the document | 文档
      Returns:
      map of prefix to URI | 前缀到 URI 的映射

    • diff

      public static List<DiffEntry> diff(String xml1, String xml2)
      Computes the differences between two XML strings. 计算两个 XML 字符串之间的差异。
      Parameters:
      xml1 - the first XML string | 第一个 XML 字符串
      xml2 - the second XML string | 第二个 XML 字符串
      Returns:
      the list of differences | 差异列表

    • diff

      public static List<DiffEntry> diff(XmlDocument doc1, XmlDocument doc2)
      Computes the differences between two XML documents. 计算两个 XML 文档之间的差异。
      Parameters:
      doc1 - the first document | 第一个文档
      doc2 - the second document | 第二个文档
      Returns:
      the list of differences | 差异列表

    • xmlEquals

      public static boolean xmlEquals(String xml1, String xml2)
      Checks whether two XML strings are structurally equal. 检查两个 XML 字符串是否结构相等。
      Parameters:
      xml1 - the first XML string | 第一个 XML 字符串
      xml2 - the second XML string | 第二个 XML 字符串
      Returns:
      true if structurally equal | 如果结构相等则返回 true

    • merge

      public static XmlDocument merge(XmlDocument base, XmlDocument overlay)
      Merges an overlay document onto a base document. 将覆盖文档合并到基础文档上。
      Parameters:
      base - the base document | 基础文档
      overlay - the overlay document | 覆盖文档
      Returns:
      the merged document | 合并后的文档

    • merge

      public static String merge(String baseXml, String overlayXml)
      Merges an overlay XML string onto a base XML string. 将覆盖 XML 字符串合并到基础 XML 字符串上。
      Parameters:
      baseXml - the base XML string | 基础 XML 字符串
      overlayXml - the overlay XML string | 覆盖 XML 字符串
      Returns:
      the merged XML string | 合并后的 XML 字符串

    • path

      public static String path(XmlDocument doc, String path)
      Accesses an element value using dot-notation path. 使用点表示法路径访问元素值。
      Parameters:
      doc - the document | 文档
      path - the dot-notation path (e.g. "root.child.name") | 点表示法路径（例如 "root.child.name"）
      Returns:
      the element text value | 元素文本值

    • pathOptional

      public static Optional<String> pathOptional(XmlDocument doc, String path)
      Accesses an element value using dot-notation path, returning Optional. 使用点表示法路径访问元素值，返回 Optional。
      Parameters:
      doc - the document | 文档
      path - the dot-notation path | 点表示法路径
      Returns:
      the element text value, or empty if not found | 元素文本值，如果未找到则为空

    • split

      public static void split(InputStream input, String elementName, Consumer<XmlDocument> handler)
      Splits an XML input stream by element name and processes each fragment. 按元素名称拆分 XML 输入流并处理每个片段。
      Parameters:
      input - the input stream | 输入流
      elementName - the element name to split on | 要拆分的元素名称
      handler - the fragment handler | 片段处理器

    • splitAll

      public static List<XmlDocument> splitAll(String xml, String elementName)
      Splits an XML string by element name and collects all fragments. 按元素名称拆分 XML 字符串并收集所有片段。
      Parameters:
      xml - the XML string | XML 字符串
      elementName - the element name to split on | 要拆分的元素名称
      Returns:
      the list of fragments | 片段列表

    • canonicalize

      public static String canonicalize(String xml)
      Produces a canonical XML representation of the given XML string. 生成给定 XML 字符串的规范化 XML 表示。
      Parameters:
      xml - the XML string | XML 字符串
      Returns:
      the canonical XML | 规范化的 XML