Class StaxReader

java.lang.Object
cloud.opencode.base.xml.stax.StaxReader
All Implemented Interfaces:
Closeable, AutoCloseable
public final class StaxReader extends Object implements Closeable
StAX Reader - Pull-mode streaming XML reader StAX 读取器 - 拉模式流式 XML 读取器

This class provides a fluent API for pull-mode XML parsing using StAX. StAX is efficient for both memory and CPU when processing large XML files.

此类提供使用 StAX 进行拉模式 XML 解析的流式 API。 StAX 在处理大型 XML 文件时内存和 CPU 效率都很高。

Usage Examples | 使用示例:

// Simple iteration
try (StaxReader reader = StaxReader.of(xml)) {
    while (reader.hasNext()) {
        if (reader.isStartElement("user")) {
            String id = reader.getAttribute("id");
            String name = reader.getElementText("name");
        }
        reader.next();
    }
}

// Callback-based reading
StaxReader.of(xml)
    .onElement("user", (name, attrs) -> {
        System.out.println("User: " + attrs.get("id"));
    })
    .onText("name", text -> {
        System.out.println("Name: " + text);
    })
    .read();

Features | 主要功能:

  • Pull-mode streaming XML parsing - 拉模式流式 XML 解析
  • Memory-efficient for large XML files - 大型 XML 文件的内存高效处理
  • AutoCloseable for resource management - 支持 AutoCloseable 的资源管理
  • Element and attribute access helpers - 元素和属性访问辅助方法

Security | 安全性:

  • Thread-safe: No (not designed for shared use) - 线程安全: 否（不适用于共享使用）
  • Null-safe: No (throws on null input) - 空值安全: 否（null 输入抛异常）
