Class StaxWriter

java.lang.Object
cloud.opencode.base.xml.stax.StaxWriter
All Implemented Interfaces:
Closeable, AutoCloseable
public final class StaxWriter extends Object implements Closeable
StAX Writer - Streaming XML writer StAX 写入器 - 流式 XML 写入器

This class provides a fluent API for streaming XML output using StAX. StAX writing is memory-efficient for generating large XML files.

此类提供使用 StAX 进行流式 XML 输出的流式 API。 StAX 写入对于生成大型 XML 文件内存效率高。

Usage Examples | 使用示例:

// Write to string
String xml = StaxWriter.create()
    .startDocument()
    .startElement("users")
        .startElement("user")
            .attribute("id", "1")
            .element("name", "John")
            .element("email", "john@example.com")
        .endElement()
    .endElement()
    .endDocument()
    .toString();

// Write to file
StaxWriter.create(Path.of("users.xml"))
    .startDocument("UTF-8", "1.0")
    .startElement("users")
    // ... add content
    .endDocument()
    .close();

Features | 主要功能:

  • Fluent API for streaming XML output - 用于流式 XML 输出的流式 API
  • Memory-efficient writing for large XML files - 大型 XML 文件的内存高效写入
  • Automatic indentation and formatting - 自动缩进和格式化
  • Namespace and attribute support - 命名空间和属性支持

