Class XmlBuilder

java.lang.Object
cloud.opencode.base.xml.builder.XmlBuilder
public final class XmlBuilder extends Object
XML Builder - Fluent builder for XML documents XML 构建器 - XML 文档的流式构建器

This class provides a fluent API for building XML documents programmatically.

此类提供流式 API，用于以编程方式构建 XML 文档。

Features | 主要功能:

  • Fluent document building with element stack - 带元素栈的流式文档构建
  • Namespace, encoding, version, standalone configuration - 命名空间、编码、版本、独立声明配置
  • Element, attribute, text, CDATA, comment, PI support - 元素、属性、文本、CDATA、注释、处理指令支持
  • Conditional element/attribute insertion - 条件性元素/属性插入
  • Consumer-based element configuration - 基于 Consumer 的元素配置

Usage Examples | 使用示例:

// Build a simple XML document
XmlDocument doc = XmlBuilder.create("users")
    .encoding("UTF-8")
    .startElement("user")
        .attribute("id", "1")
        .element("name", "John Doe")
        .element("email", "john@example.com")
    .end()
    .build();

// With namespace
XmlDocument doc = XmlBuilder.create("http://example.com", "users")
    .namespace("http://example.com", "ex")
    .startElement("user")
        .attribute("id", "1")
    .end()
    .build();

// With formatted output
String xml = XmlBuilder.create("root")
    .element("child", "value")
    .build()
    .toXml(4);

Security | 安全性:

  • Thread-safe: No (mutable builder state with element stack) - 线程安全: 否（带元素栈的可变构建器状态）
  • Null-safe: Partial (null values are skipped for attributes and text) - 空值安全: 部分（属性和文本的空值被跳过）

Performance | 性能特性:

  • Time complexity: O(n) overall for building a document with n elements; each startElement/element/attribute call is O(1) amortized - 时间复杂度: 构建含 n 个元素的文档总体为 O(n)；每次 startElement/element/attribute 调用摊销为 O(1)
  • Space complexity: O(d) for the element stack where d=current nesting depth, plus O(n) for the DOM tree - 空间复杂度: 元素栈 O(d)，d 为当前嵌套深度，加上 DOM 树 O(n)
