java.lang.Object

cloud.opencode.base.xml.dom.DomUtil

public final class DomUtil extends Object

DOM Utility Class - Utility methods for DOM manipulation DOM 工具类 - DOM 操作的工具方法

This class provides static utility methods for common DOM operations including serialization, conversion, and node manipulation.

此类提供用于常见 DOM 操作的静态工具方法，包括序列化、转换和节点操作。

Features | 主要功能:

Document/Node to String conversion - 文档/节点转字符串
Element to Map conversion - 元素转 Map
Text type conversion - 文本类型转换
Node cloning and manipulation - 节点克隆和操作

Usage Examples | 使用示例:

// Convert document to string
String xml = DomUtil.toString(document, 4);

// Convert element to map
Map<String, String> map = DomUtil.toMap(element);

// Get text content with type conversion
int value = DomUtil.getInt(element, "count", 0);

Security | 安全性:

Thread-safe: Yes (stateless utility) - 线程安全: 是（无状态工具）
Null-safe: No (throws on null document/node) - 空值安全: 否（null 文档/节点抛异常）

Performance | 性能特性:

Time complexity: O(n) for elementToMap/toMap (recursive traversal of all nodes, depth-limited to 1000); O(c) for getChildElements where c=child count; O(1) for scalar getters - 时间复杂度: elementToMap/toMap 为 O(n)（递归遍历所有节点，深度限制为 1000）；getChildElements 为 O(c)，c 为子元素数；标量获取器为 O(1)
Space complexity: O(n) for map conversions; O(1) for scalar operations - 空间复杂度: map 转换为 O(n)；标量操作为 O(1)

Since:

JDK 25, opencode-base-xml V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

static Element

addChildElement(Element parent, String tagName, String text)

Adds a child element with text content.

static Node

cloneInto(Node node, Document document)

Deep clones a node into another document.

static <T> T

convertText(String text, Class<T> clazz)

Converts text to the specified type.

static Document

createDocument()

Creates a new empty Document.

static Document

createDocument(String rootElementName)

Creates a new Document with a root element.

static Map<String,Object>

elementToMap(Element element)

Converts an Element to a Map.

static Map<String,String>

elementToSimpleMap(Element element)

Converts a flat, single-level XML element to a Map<String, String>.

static List<Element>

getChildElements(Node parent)

Gets all child elements of a node.

static List<Element>

getChildElements(Node parent, String tagName)

Gets child elements with the specified tag name.

static String

getChildText(Node parent, String tagName)

Gets the text content of the first child element with the specified tag name.

static Element

getFirstChildElement(Node parent, String tagName)

Gets the first child element with the specified tag name.

static void

removeAllChildren(Node node)

Removes all child nodes from a node.

static String

toString(Document document)

Converts a Document to XML string.

static String

toString(Document document, int indent)

Converts a Document to formatted XML string.

static String

toString(Node node)

Converts a Node to XML string.

static String

toString(Node node, int indent)

Converts a Node to formatted XML string.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- createDocument
  
  public static Document createDocument()
  
  Creates a new empty Document. 创建新的空 Document。
  
  Returns:
  
  a new empty Document | 新的空 Document
- createDocument
  
  public static Document createDocument(String rootElementName)
  
  Creates a new Document with a root element. 创建带根元素的新 Document。
  
  Parameters:
  
  rootElementName - the root element name | 根元素名称
  
  Returns:
  
  the new Document | 新 Document
- toString
  
  public static String toString(Document document)
  
  Converts a Document to XML string. 将 Document 转换为 XML 字符串。
  
  Parameters:
  
  document - the Document | Document
  
  Returns:
  
  the XML string | XML 字符串
- toString
  
  public static String toString(Document document, int indent)
  
  Converts a Document to formatted XML string. 将 Document 转换为格式化的 XML 字符串。
  
  Parameters:
  
  document - the Document | Document
  
  indent - the number of spaces for indentation | 缩进空格数
  
  Returns:
  
  the formatted XML string | 格式化的 XML 字符串
- toString
  
  public static String toString(Node node)
  
  Converts a Node to XML string. 将 Node 转换为 XML 字符串。
  
  Parameters:
  
  node - the Node | Node
  
  Returns:
  
  the XML string | XML 字符串
