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 具有相同的 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。

返回：

當前的 Namespace 上下文。

compile

XPathExpression compile(String expression)
                        throws XPathExpressionException

編譯 XPath 表達式供以後計算使用。

如果 expression 套件含任何 XPathFunction，則它們必須可以通過 XPathFunctionResolver 獲取。如果不能通過 XPathFunctionResolver 解析 XPathFunction，則將拋出 XPathExpressionException。

如果 expression 套件含任何變數，則將使用在編譯時有效的 XPathVariableResolver 來解析這些變數。

如果 expression 為 null，則拋出 NullPointerException。

參數：

expression - XPath 表達式。

返回：

編譯後的 XPath 表達式。

拋出：

XPathExpressionException - 如果不能編譯 expression。

NullPointerException - 如果 expression 為 null。

evaluate

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

計算指定上下文中的 XPath 表達式並返回指定型別的結果。

有關上下文項計算、變數、函數和 QName 解析，以及返回型別轉換，請參閱 Evaluation of XPath Expressions。

如果 returnType 不是 XPathConstants (NUMBER、STRING、BOOLEAN、NODE 或 NODESET) 中定義的某種型別，則拋出 IllegalArgumentException。

如果 item 為 null 值，則將使用一個空文檔作為上下文。如果 expression 或 returnType 為 null，則拋出 NullPointerException。

參數：

expression - XPath 表達式。

item - 開始上下文（例如節點）。

returnType - 所需的返回型別。

返回：

以 returnType 的 Object 形式返回 XPath 表達式的計算結果。

拋出：

XPathExpressionException - 如果不能計算 expression。

IllegalArgumentException - 如果 returnType 不是 XPathConstants 中定義的型別之一。

NullPointerException - 如果 expression 或 returnType 為 null。

evaluate

String evaluate(String expression,
                Object item)
                throws XPathExpressionException

計算指定上下文中的 XPath 表達式並返回 String 形式的結果。

此方法通過 XPathConstants.STRING 的 returnType 調用 evaluate(String expression, Object item, QName returnType)。

有關上下文項計算、變數、函數和 QName 解析，以及返回型別轉換，請參閱 Evaluation of XPath Expressions。

如果為 item 為 null 值，則將使用一個空文檔作為上下文。如果 expression 為 null，則拋出 NullPointerException。

參數：

expression - XPath 表達式。

item - 開始上下文（例如節點）。

返回：

計算表達式並將計算結果轉換為 String 所得到的結果 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 解析，以及返回型別轉換，請參閱 Evaluation of XPath Expressions。

如果 returnType 不是 XPathConstants 中定義的型別之一，則拋出 IllegalArgumentException。

如果 expression、source 或 returnType 為 null，則拋出 NullPointerException。

參數：

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 形式的結果。

此方法通過 XPathConstants.STRING 的 returnType 調用 evaluate(String expression, InputSource source, QName returnType)。

有關上下文項計算、變數、函數和 QName 解析，以及返回型別轉換，請參閱 Evaluation of XPath Expressions。

如果 expression 或 source 為 null，則拋出 NullPointerException。

參數：

expression - XPath 表達式。

source - 要對其計算的文檔的 InputSource。

返回：

計算表達式並將計算結果轉換為 String 所得到的結果 String。

拋出：

XPathExpressionException - 如果不能計算表達式。

NullPointerException - 如果 expression 或 source 為 null。