Class XmlDocument

java.lang.Object
cloud.opencode.base.xml.XmlDocument
public final class XmlDocument extends Object
XML Document - Wrapper for DOM Document with fluent API XML 文档 - 提供流式 API 的 DOM Document 封装

This class wraps a DOM Document and provides convenient methods for parsing, querying, modifying, and serializing XML content.

此类封装 DOM Document，并提供便捷的方法来解析、查询、修改和序列化 XML 内容。

Features | 主要功能:

  • Parse XML from String, File, InputStream, classpath resource - 从字符串、文件、输入流、类路径资源解析 XML
  • XPath query support - XPath 查询支持
  • Element access and modification - 元素访问和修改
  • Object binding via annotations - 通过注解进行对象绑定
  • Serialization to XML string or file - 序列化为 XML 字符串或文件
  • Conversion to Map representation - 转换为 Map 表示

Usage Examples | 使用示例:

// Parse XML string
XmlDocument doc = XmlDocument.parse("<root><item>value</item></root>");

// Load from file
XmlDocument doc = XmlDocument.load(Path.of("config.xml"));

// Create new document
XmlDocument doc = XmlDocument.create("root");

// Access content
XmlElement root = doc.getRoot();
String text = doc.getElementText("item");

// XPath queries
String value = doc.xpath("//item/text()");
List<XmlElement> items = doc.xpathList("//item");

// Bind to object
Config config = doc.bind(Config.class);

// Serialize
String xml = doc.toXml(4); // with 4-space indent
doc.save(Path.of("output.xml"));

Security | 安全性:

  • Thread-safe: No (wraps mutable DOM Document) - 线程安全: 否（封装可变的 DOM Document）
  • Null-safe: No (null inputs throw exceptions) - 空值安全: 否（空值输入抛出异常）
  • Secure parsing with XXE protection - 安全解析，带 XXE 防护
Since:
JDK 25, opencode-base-xml V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • parse

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

    • load

      public static XmlDocument load(Path path)
      Loads XML from file. 从文件加载 XML。
      Parameters:
      path - the file path | 文件路径
      Returns:
      the document | 文档

    • load

      public static XmlDocument load(InputStream input)
      Loads XML from input stream. 从输入流加载 XML。
      Parameters:
      input - the input stream | 输入流
      Returns:
      the document | 文档

    • loadResource

      public static XmlDocument loadResource(String resourceName)
      Loads XML from classpath resource. 从类路径资源加载 XML。
      Parameters:
      resourceName - the resource name | 资源名
      Returns:
      the document | 文档

    • create

      public static XmlDocument create(String rootName)
      Creates an empty document with the specified root element. 创建具有指定根元素的空文档。
      Parameters:
      rootName - the root element name | 根元素名称
      Returns:
      the document | 文档

    • of

      public static XmlDocument of(Document document)
      Wraps an existing DOM Document. 封装现有的 DOM Document。
      Parameters:
      document - the DOM Document | DOM Document
      Returns:
      the wrapped document | 封装的文档

    • getRoot

      public XmlElement getRoot()
      Returns the root element. 返回根元素。
      Returns:
      the root element | 根元素

    • getDocument

      public Document getDocument()
      Returns the underlying DOM Document. 返回底层的 DOM Document。
      Returns:
      the DOM Document | DOM Document

    • xpath

      public String xpath(String xpath)
      Evaluates an XPath expression and returns string result. 求值 XPath 表达式并返回字符串结果。
      Parameters:
      xpath - the XPath expression | XPath 表达式
      Returns:
      the result string | 结果字符串

    • xpathList

      public List<XmlElement> xpathList(String xpath)
      Evaluates an XPath expression and returns element list. 求值 XPath 表达式并返回元素列表。
      Parameters:
      xpath - the XPath expression | XPath 表达式
      Returns:
      the list of matching elements | 匹配元素列表

    • xpathOne

      public XmlElement xpathOne(String xpath)
      Evaluates an XPath expression and returns single element. 求值 XPath 表达式并返回单个元素。
      Parameters:
      xpath - the XPath expression | XPath 表达式
      Returns:
      the element, or null if not found | 元素，如果未找到则返回 null

    • xpath

      public <T> T xpath(String xpath, Class<T> clazz)
      Evaluates an XPath expression and returns typed result. 求值 XPath 表达式并返回类型化结果。
      Type Parameters:
      T - the type parameter | 类型参数
      Parameters:
      xpath - the XPath expression | XPath 表达式
      clazz - the target type | 目标类型
      Returns:
      the typed result | 类型化结果

    • getElement

      public XmlElement getElement(String name)
      Returns the first element with the specified name. 返回具有指定名称的第一个元素。
      Parameters:
      name - the element name | 元素名称
      Returns:
      the element, or null if not found | 元素，如果未找到则返回 null

    • getElements

      public List<XmlElement> getElements(String name)
      Returns all elements with the specified name. 返回具有指定名称的所有元素。
      Parameters:
      name - the element name | 元素名称
      Returns:
      the list of elements | 元素列表

    • getElementText

      public String getElementText(String name)
      Returns the text content of the first element with the specified name. 返回具有指定名称的第一个元素的文本内容。
      Parameters:
      name - the element name | 元素名称
      Returns:
      the text content, or null if not found | 文本内容，如果未找到则返回 null

    • getElementText

      public String getElementText(String name, String defaultValue)
      Returns the text content of an element or default value. 返回元素的文本内容或默认值。
      Parameters:
      name - the element name | 元素名称
      defaultValue - the default value | 默认值
      Returns:
      the text content or default | 文本内容或默认值

    • hasElement

      public boolean hasElement(String name)
      Returns whether an element with the specified name exists. 返回是否存在具有指定名称的元素。
      Parameters:
      name - the element name | 元素名称
      Returns:
      true if element exists | 如果元素存在则返回 true

    • addElement

      public XmlElement addElement(String name, String text)
      Adds an element to the root. 向根元素添加元素。
      Parameters:
      name - the element name | 元素名称
      text - the text content | 文本内容
      Returns:
      the new element | 新元素

    • addElement

      public XmlDocument addElement(XmlElement element)
      Adds an existing element to the root. 向根元素添加现有元素。
      Parameters:
      element - the element to add | 要添加的元素
      Returns:
      this document for chaining | 此文档以便链式调用

    • removeElement

      public XmlDocument removeElement(String name)
      Removes elements with the specified name from the root. 从根元素移除具有指定名称的元素。
      Parameters:
      name - the element name | 元素名称
      Returns:
      this document for chaining | 此文档以便链式调用

    • bind

      public <T> T bind(Class<T> clazz)
      Binds this document to an object. 将此文档绑定到对象。
      Type Parameters:
      T - the type parameter | 类型参数
      Parameters:
      clazz - the target type | 目标类型
      Returns:
      the bound object | 绑定的对象

    • toXml

      public String toXml()
      Converts this document to XML string. 将此文档转换为 XML 字符串。
      Returns:
      the XML string | XML 字符串

    • toXml

      public String toXml(int indent)
      Converts this document to formatted XML string. 将此文档转换为格式化的 XML 字符串。
      Parameters:
      indent - the number of spaces for indentation | 缩进空格数
      Returns:
      the formatted XML string | 格式化的 XML 字符串

    • save

      public void save(Path path)
      Saves this document to file. 将此文档保存到文件。
      Parameters:
      path - the file path | 文件路径

    • toMap

      public Map<String,Object> toMap()
      Converts this document to a Map. 将此文档转换为 Map。
      Returns:
      the Map representation | Map 表示

    • toString

      public String toString()
      Overrides:
      toString in class Object