Since:
JDK 25, opencode-base-xml V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • of

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

    • of

      public static StaxReader of(InputStream input)
      Creates a reader from an input stream. 从输入流创建读取器。
      Parameters:
      input - the input stream | 输入流
      Returns:
      a new reader | 新读取器

    • of

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

    • ofSecure

      public static StaxReader ofSecure(String xml)
      Creates a secure reader from an XML string. 从 XML 字符串创建安全读取器。
      Parameters:
      xml - the XML string | XML 字符串
      Returns:
      a new secure reader | 新的安全读取器

    • hasNext

      public boolean hasNext()
      Checks if there are more events. 检查是否有更多事件。
      Returns:
      true if more events exist | 如果存在更多事件则返回 true

    • next

      public int next()
      Moves to the next event. 移动到下一个事件。
      Returns:
      the event type | 事件类型

    • nextTag

      public int nextTag()
      Moves to the next tag (start or end element). 移动到下一个标签（开始或结束元素）。
      Returns:
      the event type | 事件类型

    • getEventType

      public int getEventType()
      Gets the current event type. 获取当前事件类型。
      Returns:
      the event type | 事件类型

    • isStartElement

      public boolean isStartElement()
      Checks if the current event is a start element. 检查当前事件是否是开始元素。
      Returns:
      true if start element | 如果是开始元素则返回 true

    • isStartElement

      public boolean isStartElement(String localName)
      Checks if the current event is a start element with the given name. 检查当前事件是否是具有给定名称的开始元素。
      Parameters:
      localName - the element name | 元素名称
      Returns:
      true if matching start element | 如果是匹配的开始元素则返回 true

    • isEndElement

      public boolean isEndElement()
      Checks if the current event is an end element. 检查当前事件是否是结束元素。
      Returns:
      true if end element | 如果是结束元素则返回 true

    • isEndElement

      public boolean isEndElement(String localName)
      Checks if the current event is an end element with the given name. 检查当前事件是否是具有给定名称的结束元素。
      Parameters:
      localName - the element name | 元素名称
      Returns:
      true if matching end element | 如果是匹配的结束元素则返回 true

    • isCharacters

      public boolean isCharacters()
      Checks if the current event is characters. 检查当前事件是否是字符。
      Returns:
      true if characters | 如果是字符则返回 true

    • isWhiteSpace

      public boolean isWhiteSpace()
      Checks if the current event is whitespace. 检查当前事件是否是空白字符。
      Returns:
      true if whitespace | 如果是空白字符则返回 true

    • getLocalName

      public String getLocalName()
      Gets the local name of the current element. 获取当前元素的本地名称。
      Returns:
      the local name | 本地名称

    • getNamespaceURI

      public String getNamespaceURI()
      Gets the namespace URI of the current element. 获取当前元素的命名空间 URI。
      Returns:
      the namespace URI | 命名空间 URI

    • getPrefix

      public String getPrefix()
      Gets the prefix of the current element. 获取当前元素的前缀。
      Returns:
      the prefix | 前缀

    • getAttribute

      public String getAttribute(String localName)
      Gets an attribute value. 获取属性值。
      Parameters:
      localName - the attribute name | 属性名称
      Returns:
      the attribute value or null | 属性值或 null

    • getAttribute

      public String getAttribute(String namespaceURI, String localName)
      Gets an attribute value with namespace. 获取带命名空间的属性值。
      Parameters:
      namespaceURI - the namespace URI | 命名空间 URI
      localName - the attribute name | 属性名称
      Returns:
      the attribute value or null | 属性值或 null

    • getAttributeOptional

      public Optional<String> getAttributeOptional(String localName)
      Gets an attribute value as Optional. 获取属性值作为 Optional。
      Parameters:
      localName - the attribute name | 属性名称
      Returns:
      Optional containing the value | 包含值的 Optional

    • getAttributes

      public Map<String,String> getAttributes()
      Gets all attributes as a map. 获取所有属性作为映射。
      Returns:
      map of attribute names to values | 属性名称到值的映射

    • getText

      public String getText()
      Gets the text content of the current element. 获取当前元素的文本内容。
      Returns:
      the text content | 文本内容

    • getElementText

      public String getElementText()
      Gets the element text (must be on START_ELEMENT). 获取元素文本（必须在 START_ELEMENT 上）。
      Returns:
      the element text | 元素文本

    • getElementText

      public String getElementText(String elementName)
      Reads text content from a child element. 从子元素读取文本内容。
      Parameters:
      elementName - the element name | 元素名称
      Returns:
      the text content or null | 文本内容或 null

    • onElement

      public StaxReader onElement(String elementName, BiConsumer<String, Map<String,String>> callback)
      Registers a callback for element start. 注册元素开始的回调。
      Parameters:
      elementName - the element name | 元素名称
      callback - the callback (name, attributes) | 回调（名称，属性）
      Returns:
      this reader for chaining | 此读取器以便链式调用

    • onText

      public StaxReader onText(String elementName, Consumer<String> callback)
      Registers a callback for element text. 注册元素文本的回调。
      Parameters:
      elementName - the element name | 元素名称
      callback - the callback (text) | 回调（文本）
      Returns:
      this reader for chaining | 此读取器以便链式调用

    • onEndElement

      public StaxReader onEndElement(Consumer<String> callback)
      Registers a callback for any element end. 注册任意元素结束的回调。
      Parameters:
      callback - the callback (element name) | 回调（元素名称）
      Returns:
      this reader for chaining | 此读取器以便链式调用

    • read

      public void read()
      Reads the entire document using registered callbacks. 使用注册的回调读取整个文档。

    • skipToNextStartElement

      public boolean skipToNextStartElement()
      Skips to the next start element. 跳转到下一个开始元素。
      Returns:
      true if found | 如果找到则返回 true

    • skipTo

      public boolean skipTo(String elementName)
      Skips to a specific element. 跳转到特定元素。
      Parameters:
      elementName - the element name | 元素名称
      Returns:
      true if found | 如果找到则返回 true

    • require

      public void require(String localName)
      Requires the current element to be a start element with the given name. 要求当前元素是具有给定名称的开始元素。
      Parameters:
      localName - the expected element name | 预期的元素名称
      Throws:
      NoSuchElementException - if not matching | 如果不匹配则抛出异常

    • getUnderlyingReader

      public XMLStreamReader getUnderlyingReader()
      Gets the underlying XMLStreamReader. 获取底层 XMLStreamReader。
      Returns:
      the underlying reader | 底层读取器

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable