Class XPathQuery

java.lang.Object
cloud.opencode.base.xml.xpath.XPathQuery
public final class XPathQuery extends Object
XPath Query - Builder for complex XPath queries XPath 查询 - 复杂 XPath 查询的构建器

This class provides a fluent interface for building and executing XPath queries with support for namespaces and variables.

此类提供流式接口，用于构建和执行支持命名空间和变量的 XPath 查询。

Usage Examples | 使用示例:

// Simple query
String name = XPathQuery.create()
    .xml("<root><name>John</name></root>")
    .selectString("//name/text()");

// Query with namespace
String value = XPathQuery.create()
    .xml(nsXml)
    .namespace("ns", "http://example.com")
    .selectString("//ns:item/text()");

// Query with variables
String result = XPathQuery.create()
    .xml(xml)
    .variable("userId", "123")
    .selectString("//user[@id=$userId]/name");

Features | 主要功能:

  • Fluent builder for complex XPath queries - 复杂 XPath 查询的流式构建器
  • Namespace and variable support - 命名空间和变量支持
  • Multiple result type selection (string, number, node list) - 多种结果类型选择（字符串、数字、节点列表）

Security | 安全性:

  • Thread-safe: No (mutable builder) - 线程安全: 否（可变构建器）
  • Null-safe: No (throws on null XML/expression) - 空值安全: 否（null XML/表达式抛异常）
Since:
JDK 25, opencode-base-xml V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static XPathQuery create()
      Creates a new XPath query. 创建新的 XPath 查询。
      Returns:
      the query object | 查询对象

    • xml

      public XPathQuery xml(String xml)
      Sets the XML to query. 设置要查询的 XML。
      Parameters:
      xml - the XML string | XML 字符串
      Returns:
      this query for chaining | 此查询以便链式调用

    • document

      public XPathQuery document(Document document)
      Sets the Document to query. 设置要查询的 Document。
      Parameters:
      document - the Document | Document
      Returns:
      this query for chaining | 此查询以便链式调用

    • namespace

      public XPathQuery namespace(String prefix, String namespaceUri)
      Adds a namespace binding. 添加命名空间绑定。
      Parameters:
      prefix - the namespace prefix | 命名空间前缀
      namespaceUri - the namespace URI | 命名空间 URI
      Returns:
      this query for chaining | 此查询以便链式调用

    • namespaces

      public XPathQuery namespaces(Map<String,String> namespaces)
      Adds multiple namespace bindings. 添加多个命名空间绑定。
      Parameters:
      namespaces - the namespace map (prefix -> URI) | 命名空间映射（前缀 -> URI）
      Returns:
      this query for chaining | 此查询以便链式调用

    • variable

      public XPathQuery variable(String name, Object value)
      Adds a variable binding. 添加变量绑定。
      Parameters:
      name - the variable name | 变量名
      value - the variable value | 变量值
      Returns:
      this query for chaining | 此查询以便链式调用

    • selectString

      public String selectString(String xpath)
      Selects a string value. 选择字符串值。
      Parameters:
      xpath - the XPath expression | XPath 表达式
      Returns:
      the result string | 结果字符串

    • selectNumber

      public Number selectNumber(String xpath)
      Selects a number value. 选择数字值。
      Parameters:
      xpath - the XPath expression | XPath 表达式
      Returns:
      the result number | 结果数字

    • selectBoolean

      public Boolean selectBoolean(String xpath)
      Selects a boolean value. 选择布尔值。
      Parameters:
      xpath - the XPath expression | XPath 表达式
      Returns:
      the result boolean | 结果布尔值

    • selectElement

      public XmlElement selectElement(String xpath)
      Selects a single element. 选择单个元素。
      Parameters:
      xpath - the XPath expression | XPath 表达式
      Returns:
      the element, or null if not found | 元素，如果未找到则返回 null

    • selectElements

      public List<XmlElement> selectElements(String xpath)
      Selects multiple elements. 选择多个元素。
      Parameters:
      xpath - the XPath expression | XPath 表达式
      Returns:
      the list of elements | 元素列表

    • selectValues

      public List<String> selectValues(String xpath)
      Selects string values. 选择字符串值列表。
      Parameters:
      xpath - the XPath expression | XPath 表达式
      Returns:
      the list of strings | 字符串列表