/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ // $Id: XPath.java 569998 2007-08-27 04:40:02Z mrglavas $ package javax.xml.xpath; import javax.xml.namespace.NamespaceContext; import javax.xml.namespace.QName; import org.xml.sax.InputSource; /** *

XPath provides access to the XPath evaluation environment and expressions.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Evaluation of XPath Expressions.
context * If a request is made to evaluate the expression in the absence * of a context item, an empty document node will be used for the context. * For the purposes of evaluating XPath expressions, a DocumentFragment * is treated like a Document node. *
variables * If the expression contains a variable reference, its value will be found through the {@link XPathVariableResolver} * set with {@link #setXPathVariableResolver(XPathVariableResolver resolver)}. * An {@link XPathExpressionException} is raised if the variable resolver is undefined or * the resolver returns null for the variable. * The value of a variable must be immutable through the course of any single evaluation.

*
functions * If the expression contains a function reference, the function will be found through the {@link XPathFunctionResolver} * set with {@link #setXPathFunctionResolver(XPathFunctionResolver resolver)}. * An {@link XPathExpressionException} is raised if the function resolver is undefined or * the function resolver returns null for the function.

*
QNames * QNames in the expression are resolved against the XPath namespace context * set with {@link #setNamespaceContext(NamespaceContext nsContext)}. *
result * This result of evaluating an expression is converted to an instance of the desired return type. * Valid return types are defined in {@link XPathConstants}. * Conversion to the return type follows XPath conversion rules.

*
* * @author Norman Walsh * @author Jeff Suttor * @version $Revision: 569998 $, $Date: 2007-08-26 21:40:02 -0700 (Sun, 26 Aug 2007) $ * @see XML Path Language (XPath) Version 1.0 * @since 1.5 */ public interface XPath { /** *

Reset this XPath to its original configuration.

* *

XPath is reset to the same state as when it was created with * {@link XPathFactory#newXPath()}. * reset() is designed to allow the reuse of existing XPaths * thus saving resources associated with the creation of new XPaths.

* *

The reset XPath is not guaranteed to have the same {@link XPathFunctionResolver}, {@link XPathVariableResolver} * or {@link NamespaceContext} Objects, e.g. {@link Object#equals(Object obj)}. * It is guaranteed to have a functionally equal XPathFunctionResolver, XPathVariableResolver * and NamespaceContext.

*/ public void reset(); /** *

Establish a variable resolver.

* *

A NullPointerException is thrown if resolver is null.

* * @param resolver Variable resolver. * * @throws NullPointerException If resolver is null. */ public void setXPathVariableResolver(XPathVariableResolver resolver); /** *

Return the current variable resolver.

* *

null is returned in no variable resolver is in effect.

* * @return Current variable resolver. */ public XPathVariableResolver getXPathVariableResolver(); /** *

Establish a function resolver.

* *

A NullPointerException is thrown if resolver is null.

* * @param resolver XPath function resolver. * * @throws NullPointerException If resolver is null. */ public void setXPathFunctionResolver(XPathFunctionResolver resolver); /** *

Return the current function resolver.

* *

null is returned in no function resolver is in effect.

* * @return Current function resolver. */ public XPathFunctionResolver getXPathFunctionResolver(); /** *

Establish a namespace context.

* *

A NullPointerException is thrown if nsContext is null.

* * @param nsContext Namespace context to use. * * @throws NullPointerException If nsContext is null. */ public void setNamespaceContext(NamespaceContext nsContext); /** *

Return the current namespace context.

* *

null is returned in no namespace context is in effect.

* * @return Current Namespace context. */ public NamespaceContext getNamespaceContext(); /** *

Compile an XPath expression for later evaluation.

* *

If expression contains any {@link XPathFunction}s, * they must be available via the {@link XPathFunctionResolver}. * An {@link XPathExpressionException} will be thrown if the XPathFunction * cannot be resolved with the XPathFunctionResolver.

* *

If expression is null, a NullPointerException is thrown.

* * @param expression The XPath expression. * * @return Compiled XPath expression. * @throws XPathExpressionException If expression cannot be compiled. * @throws NullPointerException If expression is null. */ public XPathExpression compile(String expression) throws XPathExpressionException; /** *

Evaluate an XPath expression in the specified context and return the result as the specified type.

* *

See Evaluation of XPath Expressions for context item evaluation, * variable, function and QName resolution and return type conversion.

* *

If returnType is not one of the types defined in {@link XPathConstants} ( * {@link XPathConstants#NUMBER NUMBER}, * {@link XPathConstants#STRING STRING}, * {@link XPathConstants#BOOLEAN BOOLEAN}, * {@link XPathConstants#NODE NODE} or * {@link XPathConstants#NODESET NODESET}) * then an IllegalArgumentException is thrown.

* *

If a null value is provided for * item, an empty document will be used for the * context. * If expression or returnType is null, then a * NullPointerException is thrown.

* * @param expression The XPath expression. * @param item The starting context (node or node list, for example). * @param returnType The desired return type. * * @return Result of evaluating an XPath expression as an Object of returnType. * * @throws XPathExpressionException If expression cannot be evaluated. * @throws IllegalArgumentException If returnType is not one of the types defined in {@link XPathConstants}. * @throws NullPointerException If expression or returnType is null. */ public Object evaluate(String expression, Object item, QName returnType) throws XPathExpressionException; /** *

Evaluate an XPath expression in the specified context and return the result as a String.

* *

This method calls {@link #evaluate(String expression, Object item, QName returnType)} with a returnType of * {@link XPathConstants#STRING}.

* *

See Evaluation of XPath Expressions for context item evaluation, * variable, function and QName resolution and return type conversion.

* *

If a null value is provided for * item, an empty document will be used for the * context. * If expression is null, then a NullPointerException is thrown.

* * @param expression The XPath expression. * @param item The starting context (node or node list, for example). * * @return The String that is the result of evaluating the expression and * converting the result to a String. * * @throws XPathExpressionException If expression cannot be evaluated. * @throws NullPointerException If expression is null. */ public String evaluate(String expression, Object item) throws XPathExpressionException; /** *

Evaluate an XPath expression in the context of the specified InputSource * and return the result as the specified type.

* *

This method builds a data model for the {@link InputSource} and calls * {@link #evaluate(String expression, Object item, QName returnType)} on the resulting document object.

* *

See Evaluation of XPath Expressions for context item evaluation, * variable, function and QName resolution and return type conversion.

* *

If returnType is not one of the types defined in {@link XPathConstants}, * then an IllegalArgumentException is thrown.

* *

If expression, source or returnType is null, * then a NullPointerException is thrown.

* * @param expression The XPath expression. * @param source The input source of the document to evaluate over. * @param returnType The desired return type. * * @return The Object that encapsulates the result of evaluating the expression. * * @throws XPathExpressionException If expression cannot be evaluated. * @throws IllegalArgumentException If returnType is not one of the types defined in {@link XPathConstants}. * @throws NullPointerException If expression, source or returnType * is null. */ public Object evaluate( String expression, InputSource source, QName returnType) throws XPathExpressionException; /** *

Evaluate an XPath expression in the context of the specified InputSource * and return the result as a String.

* *

This method calls {@link #evaluate(String expression, InputSource source, QName returnType)} with a * returnType of {@link XPathConstants#STRING}.

* *

See Evaluation of XPath Expressions for context item evaluation, * variable, function and QName resolution and return type conversion.

* *

If expression or source is null, * then a NullPointerException is thrown.

* * @param expression The XPath expression. * @param source The InputSource of the document to evaluate over. * * @return The String that is the result of evaluating the expression and * converting the result to a String. * * @throws XPathExpressionException If expression cannot be evaluated. * @throws NullPointerException If expression or source is null. */ public String evaluate(String expression, InputSource source) throws XPathExpressionException; }