模块 java.xml

包 javax.xml.xpath

接口 XPath

public interface XPath
      

XPath 提供对 XPath 评估环境和表达式的访问。 XPath 评估受下表中描述的因素影响。

XPath 表达式的评估

因素	行为
context	上下文的类型是依赖于实现的。如果值为 null，则操作必须不依赖于上下文，否则将抛出 XPathExpressionException。为了评估 XPath 表达式，将 DocumentFragment 视为文档节点。
变量	如果表达式包含变量引用，将通过 XPathVariableResolver 和 setXPathVariableResolver(XPathVariableResolver resolver) 集找到它的值。如果变量解析器未定义或解析器为变量返回 null，则会引发 XPathExpressionException 。在任何单个评估过程中，变量的值必须是不可变的。
功能	如果表达式包含函数引用，将通过 XPathFunctionResolver 和 setXPathFunctionResolver(XPathFunctionResolver resolver) 集找到该函数。如果函数解析器未定义或函数解析器为函数返回 null，则会引发 XPathExpressionException 。
QNames	表达式中的 QName 是根据用 setNamespaceContext(NamespaceContext nsContext) 设置的 XPath 命名空间上下文解析的。
结果	计算表达式的结果将转换为所需返回类型的实例。 XPathConstants 中定义了有效的返回类型。转换为返回类型遵循 XPath 转换规则。

XPath 对象不是线程安全的，也不是可重入的。换句话说，应用程序有责任确保在任何给定时间不从多个线程使用一个 XPath 对象，并且在调用 evaluate 方法时，应用程序不得递归调用 evaluate 方法。

自从：

1.5

参见：

• XML 路径语言 (XPath) 1.0 版

方法总结

修饰符和类型	方法	描述
XPathExpression	compile(String expression)	编译 XPath 表达式以供以后评估。
String	evaluate(String expression, Object item)	在指定上下文中计算 XPath 表达式并将结果作为 String 返回。
Object	evaluate(String expression, Object item, QName returnType)	在指定上下文中计算 XPath 表达式并将结果作为指定类型返回。
String	evaluate(String expression, InputSource source)	在指定的 InputSource 上下文中计算 XPath 表达式并将结果作为 String 返回。
Object	evaluate(String expression, InputSource source, QName returnType)	在指定 InputSource 的上下文中计算 XPath 表达式，并将结果作为指定类型返回。
default XPathEvaluationResult<?>	evaluateExpression(String expression, Object item)	在指定上下文中计算 XPath 表达式。
default <T> T	evaluateExpression(String expression, Object item, Class<T> type)	在指定的上下文中计算 XPath 表达式并返回具有通过 class type 指定的类型的结果
default XPathEvaluationResult<?>	evaluateExpression(String expression, InputSource source)	在指定上下文中计算 XPath 表达式。
default <T> T	evaluateExpression(String expression, InputSource source, Class<T> type)	在指定的 source 的上下文中计算 XPath 表达式并返回指定的结果。
NamespaceContext	getNamespaceContext()	返回当前命名空间上下文。
XPathFunctionResolver	getXPathFunctionResolver()	返回当前函数解析器。
XPathVariableResolver	getXPathVariableResolver()	返回当前变量解析器。
void	reset()	将此 XPath 重置为其原始配置。
void	setNamespaceContext(NamespaceContext nsContext)	建立命名空间上下文。
void	setXPathFunctionResolver(XPathFunctionResolver resolver)	建立功能解析器。
void	setXPathVariableResolver(XPathVariableResolver resolver)	建立变量解析器。

方法详情

reset

void reset()
            

将此 XPath 重置为其原始配置。

XPath 重置为与使用 XPathFactory.newXPath() 创建时相同的状态。 reset() 旨在允许重用现有的 XPath s，从而节省与创建新的 XPath s 相关的资源。

不能保证重置 XPath 具有相同的 XPathFunctionResolver 、XPathVariableResolver 或 NamespaceContext Object，例如 Object.equals(Object obj) 。它保证具有功能相同的 XPathFunctionResolver 、 XPathVariableResolver 和 NamespaceContext 。

setXPathVariableResolver

void setXPathVariableResolver(XPathVariableResolver  resolver)
            

建立变量解析器。

如果 resolver 是 null 则抛出 NullPointerException。

参数：

resolver - 变量解析器。

抛出：

NullPointerException - 如果 resolver 是 null。

getXPathVariableResolver

XPathVariableResolver  getXPathVariableResolver()
            

返回当前变量解析器。

null 在没有变量解析器生效时返回。

返回：

当前变量解析器。

setXPathFunctionResolver

void setXPathFunctionResolver(XPathFunctionResolver  resolver)
            

建立功能解析器。

如果 resolver 是 null 则抛出 NullPointerException。

参数：

resolver - XPath 函数解析器。

抛出：

NullPointerException - 如果 resolver 是 null。

getXPathFunctionResolver

XPathFunctionResolver  getXPathFunctionResolver()
            

返回当前函数解析器。

