java.lang.Object

cloud.opencode.base.xml.path.XmlPath

public final class XmlPath extends Object

XML Path - Simplified dot-notation path access for XML documents XML 路径 - XML 文档的简化点表示法路径访问

This utility class provides a simpler alternative to XPath for common XML access patterns. Paths use dot notation to navigate through elements.

此工具类为常见的 XML 访问模式提供了比 XPath 更简单的替代方案。路径使用点表示法来导航元素。

Features | 主要功能:

Dot-notation element navigation: "root.child.name" - 点表示法元素导航
Index-based access: "root.child[2].name" (0-based) - 基于索引的访问（从0开始）
Attribute access: "root.child.@attr" (@ prefix) - 属性访问（@ 前缀）
Multiple element retrieval: getElements for lists - 多元素检索
Typed value access (int, boolean) with defaults - 类型化值访问（int、boolean）带默认值
Path existence checking - 路径存在性检查
Value setting with intermediate element creation - 值设置并自动创建中间元素

Path Syntax | 路径语法:

"root.child.name" — navigate by element name | 按元素名导航
"root.child[2].name" — index-based access (0-based) | 基于索引的访问（从0开始）
"root.child.@attr" — attribute access (@ prefix) | 属性访问（@ 前缀）
"root.items.item" with getElements → returns all item children | 与 getElements 配合返回所有子元素

Usage Examples | 使用示例:

XmlDocument doc = XmlDocument.parse("<config><db><host>localhost</host></db></config>");

// Simple path access
String host = XmlPath.getString(doc, "config.db.host"); // "localhost"

// With default value
int port = XmlPath.getInt(doc, "config.db.port", 3306); // 3306

// Attribute access
String id = XmlPath.getAttribute(doc, "config.db.@id");

// Check existence
boolean exists = XmlPath.exists(doc, "config.db.host"); // true

// Set value (creates intermediate elements)
XmlPath.set(doc, "config.db.port", "5432");

Performance | 性能特性:

Time complexity: O(d) where d = path depth - 时间复杂度: O(d)，d 为路径深度
Space complexity: O(d) for path segment splitting - 空间复杂度: O(d)，路径段分割

Security | 安全性:

Thread-safe: Yes (stateless utility) - 线程安全: 是（无状态工具）
Null-safe: No (null inputs throw NullPointerException) - 空值安全: 否（null 输入抛出 NullPointerException）

Since:

JDK 25, opencode-base-xml V1.0.3

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

static boolean

exists(XmlDocument doc, String path)

Checks whether a path exists in the document.

static String

getAttribute(XmlDocument doc, String path)

Gets an attribute value using @-notation path.

static boolean

getBoolean(XmlDocument doc, String path, boolean defaultValue)

Gets a boolean value at the specified path, or the default if not found.

static XmlElement

getElement(XmlDocument doc, String path)

Gets the element at the specified path.

static List<XmlElement>

getElements(XmlDocument doc, String path)

Gets all matching elements at the specified path.

static int

getInt(XmlDocument doc, String path, int defaultValue)

Gets an integer value at the specified path, or the default if not found or not parseable.

static Optional<String>

getOptional(XmlDocument doc, String path)

Gets an optional text value at the specified path.

static String

getString(XmlDocument doc, String path)

Gets the text value at the specified path.

static String

getString(XmlDocument doc, String path, String defaultValue)

Gets the text value at the specified path, or the default value if not found.

static String

getString(XmlElement element, String path)

Gets the text value at the specified path relative to an element.

static List<String>

getStrings(XmlDocument doc, String path)

Gets text values of all matching elements at the specified path.

static void

set(XmlDocument doc, String path, String value)

Sets the value at the specified path, creating intermediate elements as needed.

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

Method Details
- getString
  
  public static String getString(XmlDocument doc, String path)
  
  Gets the text value at the specified path. 获取指定路径处的文本值。
  
  Parameters:
  
  doc - the XML document | XML 文档
  
  path - the dot-notation path | 点表示法路径
  
  Returns:
  
  the text value, or null if not found | 文本值，如果未找到则返回 null
- getString
  
  public static String getString(XmlElement element, String path)
  
  Gets the text value at the specified path relative to an element. 获取相对于元素的指定路径处的文本值。
  
  Parameters:
  
  element - the starting element | 起始元素
  
  path - the dot-notation path | 点表示法路径
  
  Returns:
  
  the text value, or null if not found | 文本值，如果未找到则返回 null
- getOptional
  
  public static Optional<String> getOptional(XmlDocument doc, String path)
  
  Gets an optional text value at the specified path. 获取指定路径处的可选文本值。
  
  Parameters:
  
  doc - the XML document | XML 文档
  
  path - the dot-notation path | 点表示法路径
  
  Returns:
  
  an Optional containing the text value, or empty if not found | 包含文本值的 Optional，如果未找到则为空
