Class XmlElement

java.lang.Object
cloud.opencode.base.xml.XmlElement
All Implemented Interfaces:
XmlNode
public final class XmlElement extends Object implements XmlNode
XML Element - Wrapper for DOM Element with fluent API XML 元素 - 提供流式 API 的 DOM Element 封装

This class wraps a DOM Element and provides convenient methods for accessing and manipulating XML content.

此类封装 DOM Element，并提供便捷的方法来访问和操作 XML 内容。

Features | 主要功能:

  • Fluent API for element access and modification - 元素访问和修改的流式 API
  • Attribute read/write operations - 属性读写操作
  • Child element navigation and manipulation - 子元素导航和操作
  • XPath queries relative to this element - 相对于此元素的 XPath 查询
  • Type-safe text conversion - 类型安全的文本转换
  • Object binding support - 对象绑定支持

Usage Examples | 使用示例:

XmlElement element = XmlElement.of(domElement);

// Get element info
String name = element.getName();
String text = element.getText();

// Access attributes
String id = element.getAttribute("id");
Map<String, String> attrs = element.getAttributes();

// Access children
XmlElement child = element.getChild("name");
List<XmlElement> items = element.getChildren("item");

// XPath queries
String value = element.xpath("./name/text()");
List<XmlElement> results = element.xpathList(".//item");