null 在没有函数解析器生效时返回。

返回：

当前功能解析器。

setNamespaceContext

void setNamespaceContext(NamespaceContext  nsContext)
            

建立命名空间上下文。

如果 nsContext 是 null 则抛出 NullPointerException。

参数：

nsContext - 要使用的命名空间上下文。

抛出：

NullPointerException - 如果 nsContext 是 null。

getNamespaceContext

NamespaceContext  getNamespaceContext()
            

返回当前命名空间上下文。

null 在没有有效的命名空间上下文中返回。

返回：

当前命名空间上下文。

compile

XPathExpression  compile(String  expression) throws XPathExpressionException 
            

编译 XPath 表达式以供以后评估。

如果 expression 包含任何 XPathFunction ，则它们必须通过 XPathFunctionResolver 可用。如果 XPathFunction 不能用 XPathFunctionResolver 解决，将抛出 XPathExpressionException 。

如果 expression 包含任何变量，则 XPathVariableResolver 实际上 at compile time 将用于解析它们。

参数：

expression - XPath 表达式。

返回：

已编译的 XPath 表达式。

抛出：

XPathExpressionException - 如果无法编译 expression。

NullPointerException - 如果 expression 是 null。

evaluate

Object  evaluate(String  expression, Object  item, QName  returnType) throws XPathExpressionException 
            

在指定上下文中计算 XPath 表达式并将结果作为指定类型返回。

有关上下文项评估、变量、函数和 QName 解析和返回类型转换的信息，请参见 XPath 表达式的评估。

参数 item 代表 XPath 表达式将被操作的上下文。上下文的类型是依赖于实现的。如果值为 null ，则操作必须不依赖于上下文，否则将抛出 XPathExpressionException。

实现注意事项：

上下文的类型通常是 Node 。

参数：

expression - XPath 表达式。

item - 将在其中计算 XPath 表达式的上下文。

returnType - XPath 表达式预期返回的结果类型。

返回：

将 XPath 表达式计算为 returnType 的 Object 的结果。

抛出：

XPathExpressionException - 如果无法评估 expression。

IllegalArgumentException - 如果 returnType 不是 XPathConstants 中定义的类型之一（NUMBER 、STRING 、BOOLEAN 、NODE 或 NODESET ）。

NullPointerException - 如果 expression or returnType 是 null。

evaluate

String  evaluate(String  expression, Object  item) throws XPathExpressionException 
            

在指定上下文中计算 XPath 表达式并将结果作为 String 返回。

此方法使用 XPathConstants.STRING 的 returnType 调用 evaluate(String expression, Object item, QName returnType) 。

有关上下文项评估、变量、函数和 QName 解析以及返回类型转换，请参阅 XPath 表达式的评估。

参数 item 代表 XPath 表达式将被操作的上下文。上下文的类型是依赖于实现的。如果值为 null ，则操作必须不依赖于上下文，否则将抛出 XPathExpressionException。

实现注意事项：

上下文的类型通常是 Node 。

参数：

expression - XPath 表达式。

item - 将在其中计算 XPath 表达式的上下文。

返回：

将 XPath 表达式计算为 String 的结果。

抛出：

XPathExpressionException - 如果无法评估 expression。

NullPointerException - 如果 expression 是 null。

evaluate

Object  evaluate(String  expression, InputSource  source, QName  returnType) throws XPathExpressionException 
            

在指定 InputSource 的上下文中计算 XPath 表达式，并将结果作为指定类型返回。

此方法为 InputSource 构建数据模型并在生成的文档对象上调用 evaluate(String expression, Object item, QName returnType) 。

有关上下文项评估、变量、函数和 QName 解析以及返回类型转换，请参阅 XPath 表达式的评估。

参数：

expression - XPath 表达式。

source - 要评估的文档的输入源。

returnType - 所需的返回类型。

返回：

封装表达式计算结果的 Object。

抛出：

XPathExpressionException - 如果无法计算表达式。

IllegalArgumentException - 如果 returnType 不是 XPathConstants 中定义的类型之一。

NullPointerException - 如果 expression, source or returnType 是 null。

evaluate

String  evaluate(String  expression, InputSource  source) throws XPathExpressionException 
            

在指定的 InputSource 上下文中计算 XPath 表达式并将结果作为 String 返回。

此方法使用 XPathConstants.STRING 的 returnType 调用 evaluate(String expression, InputSource source, QName returnType) 。

有关上下文项评估、变量、函数和 QName 解析以及返回类型转换，请参阅 XPath 表达式的评估。

参数：

expression - XPath 表达式。

source - 要评估的文档的 InputSource。

返回：

String 是计算表达式并将结果转换为 String 的结果。

抛出：

XPathExpressionException - 如果无法计算表达式。

NullPointerException - 如果 expression or source 是 null。

evaluateExpression

default <T> T evaluateExpression(String  expression, Object  item, Class <T> type) throws XPathExpressionException 
            

在指定的上下文中计算 XPath 表达式并返回具有通过 class type 指定的类型的结果

