/* * 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: XPathExpression.java 446598 2006-09-15 12:55:40Z jeremias $ package javax.xml.xpath; import javax.xml.namespace.QName; import org.xml.sax.InputSource; /** *

XPathExpression provides access to compiled XPath 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}. * 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}. * 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. *
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: 446598 $, $Date: 2006-09-15 05:55:40 -0700 (Fri, 15 Sep 2006) $ * @see XML Path Language (XPath) Version 1.0, Expressions * @since 1.5 */ public interface XPathExpression { /** *

Evaluate the compiled 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}, * then an IllegalArgumentException is thrown.

* *

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

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

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

* *

This method calls {@link #evaluate(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. * * @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 the expression cannot be evaluated. */ public String evaluate(Object item) throws XPathExpressionException; /** *

Evaluate the compiled 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(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 source or returnType is null, * then a NullPointerException is thrown.

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

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

* *

This method calls {@link #evaluate(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 source is null, then a NullPointerException is thrown.

* * @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 the expression cannot be evaluated. * @throws NullPointerException If source is null. */ public String evaluate(InputSource source) throws XPathExpressionException; }