Since:
JDK 25, opencode-base-xml V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static XmlBuilder create(String rootName)
      Creates a new XML builder with the given root element name. 使用给定的根元素名称创建新的 XML 构建器。
      Parameters:
      rootName - the root element name | 根元素名称
      Returns:
      a new builder | 新构建器

    • create

      public static XmlBuilder create(String namespaceURI, String rootName)
      Creates a new XML builder with namespace. 使用命名空间创建新的 XML 构建器。
      Parameters:
      namespaceURI - the namespace URI | 命名空间 URI
      rootName - the root element name | 根元素名称
      Returns:
      a new builder | 新构建器

    • encoding

      public XmlBuilder encoding(String encoding)
      Sets the XML encoding. 设置 XML 编码。
      Parameters:
      encoding - the encoding | 编码
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • version

      public XmlBuilder version(String version)
      Sets the XML version. 设置 XML 版本。
      Parameters:
      version - the version | 版本
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • standalone

      public XmlBuilder standalone(boolean standalone)
      Sets the standalone declaration. 设置独立声明。
      Parameters:
      standalone - whether standalone | 是否独立
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • namespace

      public XmlBuilder namespace(String namespaceURI, String prefix)
      Adds a namespace declaration to the current element. 向当前元素添加命名空间声明。
      Parameters:
      namespaceURI - the namespace URI | 命名空间 URI
      prefix - the prefix | 前缀
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • defaultNamespace

      public XmlBuilder defaultNamespace(String namespaceURI)
      Sets the default namespace on the current element. 在当前元素上设置默认命名空间。
      Parameters:
      namespaceURI - the namespace URI | 命名空间 URI
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • startElement

      public XmlBuilder startElement(String name)
      Starts a new child element. 开始新的子元素。
      Parameters:
      name - the element name | 元素名称
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • startElement

      public XmlBuilder startElement(String namespaceURI, String name)
      Starts a new child element with namespace. 开始带命名空间的新子元素。
      Parameters:
      namespaceURI - the namespace URI | 命名空间 URI
      name - the element name | 元素名称
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • startElement

      public XmlBuilder startElement(String namespaceURI, String prefix, String localName)
      Starts a new child element with prefix and namespace. 开始带前缀和命名空间的新子元素。
      Parameters:
      namespaceURI - the namespace URI | 命名空间 URI
      prefix - the prefix | 前缀
      localName - the local name | 本地名称
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • end

      public XmlBuilder end()
      Ends the current element and returns to the parent. 结束当前元素并返回到父元素。
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • element

      public XmlBuilder element(String name, String text)
      Adds a complete element with text content. 添加带文本内容的完整元素。
      Parameters:
      name - the element name | 元素名称
      text - the text content | 文本内容
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • element

      public XmlBuilder element(String name, Number value)
      Adds a complete element with number content. 添加带数字内容的完整元素。
      Parameters:
      name - the element name | 元素名称
      value - the number value | 数字值
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • element

      public XmlBuilder element(String name, boolean value)
      Adds a complete element with boolean content. 添加带布尔内容的完整元素。
      Parameters:
      name - the element name | 元素名称
      value - the boolean value | 布尔值
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • elementIfNotNull

      public XmlBuilder elementIfNotNull(String name, String text)
      Adds a complete element if value is not null. 如果值不为 null 则添加完整元素。
      Parameters:
      name - the element name | 元素名称
      text - the text content | 文本内容
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • emptyElement

      public XmlBuilder emptyElement(String name)
      Adds an empty element. 添加空元素。
      Parameters:
      name - the element name | 元素名称
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • configure

      public XmlBuilder configure(Consumer<XmlBuilder> configurer)
      Configures the current element using a consumer. 使用消费者配置当前元素。
      Parameters:
      configurer - the element configurer | 元素配置器
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • attribute

      public XmlBuilder attribute(String name, String value)
      Adds an attribute to the current element. 向当前元素添加属性。
      Parameters:
      name - the attribute name | 属性名称
      value - the attribute value | 属性值
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • attribute

      public XmlBuilder attribute(String namespaceURI, String name, String value)
      Adds an attribute with namespace to the current element. 向当前元素添加带命名空间的属性。
      Parameters:
      namespaceURI - the namespace URI | 命名空间 URI
      name - the attribute name | 属性名称
      value - the attribute value | 属性值
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • attribute

      public XmlBuilder attribute(String name, Number value)
      Adds an attribute with number value. 添加带数字值的属性。
      Parameters:
      name - the attribute name | 属性名称
      value - the number value | 数字值
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • attribute

      public XmlBuilder attribute(String name, boolean value)
      Adds an attribute with boolean value. 添加带布尔值的属性。
      Parameters:
      name - the attribute name | 属性名称
      value - the boolean value | 布尔值
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • attributeIfNotNull

      public XmlBuilder attributeIfNotNull(String name, String value)
      Adds an attribute if value is not null. 如果值不为 null 则添加属性。
      Parameters:
      name - the attribute name | 属性名称
      value - the attribute value | 属性值
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • text

      public XmlBuilder text(String text)
      Adds text content to the current element. 向当前元素添加文本内容。
      Parameters:
      text - the text content | 文本内容
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • cdata

      public XmlBuilder cdata(String data)
      Adds CDATA content to the current element. 向当前元素添加 CDATA 内容。
      Parameters:
      data - the CDATA content | CDATA 内容
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • comment

      public XmlBuilder comment(String comment)
      Adds a comment to the current element. 向当前元素添加注释。
      Parameters:
      comment - the comment text | 注释文本
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • processingInstruction

      public XmlBuilder processingInstruction(String target, String data)
      Adds a processing instruction. 添加处理指令。
      Parameters:
      target - the target | 目标
      data - the data | 数据
      Returns:
      this builder for chaining | 此构建器以便链式调用

    • build

      public XmlDocument build()
      Builds and returns the XML document. 构建并返回 XML 文档。
      Returns:
      the built document | 构建的文档

    • buildElement

      public XmlElement buildElement()
      Builds and returns the root element. 构建并返回根元素。
      Returns:
      the root element | 根元素

    • toXml

      public String toXml()
      Builds and returns the XML string. 构建并返回 XML 字符串。
      Returns:
      the XML string | XML 字符串

    • toXml

      public String toXml(int indent)
      Builds and returns the formatted XML string. 构建并返回格式化的 XML 字符串。
      Parameters:
      indent - the indent spaces | 缩进空格数
      Returns:
      the XML string | XML 字符串

    • getDocument

      public Document getDocument()
      Gets the underlying DOM Document. 获取底层 DOM Document。
      Returns:
      the DOM Document | DOM 文档

    • getCurrentElement

      public Element getCurrentElement()
      Gets the current element being built. 获取正在构建的当前元素。
      Returns:
      the current element | 当前元素