参数 item 代表 XPath 表达式将被操作的上下文。上下文的类型是依赖于实现的。如果值为 null ，则操作必须不依赖于上下文，否则将抛出 XPathExpressionException。

实现要求：

XPath API 中的默认实现等效于：

 
   (T)evaluate(expression, item,
      XPathEvaluationResult.XPathResultType.getQNameType(type));
  

由于 evaluate 方法不支持 ANY 类型，因此将 XPathEvaluationResult 指定为类型将导致 IllegalArgumentException。任何支持 ANY 类型的实现都必须覆盖此方法。

实现注意事项：

上下文的类型通常是 Node 。

类型参数：

T - XPath 表达式将返回的类类型。

参数：

expression - XPath 表达式。

item - 将在其中计算 XPath 表达式的上下文。

type - XPath 表达式预期返回的类类型必须是包摘要中 3.2 类类型 部分中描述的类型之一。

返回：

计算表达式的结果。

抛出：

XPathExpressionException - 如果无法计算表达式。

IllegalArgumentException - 如果 type 不是与 XPathEvaluationResult.XPathResultType 中定义的类型相对应的类型，或者 XPathEvaluationResult 被指定为该类型但支持 ANY 类型的实现不可用。

NullPointerException - 如果 expression or type 是 null。

自从：

9

evaluateExpression

default XPathEvaluationResult <?> evaluateExpression(String  expression, Object  item) throws XPathExpressionException 
            

在指定上下文中计算 XPath 表达式。这相当于调用类型为 XPathEvaluationResult 的 evaluateExpression(String expression, Object item, Class type) :

 
   evaluateExpression(expression, item, XPathEvaluationResult.class);
  

参数 item 代表 XPath 表达式将被操作的上下文。上下文的类型是依赖于实现的。如果值为 null ，则操作必须不依赖于上下文，否则将抛出 XPathExpressionException。

实现要求：

XPath API 中的默认实现等效于：

 
   evaluateExpression(expression, item, XPathEvaluationResult.class);
  

由于 evaluate 方法不支持 ANY 类型，因此此方法的默认实现将始终抛出 IllegalArgumentException。因此，任何支持 ANY 类型的实现都必须覆盖此方法。

实现注意事项：

上下文的类型通常是 Node 。

参数：

expression - XPath 表达式。

item - 将在其中计算 XPath 表达式的上下文。

返回：

计算表达式的结果。

抛出：

XPathExpressionException - 如果无法计算表达式。

IllegalArgumentException - 如果此方法的实现不支持 ANY 类型。

NullPointerException - 如果 expression 是 null。

自从：

9

evaluateExpression

default <T> T evaluateExpression(String  expression, InputSource  source, Class <T> type) throws XPathExpressionException 
            

在指定的 source 的上下文中计算 XPath 表达式并返回指定的结果。

此方法为 InputSource 构建数据模型并在生成的文档对象上调用 evaluateExpression(String expression, Object item, Class type) 。数据模型通常是Document

实现要求：

XPath API 中的默认实现等效于：

 
      (T)evaluate(expression, source,
        XPathEvaluationResult.XPathResultType.getQNameType(type));
  

由于 evaluate 方法不支持 ANY 类型，因此将 XPathEvaluationResult 指定为类型将导致 IllegalArgumentException。任何支持 ANY 类型的实现都必须覆盖此方法。

类型参数：

T - XPath 表达式将返回的类类型。

参数：

expression - XPath 表达式。

source - 要评估的文档的输入源。

type - XPath 表达式预期返回的类类型必须是包摘要中 3.2 类类型 部分中描述的类型之一。

返回：

计算表达式的结果。

抛出：

XPathExpressionException - 如果无法计算表达式。

IllegalArgumentException - 如果 type 不是与 XPathResultType 中定义的类型相对应的类型，或者 XPathEvaluationResult 被指定为该类型但支持 ANY 类型的实现不可用。

NullPointerException - 如果 expression, source or type 是 null。

自从：

9

evaluateExpression

default XPathEvaluationResult <?> evaluateExpression(String  expression, InputSource  source) throws XPathExpressionException 
            

在指定上下文中计算 XPath 表达式。这相当于调用类型为 XPathEvaluationResult 的 evaluateExpression(String expression, Object item, Class type) :

 
   evaluateExpression(expression, item, XPathEvaluationResult.class);
  

实现要求：

XPath API 中的默认实现等效于：

 
   evaluateExpression(expression, source, XPathEvaluationResult.class);
  

由于 evaluate 方法不支持 ANY 类型，因此此方法的默认实现将始终抛出 IllegalArgumentException。因此，任何支持 ANY 类型的实现都必须覆盖此方法。

参数：

expression - XPath 表达式。

source - 要评估的文档的输入源。

返回：

计算表达式的结果。

抛出：

XPathExpressionException - 如果无法计算表达式。

IllegalArgumentException - 如果此方法的实现不支持 ANY 类型。

NullPointerException - 如果 expression or source 是 null。

自从：

9