Module java.xml

Package javax.xml.xpath

Interface XPath

       public interface XPath
      

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

XPath表达式的评估

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

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

自版本:

1.5

参见:

• XML路径语言（XPath）版本1.0

Method Summary

Modifier and Type	Method	Description
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)	建立变量解析器。

Method Details

reset

             void reset()
            

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

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

重置的XPath不能保证具有相同的XPathFunctionResolver，XPathVariableResolver或NamespaceContext Objects，例如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可用。如果expression包含任何变量，则将在编译时使用的XPathVariableResolver来解析它们。

参数:

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表达式返回的结果类型。

返回:

作为 returnType 的 Object 评估XPath表达式的结果。

抛出:

XPathExpressionException - 如果无法评估 expression。

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

NullPointerException - 如果 expression 或 returnType 是 null。

evaluate

             String evaluate(String expression, Object item) throws XPathExpressionException
            

在指定的上下文中评估XPath表达式，并将结果作为 String 返回。

此方法调用带有 evaluate(String expression, Object item, QName returnType)，并将 returnType 设置为 XPathConstants.STRING。

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

参数 item 表示XPath表达式将在其上操作的上下文。上下文的类型取决于实现。如果值为 null，则操作不得依赖于上下文，否则将抛出XPathExpressionException。

实现注意事项:

上下文的类型通常是 Node。

参数:

expression - XPath表达式。

item - XPath表达式将在其中进行评估的上下文。

返回:

作为 String 的评估XPath表达式的结果。

抛出:

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 或 returnType 是 null。

evaluate

             String evaluate(String expression, InputSource source) throws XPathExpressionException
            

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

此方法调用带有 evaluate(String expression, InputSource source, QName returnType)，并将 returnType 设置为 XPathConstants.STRING。

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

参数:

expression - XPath表达式。

source - 要在其上评估文档的 InputSource。

返回:

作为 String 的评估表达式结果。

抛出:

XPathExpressionException - 如果无法评估表达式。

NullPointerException - 如果 expression 或 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 或 type 是 null。

自:

9

evaluateExpression

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

在指定的上下文中评估XPath表达式。这相当于调用 evaluateExpression(String expression, Object item, Class type)，并将类型设置为 XPathEvaluationResult:

 
     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或type为null。

自版本:

9

evaluateExpression

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

在指定的上下文中评估XPath表达式。这等同于调用evaluateExpression(String expression, Object item, Class type)，类型为XPathEvaluationResult:

 
     evaluateExpression(expression, item, XPathEvaluationResult.class);
 

实现要求:

XPath API中的默认实现等同于:

 
     evaluateExpression(expression, source, XPathEvaluationResult.class);
 

由于evaluate方法不支持ANY类型，因此该方法的默认实现将始终抛出IllegalArgumentException异常。因此，任何支持ANY类型的实现必须重写此方法。

参数:

expression - XPath表达式。

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

返回:

评估表达式的结果。

抛出:

XPathExpressionException - 如果无法评估表达式。

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

NullPointerException - 如果expression或source为null。

自版本:

9