Security | 安全性:

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

  • Method Details

    • create

      public static StaxWriter create()
      Creates a new writer that writes to a string. 创建写入字符串的新写入器。
      Returns:
      a new writer | 新写入器

    • create

      public static StaxWriter create(OutputStream output)
      Creates a new writer that writes to an output stream. 创建写入输出流的新写入器。
      Parameters:
      output - the output stream | 输出流
      Returns:
      a new writer | 新写入器

    • create

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

    • formatted

      public StaxWriter formatted(boolean formatted)
      Enables formatted output with indentation. 启用带缩进的格式化输出。
      Parameters:
      formatted - whether to format | 是否格式化
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • indent

      public StaxWriter indent(String indent)
      Sets the indent string. 设置缩进字符串。
      Parameters:
      indent - the indent string | 缩进字符串
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • indent

      public StaxWriter indent(int spaces)
      Sets the indent size in spaces. 设置空格缩进大小。
      Parameters:
      spaces - the number of spaces | 空格数
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • startDocument

      public StaxWriter startDocument()
      Writes the XML declaration. 写入 XML 声明。
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • startDocument

      public StaxWriter startDocument(String encoding, String version)
      Writes the XML declaration with encoding and version. 写入带编码和版本的 XML 声明。
      Parameters:
      encoding - the encoding | 编码
      version - the XML version | XML 版本
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • endDocument

      public StaxWriter endDocument()
      Ends the document. 结束文档。
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • startElement

      public StaxWriter startElement(String localName)
      Starts an element. 开始一个元素。
      Parameters:
      localName - the element name | 元素名称
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • startElement

      public StaxWriter startElement(String namespaceURI, String localName)
      Starts an element with namespace. 开始带命名空间的元素。
      Parameters:
      namespaceURI - the namespace URI | 命名空间 URI
      localName - the element name | 元素名称
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • startElement

      public StaxWriter startElement(String prefix, String localName, String namespaceURI)
      Starts an element with prefix and namespace. 开始带前缀和命名空间的元素。
      Parameters:
      prefix - the prefix | 前缀
      localName - the element name | 元素名称
      namespaceURI - the namespace URI | 命名空间 URI
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • endElement

      public StaxWriter endElement()
      Ends the current element. 结束当前元素。
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • emptyElement

      public StaxWriter emptyElement(String localName)
      Writes an empty element. 写入空元素。
      Parameters:
      localName - the element name | 元素名称
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • element

      public StaxWriter element(String localName, String text)
      Writes a complete element with text content. 写入带文本内容的完整元素。
      Parameters:
      localName - the element name | 元素名称
      text - the text content | 文本内容
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • elementIfNotNull

      public StaxWriter elementIfNotNull(String localName, String text)
      Writes a complete element with text content if not null. 如果不为 null 则写入带文本内容的完整元素。
      Parameters:
      localName - the element name | 元素名称
      text - the text content | 文本内容
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • element

      public StaxWriter element(String localName, Number value)
      Writes a complete element with number content. 写入带数字内容的完整元素。
      Parameters:
      localName - the element name | 元素名称
      value - the number value | 数字值
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • element

      public StaxWriter element(String localName, boolean value)
      Writes a complete element with boolean content. 写入带布尔内容的完整元素。
      Parameters:
      localName - the element name | 元素名称
      value - the boolean value | 布尔值
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • attribute

      public StaxWriter attribute(String localName, String value)
      Writes an attribute. 写入属性。
      Parameters:
      localName - the attribute name | 属性名称
      value - the attribute value | 属性值
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • attribute

      public StaxWriter attribute(String namespaceURI, String localName, String value)
      Writes an attribute with namespace. 写入带命名空间的属性。
      Parameters:
      namespaceURI - the namespace URI | 命名空间 URI
      localName - the attribute name | 属性名称
      value - the attribute value | 属性值
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • attribute

      public StaxWriter attribute(String prefix, String namespaceURI, String localName, String value)
      Writes an attribute with prefix and namespace. 写入带前缀和命名空间的属性。
      Parameters:
      prefix - the prefix | 前缀
      namespaceURI - the namespace URI | 命名空间 URI
      localName - the attribute name | 属性名称
      value - the attribute value | 属性值
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • attributeIfNotNull

      public StaxWriter attributeIfNotNull(String localName, String value)
      Writes an attribute if value is not null. 如果值不为 null 则写入属性。
      Parameters:
      localName - the attribute name | 属性名称
      value - the attribute value | 属性值
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • attribute

      public StaxWriter attribute(String localName, Number value)
      Writes an attribute with number value. 写入带数字值的属性。
      Parameters:
      localName - the attribute name | 属性名称
      value - the number value | 数字值
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • attribute

      public StaxWriter attribute(String localName, boolean value)
      Writes an attribute with boolean value. 写入带布尔值的属性。
      Parameters:
      localName - the attribute name | 属性名称
      value - the boolean value | 布尔值
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • text

      public StaxWriter text(String text)
      Writes text content. 写入文本内容。
      Parameters:
      text - the text | 文本
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • cdata

      public StaxWriter cdata(String data)
      Writes CDATA content. 写入 CDATA 内容。
      Parameters:
      data - the CDATA content | CDATA 内容
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • comment

      public StaxWriter comment(String comment)
      Writes a comment. 写入注释。
      Parameters:
      comment - the comment text | 注释文本
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • processingInstruction

      public StaxWriter processingInstruction(String target, String data)
      Writes a processing instruction. 写入处理指令。
      Parameters:
      target - the target | 目标
      data - the data | 数据
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • defaultNamespace

      public StaxWriter defaultNamespace(String namespaceURI)
      Writes a default namespace declaration. 写入默认命名空间声明。
      Parameters:
      namespaceURI - the namespace URI | 命名空间 URI
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • namespace

      public StaxWriter namespace(String prefix, String namespaceURI)
      Writes a namespace declaration. 写入命名空间声明。
      Parameters:
      prefix - the prefix | 前缀
      namespaceURI - the namespace URI | 命名空间 URI
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • flush

      public StaxWriter flush()
      Flushes the writer. 刷新写入器。
      Returns:
      this writer for chaining | 此写入器以便链式调用

    • getUnderlyingWriter

      public XMLStreamWriter getUnderlyingWriter()
      Gets the underlying XMLStreamWriter. 获取底层 XMLStreamWriter。
      Returns:
      the underlying writer | 底层写入器

    • close

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

    • toString

      public String toString()
      Overrides:
      toString in class Object