JavaTM Platform
Standard Ed. 6

javax.xml.xpath
接口 XPath


public interface XPath

XPath 提供了对 XPath 计算环境和表达式的访问。

XPath 表达式的计算。
上下文 如果在没有上下文项的情况下请求计算表达式,则将使用一个空文档节点作为上下文。为计算 XPath 表达式,应将 DocumentFragment 视为 Document 节点。
变量 如果表达式包含变量引用,则其值将通过 XPathVariableResolver 找到,其中 XPathVariableResolver 是通过 setXPathVariableResolver(XPathVariableResolver resolver) 设置的。如果变量解析器未定义或解析器对变量返回 null,则引发 XPathExpressionException。在任何单个计算过程中,变量的值必须是不可变的。

函数 如果表达式包含函数引用,则函数将通过 XPathFunctionResolver 找到,其中 XPathFunctionResolver 是通过 setXPathFunctionResolver(XPathFunctionResolver resolver) 设置的。如果函数解析器未定义或解析器为函数返回 null,则引发 XPathExpressionException

QNames 表达式中的 QNames 根据通过 setNamespaceContext(NamespaceContext nsContext) 设置的 XPath 名称空间上下文来解析。
结果 将计算表达式的结果转换为所需的返回类型的实例。XPathConstants 中定义了有效的返回类型。到返回类型的转换遵守 XPath 转换规则。

XPath 对象不是线程安全的,也不能重入。换句话说,应用程序负责确保在任意给定时刻不能有多个线程使用一个 XPath 对象,且当调用 evaluate 方法时,应用程序不能以递归方式调用 evaluate 方法。

从以下版本开始:
1.5
另请参见:
XML Path Language (XPath) Version 1.0

方法摘要
 XPathExpression compile(String expression)
          编译 XPath 表达式供以后计算使用。
 String evaluate(String expression, InputSource source)
          计算指定 InputSource 上下文中的 XPath 表达式并返回 String 形式的结果。
 Object evaluate(String expression, InputSource source, QName returnType)
          计算指定 InputSource 上下文中的 XPath 表达式并返回指定类型的结果。
 String evaluate(String expression, Object item)
          计算指定上下文中的 XPath 表达式并返回 String 形式的结果。
 Object evaluate(String expression, Object item, QName returnType)
          计算指定上下文中的 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,从而节省与创建新 XPath 相关的资源。

不保证重置的 XPath 具有相同的 XPathFunctionResolverXPathVariableResolverNamespaceContext Object,例如 Object.equals(Object obj)。但保证具有功能相同的 XPathFunctionResolverXPathVariableResolverNamespaceContext


setXPathVariableResolver

void setXPathVariableResolver(XPathVariableResolver resolver)

建立变量解析器。

如果 resolvernull,则抛出 NullPointerException

参数:
resolver - 变量解析器。
抛出:
NullPointerException - 如果 resolvernull

getXPathVariableResolver

XPathVariableResolver getXPathVariableResolver()

返回当前的变量解析器。

如果不存在有效的变量解析器,则返回 null

返回:
当前的变量解析器。

setXPathFunctionResolver

void setXPathFunctionResolver(XPathFunctionResolver resolver)

建立函数解析器。

如果 resolvernull,则抛出 NullPointerException

参数:
resolver - XPath 函数解析器。
抛出:
NullPointerException - 如果 resolvernull

getXPathFunctionResolver

XPathFunctionResolver getXPathFunctionResolver()

返回当前的函数解析器。

如果不存在有效的变量解析器,则返回 null

返回:
当前的函数解析器。

setNamespaceContext

void setNamespaceContext(NamespaceContext nsContext)

建立名称空间上下文。

如果 nsContextnull,则抛出 NullPointerException

参数:
nsContext - 要使用的名称空间上下文。
抛出:
NullPointerException - 如果 nsContextnull

getNamespaceContext

NamespaceContext getNamespaceContext()

返回当前的名称空间上下文。

如果不存在有效的名称空间上下文,则返回 null

返回:
当前的 Namespace 上下文。

compile

XPathExpression compile(String expression)
                        throws XPathExpressionException

编译 XPath 表达式供以后计算使用。

如果 expression 包含任何 XPathFunction,则它们必须可以通过 XPathFunctionResolver 获取。如果不能通过 XPathFunctionResolver 解析 XPathFunction,则将抛出 XPathExpressionException

如果 expression 包含任何变量,则将使用在编译时有效的 XPathVariableResolver 来解析这些变量。

如果 expressionnull,则抛出 NullPointerException

参数:
expression - XPath 表达式。
返回:
编译后的 XPath 表达式。
抛出:
XPathExpressionException - 如果不能编译 expression
NullPointerException - 如果 expressionnull

evaluate

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

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

有关上下文项计算、变量、函数和 QName 解析,以及返回类型转换,请参阅 Evaluation of XPath Expressions

如果 returnType 不是 XPathConstants (NUMBERSTRINGBOOLEANNODENODESET) 中定义的某种类型,则抛出 IllegalArgumentException

如果 itemnull 值,则将使用一个空文档作为上下文。如果 expressionreturnTypenull,则抛出 NullPointerException

参数:
expression - XPath 表达式。
item - 开始上下文(例如节点)。
returnType - 所需的返回类型。
返回:
returnTypeObject 形式返回 XPath 表达式的计算结果。
抛出:
XPathExpressionException - 如果不能计算 expression
IllegalArgumentException - 如果 returnType 不是 XPathConstants 中定义的类型之一。
NullPointerException - 如果 expressionreturnTypenull

evaluate

String evaluate(String expression,
                Object item)
                throws XPathExpressionException

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

此方法通过 XPathConstants.STRINGreturnType 调用 evaluate(String expression, Object item, QName returnType)

有关上下文项计算、变量、函数和 QName 解析,以及返回类型转换,请参阅 Evaluation of XPath Expressions

如果为 itemnull 值,则将使用一个空文档作为上下文。如果 expressionnull,则抛出 NullPointerException

参数:
expression - XPath 表达式。
item - 开始上下文(例如节点)。
返回:
计算表达式并将计算结果转换为 String 所得到的结果 String
抛出:
XPathExpressionException - 如果不能计算 expression
NullPointerException - 如果 expressionnull

evaluate

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

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

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

有关上下文项计算、变量、函数和 QName 解析,以及返回类型转换,请参阅 Evaluation of XPath Expressions

如果 returnType 不是 XPathConstants 中定义的类型之一,则抛出 IllegalArgumentException

如果 expressionsourcereturnTypenull,则抛出 NullPointerException

参数:
expression - XPath 表达式。
source - 要对其计算的文档的输入源。
returnType - 所需的返回类型。
返回:
封装了表达式计算结果的 Object
抛出:
XPathExpressionException - 如果不能计算表达式。
IllegalArgumentException - 如果 returnType 不是 XPathConstants 中定义的类型之一。
NullPointerException - 如果 expressionsourcereturnTypenull

evaluate

String evaluate(String expression,
                InputSource source)
                throws XPathExpressionException

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

此方法通过 XPathConstants.STRINGreturnType 调用 evaluate(String expression, InputSource source, QName returnType)

有关上下文项计算、变量、函数和 QName 解析,以及返回类型转换,请参阅 Evaluation of XPath Expressions

如果 expressionsourcenull,则抛出 NullPointerException

参数:
expression - XPath 表达式。
source - 要对其计算的文档的 InputSource
返回:
计算表达式并将计算结果转换为 String 所得到的结果 String
抛出:
XPathExpressionException - 如果不能计算表达式。
NullPointerException - 如果 expressionsourcenull

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策