Security | 安全性:

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

  • Method Details

    • of

      public static XmlElement of(Element element)
      Creates an XmlElement from a DOM Element. 从 DOM Element 创建 XmlElement。
      Parameters:
      element - the DOM Element | DOM Element
      Returns:
      the XmlElement | XmlElement

    • of

      public static XmlElement of(Node node)
      Creates an XmlElement from a DOM Node (if it's an Element). 从 DOM Node 创建 XmlElement（如果是 Element）。
      Parameters:
      node - the DOM Node | DOM Node
      Returns:
      the XmlElement | XmlElement
      Throws:
      OpenXmlException - if node is not an Element | 如果节点不是 Element 则抛出异常

    • getElement

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

    • getNode

      public Node getNode()
      Description copied from interface: XmlNode
      Returns the underlying DOM Node. 返回底层的 DOM 节点。
      Specified by:
      getNode in interface XmlNode
      Returns:
      the DOM node | DOM 节点

    • getName

      public String getName()
      Description copied from interface: XmlNode
      Returns the node name. 返回节点名称。
      Specified by:
      getName in interface XmlNode
      Returns:
      the node name | 节点名称

    • getLocalName

      public String getLocalName()
      Description copied from interface: XmlNode
      Returns the local name (without namespace prefix). 返回本地名称（不含命名空间前缀）。
      Specified by:
      getLocalName in interface XmlNode
      Returns:
      the local name | 本地名称

    • getNamespaceUri

      public String getNamespaceUri()
      Description copied from interface: XmlNode
      Returns the namespace URI. 返回命名空间 URI。
      Specified by:
      getNamespaceUri in interface XmlNode
      Returns:
      the namespace URI, or null if not set | 命名空间 URI，如果未设置则返回 null

    • getPrefix

      public String getPrefix()
      Description copied from interface: XmlNode
      Returns the namespace prefix. 返回命名空间前缀。
      Specified by:
      getPrefix in interface XmlNode
      Returns:
      the prefix, or null if not set | 前缀，如果未设置则返回 null

    • getText

      public String getText()
      Description copied from interface: XmlNode
      Returns the text content. 返回文本内容。
      Specified by:
      getText in interface XmlNode
      Returns:
      the text content | 文本内容

    • getTextTrim

      public String getTextTrim()
      Description copied from interface: XmlNode
      Returns the text content trimmed. 返回去除空白的文本内容。
      Specified by:
      getTextTrim in interface XmlNode
      Returns:
      the trimmed text content | 去除空白的文本内容

    • hasText

      public boolean hasText()
      Description copied from interface: XmlNode
      Returns whether this node has any text content. 返回此节点是否有任何文本内容。
      Specified by:
      hasText in interface XmlNode
      Returns:
      true if has text content | 如果有文本内容则返回 true

    • setText

      public XmlElement setText(String text)
      Sets the text content. 设置文本内容。
      Parameters:
      text - the text content | 文本内容
      Returns:
      this element for chaining | 此元素以便链式调用

    • getTextAs

      public <T> T getTextAs(Class<T> clazz)
      Returns the text content converted to the specified type. 返回转换为指定类型的文本内容。
      Type Parameters:
      T - the type parameter | 类型参数
      Parameters:
      clazz - the target type | 目标类型
      Returns:
      the converted value | 转换后的值

    • getText

      public String getText(String defaultValue)
      Returns the text content or default value if null/empty. 返回文本内容，如果为 null/空则返回默认值。
      Parameters:
      defaultValue - the default value | 默认值
      Returns:
      the text content or default | 文本内容或默认值

    • getAttribute

      public String getAttribute(String name)
      Returns the attribute value. 返回属性值。
      Parameters:
      name - the attribute name | 属性名
      Returns:
      the attribute value, or null if not present | 属性值，如果不存在则返回 null

    • getAttribute

      public String getAttribute(String name, String defaultValue)
      Returns the attribute value or default. 返回属性值或默认值。
      Parameters:
      name - the attribute name | 属性名
      defaultValue - the default value | 默认值
      Returns:
      the attribute value or default | 属性值或默认值

    • getAttribute

      public <T> T getAttribute(String name, Class<T> clazz)
      Returns the attribute value converted to the specified type. 返回转换为指定类型的属性值。
      Type Parameters:
      T - the type parameter | 类型参数
      Parameters:
      name - the attribute name | 属性名
      clazz - the target type | 目标类型
      Returns:
      the converted value | 转换后的值

    • getAttributes

      public Map<String,String> getAttributes()
      Returns all attributes as a Map. 返回所有属性为 Map。
      Returns:
      the attributes Map | 属性 Map

    • setAttribute

      public XmlElement setAttribute(String name, String value)
      Sets an attribute value. 设置属性值。
      Parameters:
      name - the attribute name | 属性名
      value - the attribute value | 属性值
      Returns:
      this element for chaining | 此元素以便链式调用

    • removeAttribute

      public XmlElement removeAttribute(String name)
      Removes an attribute. 移除属性。
      Parameters:
      name - the attribute name | 属性名
      Returns:
      this element for chaining | 此元素以便链式调用

    • hasAttribute

      public boolean hasAttribute(String name)
      Returns whether this element has the specified attribute. 返回此元素是否具有指定的属性。
      Parameters:
      name - the attribute name | 属性名
      Returns:
      true if attribute exists | 如果属性存在则返回 true

    • getChild

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

    • getChildren

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

    • getChildren

      public List<XmlElement> getChildren()
      Returns all child elements. 返回所有子元素。
      Returns:
      the list of all child elements | 所有子元素列表

    • getChildText

      public String getChildText(String name)
      Returns the text content of a child element. 返回子元素的文本内容。
      Parameters:
      name - the child element name | 子元素名称
      Returns:
      the text content, or null if not found | 文本内容，如果未找到则返回 null

    • getChildText

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

    • hasChild

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

    • getChildCount

      public int getChildCount()
      Returns the number of child elements. 返回子元素数量。
      Returns:
      the child count | 子元素数量

    • addChild

      public XmlElement addChild(String name)
      Adds a new child element. 添加新的子元素。
      Parameters:
      name - the element name | 元素名称
      Returns:
      the new child element | 新子元素

    • addChild

      public XmlElement addChild(String name, String text)
      Adds a new child element with text content. 添加带文本内容的新子元素。
      Parameters:
      name - the element name | 元素名称
      text - the text content | 文本内容
      Returns:
      the new child element | 新子元素

    • addChild

      public XmlElement addChild(XmlElement child)
      Adds an existing element as a child. 将现有元素添加为子元素。
      Parameters:
      child - the child element to add | 要添加的子元素
      Returns:
      this element for chaining | 此元素以便链式调用

    • removeChild

      public XmlElement removeChild(String name)
      Removes child elements with the specified name. 移除具有指定名称的子元素。
      Parameters:
      name - the child element name | 子元素名称
      Returns:
      this element for chaining | 此元素以便链式调用

    • removeChildren

      public XmlElement removeChildren()
      Removes all child elements. 移除所有子元素。
      Returns:
      this element for chaining | 此元素以便链式调用

    • getParent

      public XmlElement getParent()
      Returns the parent element. 返回父元素。
      Returns:
      the parent element, or null if this is the root | 父元素，如果是根元素则返回 null

    • hasParent

      public boolean hasParent()
      Returns whether this element has a parent element. 返回此元素是否有父元素。
      Returns:
      true if has parent | 如果有父元素则返回 true

    • xpath

      public String xpath(String xpath)
      Evaluates an XPath expression relative to this element. 相对于此元素求值 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 | 匹配元素列表

    • bind

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

    • toMap

      public Map<String,Object> toMap()
      Description copied from interface: XmlNode
      Converts this node to a Map. 将此节点转换为 Map。
      Specified by:
      toMap in interface XmlNode
      Returns:
      the Map representation | Map 表示

    • toXml

      public String toXml()
      Description copied from interface: XmlNode
      Converts this node to XML string. 将此节点转换为 XML 字符串。
      Specified by:
      toXml in interface XmlNode
      Returns:
      the XML string | XML 字符串

    • toXml

      public String toXml(int indent)
      Description copied from interface: XmlNode
      Converts this node to XML string with indentation. 将此节点转换为带缩进的 XML 字符串。
      Specified by:
      toXml in interface XmlNode
      Parameters:
      indent - the number of spaces for indentation | 缩进空格数
      Returns:
      the formatted XML string | 格式化的 XML 字符串

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object