- toString
  
  public static String toString(Node node, int indent)
  
  Converts a Node to formatted XML string. 将 Node 转换为格式化的 XML 字符串。
  
  Parameters:
  
  node - the Node | Node
  
  indent - the number of spaces for indentation | 缩进空格数
  
  Returns:
  
  the formatted XML string | 格式化的 XML 字符串
- elementToMap
  
  public static Map<String,Object> elementToMap(Element element)
  
  Converts an Element to a Map. 将 Element 转换为 Map。
  
  Parameters:
  
  element - the Element | Element
  
  Returns:
  
  the Map representation | Map 表示
- convertText
  
  public static <T> T convertText(String text, Class<T> clazz)
  
  Converts text to the specified type. 将文本转换为指定类型。
  
  Type Parameters:
  
  T - the type parameter | 类型参数
  
  Parameters:
  
  text - the text to convert | 要转换的文本
  
  clazz - the target type | 目标类型
  
  Returns:
  
  the converted value | 转换后的值
- elementToSimpleMap
  
  public static Map<String,String> elementToSimpleMap(Element element)
  
  Converts a flat, single-level XML element to a Map<String, String>. 将单层 XML 元素转换为 Map<String, String>。
  Only direct child elements are included; attributes and nested child elements are ignored. CDATA sections are automatically merged into text content by the DOM parser, so no manual stripping is needed.
  
  仅包含直接子元素；属性和嵌套子元素被忽略。DOM 解析器自动合并 CDATA 节，无需手动剥离。
  
  The returned map is a TreeMap (naturally ordered by key), which is required by protocols that build deterministic signing strings (e.g. WeChat Pay V2).
  
  返回 TreeMap（按 key 自然排序），满足需要确定性签名串的协议（如微信支付 V2）。
  
  Parameters:
  
  element - the root element whose direct children become map entries | 根元素，其直接子元素成为 map 条目
  
  Returns:
  
  a sorted map of tag-name → text-content | 按标签名排序的 map
  
  Since:
  
  V1.0.4
- cloneInto
  
  public static Node cloneInto(Node node, Document document)
  
  Deep clones a node into another document. 将节点深度克隆到另一个文档。
  
  Parameters:
  
  node - the node to clone | 要克隆的节点
  
  document - the target document | 目标文档
  
  Returns:
  
  the cloned node | 克隆的节点
- getChildElements
  
  public static List<Element> getChildElements(Node parent)
  
  Gets all child elements of a node. 获取节点的所有子元素。
  
  Parameters:
  
  parent - the parent node | 父节点
  
  Returns:
  
  list of child elements | 子元素列表
- getChildElements
  
  public static List<Element> getChildElements(Node parent, String tagName)
  
  Gets child elements with the specified tag name. 获取具有指定标签名的子元素。
  
  Parameters:
  
  parent - the parent node | 父节点
  
  tagName - the tag name | 标签名
  
  Returns:
  
  list of matching elements | 匹配元素列表
- getFirstChildElement
  
  public static Element getFirstChildElement(Node parent, String tagName)
  
  Gets the first child element with the specified tag name. 获取具有指定标签名的第一个子元素。
  
  Parameters:
  
  parent - the parent node | 父节点
  
  tagName - the tag name | 标签名
  
  Returns:
  
  the first matching element, or null | 第一个匹配的元素，或 null
- getChildText
  
  public static String getChildText(Node parent, String tagName)
  
  Gets the text content of the first child element with the specified tag name. 获取具有指定标签名的第一个子元素的文本内容。
  
  Parameters:
  
  parent - the parent node | 父节点
  
  tagName - the tag name | 标签名
  
  Returns:
  
  the text content, or null | 文本内容，或 null
- removeAllChildren
  
  public static void removeAllChildren(Node node)
  
  Removes all child nodes from a node. 从节点移除所有子节点。
  
  Parameters:
  
  node - the node to clear | 要清空的节点
- addChildElement
  
  public static Element addChildElement(Element parent, String tagName, String text)
  
  Adds a child element with text content. 添加带文本内容的子元素。
  
  Parameters:
  
  parent - the parent element | 父元素
  
  tagName - the tag name | 标签名
  
  text - the text content | 文本内容
  
  Returns:
  
  the new element | 新元素

Class DomUtil

Method Summary

Methods inherited from class Object

Method Details

createDocument

createDocument

toString

toString

toString

toString

elementToMap

convertText

elementToSimpleMap

cloneInto

getChildElements

getChildElements

getFirstChildElement

getChildText

removeAllChildren

addChildElement