1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 // $Id: XPathExpression.java 446598 2006-09-15 12:55:40Z jeremias $ 18 19 package javax.xml.xpath; 20 21 import javax.xml.namespace.QName; 22 import org.xml.sax.InputSource; 23 24 /** 25 * <p><code>XPathExpression</code> provides access to compiled XPath expressions.</p> 26 * 27 * <table id="XPathExpression-evaluation" border="1" cellpadding="2"> 28 * <thead> 29 * <tr> 30 * <th colspan="2">Evaluation of XPath Expressions.</th> 31 * </tr> 32 * </thead> 33 * <tbody> 34 * <tr> 35 * <td>context</td> 36 * <td> 37 * If a request is made to evaluate the expression in the absence 38 * of a context item, an empty document node will be used for the context. 39 * For the purposes of evaluating XPath expressions, a DocumentFragment 40 * is treated like a Document node. 41 * </td> 42 * </tr> 43 * <tr> 44 * <td>variables</td> 45 * <td> 46 * If the expression contains a variable reference, its value will be found through the {@link XPathVariableResolver}. 47 * An {@link XPathExpressionException} is raised if the variable resolver is undefined or 48 * the resolver returns <code>null</code> for the variable. 49 * The value of a variable must be immutable through the course of any single evaluation.</p> 50 * </td> 51 * </tr> 52 * <tr> 53 * <td>functions</td> 54 * <td> 55 * If the expression contains a function reference, the function will be found through the {@link XPathFunctionResolver}. 56 * An {@link XPathExpressionException} is raised if the function resolver is undefined or 57 * the function resolver returns <code>null</code> for the function.</p> 58 * </td> 59 * </tr> 60 * <tr> 61 * <td>QNames</td> 62 * <td> 63 * QNames in the expression are resolved against the XPath namespace context. 64 * </td> 65 * </tr> 66 * <tr> 67 * <td>result</td> 68 * <td> 69 * This result of evaluating an expression is converted to an instance of the desired return type. 70 * Valid return types are defined in {@link XPathConstants}. 71 * Conversion to the return type follows XPath conversion rules.</p> 72 * </td> 73 * </tr> 74 * </table> 75 * 76 * @author <a href="mailto:Norman.Walsh (at) Sun.com">Norman Walsh</a> 77 * @author <a href="mailto:Jeff.Suttor (at) Sun.com">Jeff Suttor</a> 78 * @version $Revision: 446598 $, $Date: 2006-09-15 05:55:40 -0700 (Fri, 15 Sep 2006) $ 79 * @see <a href="http://www.w3.org/TR/xpath#section-Expressions">XML Path Language (XPath) Version 1.0, Expressions</a> 80 * @since 1.5 81 */ 82 public interface XPathExpression { 83 84 /** 85 * <p>Evaluate the compiled XPath expression in the specified context and return the result as the specified type.</p> 86 * 87 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 88 * variable, function and QName resolution and return type conversion.</p> 89 * 90 * <p>If <code>returnType</code> is not one of the types defined in {@link XPathConstants}, 91 * then an <code>IllegalArgumentException</code> is thrown.</p> 92 * 93 * <p>If a <code>null</code> value is provided for 94 * <code>item</code>, an empty document will be used for the 95 * context. 96 * If <code>returnType</code> is <code>null</code>, then a <code>NullPointerException</code> is thrown.</p> 97 * 98 * @param item The starting context (node or node list, for example). 99 * @param returnType The desired return type. 100 * 101 * @return The <code>Object</code> that is the result of evaluating the expression and converting the result to 102 * <code>returnType</code>. 103 * 104 * @throws XPathExpressionException If the expression cannot be evaluated. 105 * @throws IllegalArgumentException If <code>returnType</code> is not one of the types defined in {@link XPathConstants}. 106 * @throws NullPointerException If <code>returnType</code> is <code>null</code>. 107 */ 108 public Object evaluate(Object item, QName returnType) 109 throws XPathExpressionException; 110 111 /** 112 * <p>Evaluate the compiled XPath expression in the specified context and return the result as a <code>String</code>.</p> 113 * 114 * <p>This method calls {@link #evaluate(Object item, QName returnType)} with a <code>returnType</code> of 115 * {@link XPathConstants#STRING}.</p> 116 * 117 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 118 * variable, function and QName resolution and return type conversion.</p> 119 * 120 * <p>If a <code>null</code> value is provided for 121 * <code>item</code>, an empty document will be used for the 122 * context. 123 * 124 * @param item The starting context (node or node list, for example). 125 * 126 * @return The <code>String</code> that is the result of evaluating the expression and converting the result to a 127 * <code>String</code>. 128 * 129 * @throws XPathExpressionException If the expression cannot be evaluated. 130 */ 131 public String evaluate(Object item) 132 throws XPathExpressionException; 133 134 /** 135 * <p>Evaluate the compiled XPath expression in the context of the specified <code>InputSource</code> and return the result as the 136 * specified type.</p> 137 * 138 * <p>This method builds a data model for the {@link InputSource} and calls 139 * {@link #evaluate(Object item, QName returnType)} on the resulting document object.</p> 140 * 141 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 142 * variable, function and QName resolution and return type conversion.</p> 143 * 144 * <p>If <code>returnType</code> is not one of the types defined in {@link XPathConstants}, 145 * then an <code>IllegalArgumentException</code> is thrown.</p> 146 * 147 * <p>If <code>source</code> or <code>returnType</code> is <code>null</code>, 148 * then a <code>NullPointerException</code> is thrown.</p> 149 * 150 * @param source The <code>InputSource</code> of the document to evaluate over. 151 * @param returnType The desired return type. 152 * 153 * @return The <code>Object</code> that is the result of evaluating the expression and converting the result to 154 * <code>returnType</code>. 155 * 156 * @throws XPathExpressionException If the expression cannot be evaluated. 157 * @throws IllegalArgumentException If <code>returnType</code> is not one of the types defined in {@link XPathConstants}. 158 * @throws NullPointerException If <code>source</code> or <code>returnType</code> is <code>null</code>. 159 */ 160 public Object evaluate(InputSource source, QName returnType) 161 throws XPathExpressionException; 162 163 /** 164 * <p>Evaluate the compiled XPath expression in the context of the specified <code>InputSource</code> and return the result as a 165 * <code>String</code>.</p> 166 * 167 * <p>This method calls {@link #evaluate(InputSource source, QName returnType)} with a <code>returnType</code> of 168 * {@link XPathConstants#STRING}.</p> 169 * 170 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 171 * variable, function and QName resolution and return type conversion.</p> 172 * 173 * <p>If <code>source</code> is <code>null</code>, then a <code>NullPointerException</code> is thrown.</p> 174 * 175 * @param source The <code>InputSource</code> of the document to evaluate over. 176 * 177 * @return The <code>String</code> that is the result of evaluating the expression and converting the result to a 178 * <code>String</code>. 179 * 180 * @throws XPathExpressionException If the expression cannot be evaluated. 181 * @throws NullPointerException If <code>source</code> is <code>null</code>. 182 */ 183 public String evaluate(InputSource source) 184 throws XPathExpressionException; 185 } 186