- getString
  
  public static String getString(XmlDocument doc, String path, String defaultValue)
  
  Gets the text value at the specified path, or the default value if not found. 获取指定路径处的文本值，如果未找到则返回默认值。
  
  Parameters:
  
  doc - the XML document | XML 文档
  
  path - the dot-notation path | 点表示法路径
  
  defaultValue - the default value | 默认值
  
  Returns:
  
  the text value or default | 文本值或默认值
- getInt
  
  public static int getInt(XmlDocument doc, String path, int defaultValue)
  
  Gets an integer value at the specified path, or the default if not found or not parseable. 获取指定路径处的整数值，如果未找到或无法解析则返回默认值。
  
  Parameters:
  
  doc - the XML document | XML 文档
  
  path - the dot-notation path | 点表示法路径
  
  defaultValue - the default value | 默认值
  
  Returns:
  
  the int value or default | 整数值或默认值
- getBoolean
  
  public static boolean getBoolean(XmlDocument doc, String path, boolean defaultValue)
  
  Gets a boolean value at the specified path, or the default if not found. 获取指定路径处的布尔值，如果未找到则返回默认值。
  "true" (case-insensitive) returns true; anything else returns the default.
  
  "true"（不区分大小写）返回 true；其他值返回默认值。
  
  Parameters:
  
  doc - the XML document | XML 文档
  
  path - the dot-notation path | 点表示法路径
  
  defaultValue - the default value | 默认值
  
  Returns:
  
  the boolean value or default | 布尔值或默认值
- getAttribute
  
  public static String getAttribute(XmlDocument doc, String path)
  
  Gets an attribute value using @-notation path. 使用 @-表示法路径获取属性值。
  The last segment of the path must start with "@" to indicate an attribute. For example, "users.user.@id" gets the "id" attribute of the "user" element.
  
  路径的最后一段必须以 "@" 开头表示属性。例如，"users.user.@id" 获取 "user" 元素的 "id" 属性。
  
  Parameters:
  
  doc - the XML document | XML 文档
  
  path - the dot-notation path ending with @attrName | 以 @attrName 结尾的点表示法路径
  
  Returns:
  
  the attribute value, or null if not found | 属性值，如果未找到则返回 null
- getElement
  
  public static XmlElement getElement(XmlDocument doc, String path)
  
  Gets the element at the specified path. 获取指定路径处的元素。
  
  Parameters:
  
  doc - the XML document | XML 文档
  
  path - the dot-notation path | 点表示法路径
  
  Returns:
  
  the element, or null if not found | 元素，如果未找到则返回 null
- getElements
  
  public static List<XmlElement> getElements(XmlDocument doc, String path)
  
  Gets all matching elements at the specified path. 获取指定路径处的所有匹配元素。
  The last segment of the path is used to match multiple children. For example, "root.items.item" returns all "item" children under "items".
  
  路径的最后一段用于匹配多个子元素。例如，"root.items.item" 返回 "items" 下的所有 "item" 子元素。
  
  Parameters:
  
  doc - the XML document | XML 文档
  
  path - the dot-notation path | 点表示法路径
  
  Returns:
  
  the list of matching elements | 匹配元素列表
- getStrings
  
  public static List<String> getStrings(XmlDocument doc, String path)
  
  Gets text values of all matching elements at the specified path. 获取指定路径处所有匹配元素的文本值。
  
  Parameters:
  
  doc - the XML document | XML 文档
  
  path - the dot-notation path | 点表示法路径
  
  Returns:
  
  the list of text values | 文本值列表
- exists
  
  public static boolean exists(XmlDocument doc, String path)
  
  Checks whether a path exists in the document. 检查文档中是否存在指定路径。
  
  Parameters:
  
  doc - the XML document | XML 文档
  
  path - the dot-notation path | 点表示法路径
  
  Returns:
  
  true if the path exists | 如果路径存在则返回 true
- set
  
  public static void set(XmlDocument doc, String path, String value)
  
  Sets the value at the specified path, creating intermediate elements as needed. 设置指定路径处的值，根据需要创建中间元素。
  If any intermediate elements do not exist, they will be created automatically.
  
  如果任何中间元素不存在，将自动创建。
  
  Parameters:
  
  doc - the XML document | XML 文档
  
  path - the dot-notation path | 点表示法路径
  
  value - the value to set | 要设置的值

Class XmlPath

Method Summary

Methods inherited from class Object

Method Details

getString

getString

getOptional

getString

getInt

getBoolean

getAttribute

getElement

getElements

getStrings

exists

set