java.lang.Object

cloud.opencode.base.xml.builder.ElementBuilder

public final class ElementBuilder extends Object

Element Builder - Fluent builder for XML elements 元素构建器 - XML 元素的流式构建器

This class provides a fluent API for building standalone XML elements.

此类提供流式 API，用于构建独立的 XML 元素。

Features | 主要功能:

Fluent builder pattern for XML elements - XML 元素的流式构建器模式
Attribute, child element, text, CDATA, comment support - 属性、子元素、文本、CDATA、注释支持
Nested element building with startChild/endChild - 通过 startChild/endChild 构建嵌套元素
Namespace-aware element creation - 支持命名空间的元素创建
Consumer-based child configuration - 基于 Consumer 的子元素配置

Usage Examples | 使用示例:

// Build a simple element
XmlElement element = ElementBuilder.create("user")
    .attribute("id", "1")
    .child("name", "John Doe")
    .child("email", "john@example.com")
    .build();

// Build nested elements
XmlElement element = ElementBuilder.create("user")
    .attribute("id", "1")
    .startChild("address")
        .child("city", "New York")
        .child("country", "USA")
    .endChild()
    .build();

Security | 安全性:

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

Performance | 性能特性:

Time complexity: O(n) overall where n=number of children/attributes added; each individual operation is O(1) - 时间复杂度: 总体 O(n)，n 为添加的子元素/属性数量；每次单独操作为 O(1)
Space complexity: O(n) for the DOM subtree built; no auxiliary data structures beyond the DOM itself - 空间复杂度: 构建的 DOM 子树为 O(n)；除 DOM 自身外无额外数据结构

Since:

JDK 25, opencode-base-xml V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

ElementBuilder

attribute(String name, boolean value)

Adds an attribute with boolean value.

ElementBuilder

attribute(String name, Number value)

Adds an attribute with number value.

ElementBuilder

attribute(String name, String value)

Adds an attribute to the element.

ElementBuilder

attribute(String namespaceURI, String name, String value)

Adds an attribute with namespace.

ElementBuilder

attributeIfNotNull(String name, String value)

Adds an attribute if value is not null.

XmlElement

build()

Builds and returns the XmlElement.

ElementBuilder

cdata(String data)

Adds CDATA content.

ElementBuilder

child(XmlElement xmlElement)

Adds a built XmlElement as a child.

ElementBuilder

child(String name, boolean value)

Adds a child element with boolean content.

ElementBuilder

child(String name, Number value)

Adds a child element with number content.

ElementBuilder

child(String name, String text)

Adds a child element with text content.

ElementBuilder

child(String name, Consumer<ElementBuilder> configurer)

Configures a child element using a consumer.

ElementBuilder

childIfNotNull(String name, String text)

Adds a child element if value is not null.

ElementBuilder

comment(String comment)

Adds a comment.

static ElementBuilder

create(String name)

Creates a new element builder with the given name.

static ElementBuilder

create(String namespaceURI, String name)

Creates a new element builder with namespace.

ElementBuilder

defaultNamespace(String namespaceURI)

Sets the default namespace.

ElementBuilder

emptyChild(String name)

Adds an empty child element.

ElementBuilder

endChild()

Ends building the current child and returns to the parent.

ElementBuilder

namespace(String namespaceURI, String prefix)

Adds a namespace declaration.

ElementBuilder

startChild(String name)

Starts building a child element.

ElementBuilder

startChild(String namespaceURI, String name)

Starts building a child element with namespace.

ElementBuilder

text(String text)

Sets the text content of the element.

String

toXml()

Converts the element to an XML string.

String

toXml(int indent)

Converts the element to a formatted XML string.

Element

unwrap()

Gets the underlying DOM Element.

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

Method Details
- create
  
  public static ElementBuilder create(String name)
  
  Creates a new element builder with the given name. 使用给定名称创建新的元素构建器。
  
  Parameters:
  
  name - the element name | 元素名称
  
  Returns:
  
  a new builder | 新构建器
- create
  
  public static ElementBuilder create(String namespaceURI, String name)
  
  Creates a new element builder with namespace. 使用命名空间创建新的元素构建器。
  
  Parameters:
  
  namespaceURI - the namespace URI | 命名空间 URI
  
  name - the element name | 元素名称
  
  Returns:
  
  a new builder | 新构建器
- attribute
  
  public ElementBuilder attribute(String name, String value)
  
  Adds an attribute to the element. 向元素添加属性。
  
  Parameters:
  
  name - the attribute name | 属性名称
  
  value - the attribute value | 属性值
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- attribute
  
  public ElementBuilder attribute(String namespaceURI, String name, String value)
  
  Adds an attribute with namespace. 添加带命名空间的属性。
  
  Parameters:
  
  namespaceURI - the namespace URI | 命名空间 URI
  
  name - the attribute name | 属性名称
  
  value - the attribute value | 属性值
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- attribute
  
  public ElementBuilder 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 ElementBuilder 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 ElementBuilder 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 | 此构建器以便链式调用
- namespace
  
  public ElementBuilder namespace(String namespaceURI, String prefix)
  
  Adds a namespace declaration. 添加命名空间声明。
  
  Parameters:
  
  namespaceURI - the namespace URI | 命名空间 URI
  
  prefix - the prefix | 前缀
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- defaultNamespace
  
  public ElementBuilder defaultNamespace(String namespaceURI)
  
  Sets the default namespace. 设置默认命名空间。
  
  Parameters:
  
  namespaceURI - the namespace URI | 命名空间 URI
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- child
  
  public ElementBuilder child(String name, String text)
  
  Adds a child element with text content. 添加带文本内容的子元素。
  
  Parameters:
  
  name - the element name | 元素名称
  
  text - the text content | 文本内容
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- child
  
  public ElementBuilder child(String name, Number value)
  
  Adds a child element with number content. 添加带数字内容的子元素。
  
  Parameters:
  
  name - the element name | 元素名称
  
  value - the number value | 数字值
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- child
  
  public ElementBuilder child(String name, boolean value)
  
  Adds a child element with boolean content. 添加带布尔内容的子元素。
  
  Parameters:
  
  name - the element name | 元素名称
  
  value - the boolean value | 布尔值
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- childIfNotNull
  
  public ElementBuilder childIfNotNull(String name, String text)
  
  Adds a child element if value is not null. 如果值不为 null 则添加子元素。
  
  Parameters:
  
  name - the element name | 元素名称
  
  text - the text content | 文本内容
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- emptyChild
  
  public ElementBuilder emptyChild(String name)
  
  Adds an empty child element. 添加空子元素。
  
  Parameters:
  
  name - the element name | 元素名称
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- startChild
  
  public ElementBuilder startChild(String name)
  
  Starts building a child element. 开始构建子元素。
  
  Parameters:
  
  name - the element name | 元素名称
  
  Returns:
  
  a new builder for the child | 子元素的新构建器
- startChild
  
  public ElementBuilder startChild(String namespaceURI, String name)
  
  Starts building a child element with namespace. 开始构建带命名空间的子元素。
  
  Parameters:
  
  namespaceURI - the namespace URI | 命名空间 URI
  
  name - the element name | 元素名称
  
  Returns:
  
  a new builder for the child | 子元素的新构建器
- endChild
  
  public ElementBuilder endChild()
  
  Ends building the current child and returns to the parent. 结束构建当前子元素并返回到父元素。
  
  Returns:
  
  the parent builder | 父构建器
- child
  
  public ElementBuilder child(XmlElement xmlElement)
  
  Adds a built XmlElement as a child. 添加已构建的 XmlElement 作为子元素。
  
  Parameters:
  
  xmlElement - the element to add | 要添加的元素
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- child
  
  public ElementBuilder child(String name, Consumer<ElementBuilder> configurer)
  
  Configures a child element using a consumer. 使用消费者配置子元素。
  
  Parameters:
  
  name - the element name | 元素名称
  
  configurer - the element configurer | 元素配置器
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- text
  
  public ElementBuilder text(String text)
  
  Sets the text content of the element. 设置元素的文本内容。
  
  Parameters:
  
  text - the text content | 文本内容
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- cdata
  
  public ElementBuilder cdata(String data)
  
  Adds CDATA content. 添加 CDATA 内容。
  
  Parameters:
  
  data - the CDATA content | CDATA 内容
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- comment
  
  public ElementBuilder comment(String comment)
  
  Adds a comment. 添加注释。
  
  Parameters:
  
  comment - the comment text | 注释文本
  
  Returns:
  
  this builder for chaining | 此构建器以便链式调用
- build
  
  public XmlElement build()
  
  Builds and returns the XmlElement. 构建并返回 XmlElement。
  
  Returns:
  
  the built element | 构建的元素
- unwrap
  
  public Element unwrap()
  
  Gets the underlying DOM Element. 获取底层 DOM 元素。
  
  Returns:
  
  the DOM Element | DOM 元素
- toXml
  
  public String toXml()
  
  Converts the element to an XML string. 将元素转换为 XML 字符串。
  
  Returns:
  
  the XML string | XML 字符串
- toXml
  
  public String toXml(int indent)
  
  Converts the element to a formatted XML string. 将元素转换为格式化的 XML 字符串。
  
  Parameters:
  
  indent - the indent spaces | 缩进空格数
  
  Returns:
  
  the XML string | XML 字符串

Class ElementBuilder

Method Summary

Methods inherited from class Object

Method Details

create

create

attribute

attribute

attribute

attribute

attributeIfNotNull

namespace

defaultNamespace

child

child

child

childIfNotNull

emptyChild

startChild

startChild

endChild

child

child

text

cdata

comment

build

unwrap

toXml

toXml