1 /* 2 * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.xml.xpath; 27 28 import javax.xml.namespace.QName; 29 import org.xml.sax.InputSource; 30 31 /** 32 * {@code XPathExpression} provides access to compiled XPath expressions. 33 * 34 * <a name="XPathExpression-evaluation"></a> 35 * <table border="1" cellpadding="2"> 36 * <thead> 37 * <tr> 38 * <th colspan="2">Evaluation of XPath Expressions.</th> 39 * </tr> 40 * </thead> 41 * <tbody> 42 * <tr> 43 * <td>context</td> 44 * <td> 45 * If a request is made to evaluate the expression in the absence 46 * of a context item, an empty document node will be used for the context. 47 * For the purposes of evaluating XPath expressions, a DocumentFragment 48 * is treated like a Document node. 49 * </td> 50 * </tr> 51 * <tr> 52 * <td>variables</td> 53 * <td> 54 * If the expression contains a variable reference, its value will be found through the {@link XPathVariableResolver}. 55 * An {@link XPathExpressionException} is raised if the variable resolver is undefined or 56 * the resolver returns {@code null} for the variable. 57 * The value of a variable must be immutable through the course of any single evaluation. 58 * </td> 59 * </tr> 60 * <tr> 61 * <td>functions</td> 62 * <td> 63 * If the expression contains a function reference, the function will be found through the {@link XPathFunctionResolver}. 64 * An {@link XPathExpressionException} is raised if the function resolver is undefined or 65 * the function resolver returns {@code null} for the function. 66 * </td> 67 * </tr> 68 * <tr> 69 * <td>QNames</td> 70 * <td> 71 * QNames in the expression are resolved against the XPath namespace context. 72 * </td> 73 * </tr> 74 * <tr> 75 * <td>result</td> 76 * <td> 77 * This result of evaluating an expression is converted to an instance of the desired return type. 78 * Valid return types are defined in {@link XPathConstants}. 79 * Conversion to the return type follows XPath conversion rules. 80 * </td> 81 * </tr> 82 * </tbody> 83 * </table> 84 * 85 * <p>An XPath expression is not thread-safe and not reentrant. 86 * In other words, it is the application's responsibility to make 87 * sure that one {@link XPathExpression} object is not used from 88 * more than one thread at any given time, and while the {@code evaluate} 89 * method is invoked, applications may not recursively call 90 * the {@code evaluate} method. 91 * 92 * @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a> 93 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> 94 * @see <a href="http://www.w3.org/TR/xpath#section-Expressions">XML Path Language (XPath) Version 1.0, Expressions</a> 95 * @since 1.5 96 */ 97 public interface XPathExpression { 98 99 100 /** 101 * Evaluate the compiled XPath expression in the specified context and return the result as the specified type. 102 * 103 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 104 * variable, function and QName resolution and return type conversion. 105 * 106 * <p> 107 * The parameter {@code item} represents the context the XPath expression 108 * will be operated on. The type of the context is implementation-dependent. 109 * If the value is {@code null}, the operation must have no dependency on 110 * the context, otherwise an XPathExpressionException will be thrown. 111 * 112 * @implNote 113 * The type of the context is usually {@link org.w3c.dom.Node}. 114 * 115 * @param item The context the XPath expression will be evaluated in. 116 * @param returnType The result type expected to be returned by the XPath expression. 117 * 118 * @return The {@code Object} that is the result of evaluating the expression and converting the result to 119 * {@code returnType}. 120 * 121 * @throws XPathExpressionException If the expression cannot be evaluated. 122 * @throws IllegalArgumentException If {@code returnType} is not one of the types defined in {@link XPathConstants}. 123 * @throws NullPointerException If {@code returnType} is {@code null}. 124 */ 125 public Object evaluate(Object item, QName returnType) 126 throws XPathExpressionException; 127 128 /** 129 * Evaluate the compiled XPath expression in the specified context and return the result as a {@code String}. 130 * 131 * <p>This method calls {@link #evaluate(Object item, QName returnType)} with a {@code returnType} of 132 * {@link XPathConstants#STRING}. 133 * 134 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 135 * variable, function and QName resolution and return type conversion. 136 * 137 * <p> 138 * The parameter {@code item} represents the context the XPath expression 139 * will be operated on. The type of the context is implementation-dependent. 140 * If the value is {@code null}, the operation must have no dependency on 141 * the context, otherwise an XPathExpressionException will be thrown. 142 * 143 * @implNote 144 * The type of the context is usually {@link org.w3c.dom.Node}. 145 * 146 * @param item The context the XPath expression will be evaluated in. 147 * 148 * @return The result of evaluating an XPath expression as a {@code String}. 149 * 150 * @throws XPathExpressionException If the expression cannot be evaluated. 151 */ 152 public String evaluate(Object item) 153 throws XPathExpressionException; 154 155 /** 156 * Evaluate the compiled XPath expression in the context 157 * of the specified {@code InputSource} and return the result as the 158 * specified type. 159 * 160 * <p>This method builds a data model for the {@link InputSource} and calls 161 * {@link #evaluate(Object item, QName returnType)} on the resulting document object. 162 * 163 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 164 * variable, function and QName resolution and return type conversion. 165 * 166 * <p>If {@code returnType} is not one of the types defined in {@link XPathConstants}, 167 * then an {@code IllegalArgumentException} is thrown. 168 * 169 * <p>If {@code source} or {@code returnType} is {@code null}, 170 * then a {@code NullPointerException} is thrown. 171 * 172 * @param source The {@code InputSource} of the document to evaluate over. 173 * @param returnType The desired return type. 174 * 175 * @return The {@code Object} that is the result of evaluating the expression and converting the result to 176 * {@code returnType}. 177 * 178 * @throws XPathExpressionException If the expression cannot be evaluated. 179 * @throws IllegalArgumentException If {@code returnType} is not one of the types defined in {@link XPathConstants}. 180 * @throws NullPointerException If {@code source or returnType} is {@code null}. 181 */ 182 public Object evaluate(InputSource source, QName returnType) 183 throws XPathExpressionException; 184 185 /** 186 * Evaluate the compiled XPath expression in the context 187 * of the specified {@code InputSource} and return the result as a 188 * {@code String}. 189 * 190 * <p>This method calls {@link #evaluate(InputSource source, QName returnType)} with a {@code returnType} of 191 * {@link XPathConstants#STRING}. 192 * 193 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 194 * variable, function and QName resolution and return type conversion. 195 * 196 * <p>If {@code source} is {@code null}, then a {@code NullPointerException} is thrown. 197 * 198 * @param source The {@code InputSource} of the document to evaluate over. 199 * 200 * @return The {@code String} that is the result of evaluating the expression and converting the result to a 201 * {@code String}. 202 * 203 * @throws XPathExpressionException If the expression cannot be evaluated. 204 * @throws NullPointerException If {@code source} is {@code null}. 205 */ 206 public String evaluate(InputSource source) 207 throws XPathExpressionException; 208 209 /** 210 * Evaluate the compiled XPath expression in the specified context, and return 211 * the result with the type specified through the {@code class type}. 212 * 213 * <p> 214 * The parameter {@code item} represents the context the XPath expression 215 * will be operated on. The type of the context is implementation-dependent. 216 * If the value is {@code null}, the operation must have no dependency on 217 * the context, otherwise an XPathExpressionException will be thrown. 218 * 219 * @implNote 220 * The type of the context is usually {@link org.w3c.dom.Node}. 221 * 222 * @implSpec 223 * The default implementation in the XPath API is equivalent to: 224 * <pre> {@code 225 * (T)evaluate(item, XPathEvaluationResult.XPathResultType.getQNameType(type)); 226 * }</pre> 227 * 228 * Since the {@code evaluate} method does not support the 229 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type, specifying 230 * XPathEvaluationResult as the type will result in IllegalArgumentException. 231 * Any implementation supporting the 232 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must override 233 * this method. 234 * 235 * @param <T> The class type that will be returned by the XPath expression. 236 * @param item The context the XPath expression will be evaluated in. 237 * @param type The class type expected to be returned by the XPath expression. 238 * 239 * @return The result of evaluating the expression. 240 * 241 * @throws XPathExpressionException If the expression cannot be evaluated. 242 * @throws IllegalArgumentException If {@code type} is not of the types 243 * corresponding to the types defined in the {@link XPathEvaluationResult.XPathResultType 244 * XPathResultType}, or XPathEvaluationResult is specified as the type but an 245 * implementation supporting the 246 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type is not available. 247 * @throws NullPointerException If {@code type} is {@code null}. 248 * 249 * @since 1.9 250 */ 251 default <T>T evaluateExpression(Object item, Class<T> type) 252 throws XPathExpressionException 253 { 254 return type.cast(evaluate(item, XPathEvaluationResult.XPathResultType.getQNameType(type))); 255 } 256 257 /** 258 * Evaluate the compiled XPath expression in the specified context. This is 259 * equivalent to calling {@link #evaluateExpression(Object item, Class type)} 260 * with type {@link XPathEvaluationResult}: 261 * <pre> {@code 262 * evaluateExpression(item, XPathEvaluationResult.class); 263 * }</pre> 264 * <p> 265 * The parameter {@code item} represents the context the XPath expression 266 * will be operated on. The type of the context is implementation-dependent. 267 * If the value is {@code null}, the operation must have no dependency on 268 * the context, otherwise an XPathExpressionException will be thrown. 269 * 270 * @implNote 271 * The type of the context is usually {@link org.w3c.dom.Node}. 272 * 273 * @implSpec 274 * The default implementation in the XPath API is equivalent to: 275 * <pre> {@code 276 * evaluateExpression(item, XPathEvaluationResult.class); 277 * }</pre> 278 * 279 * Since the {@code evaluate} method does not support the 280 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} 281 * type, the default implementation of this method will always throw an 282 * IllegalArgumentException. Any implementation supporting the 283 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must therefore 284 * override this method. 285 * 286 * @param item The context the XPath expression will be evaluated in. 287 * 288 * @return The result of evaluating the expression. 289 * 290 * @throws XPathExpressionException If the expression cannot be evaluated. 291 * @throws IllegalArgumentException If the implementation of this method 292 * does not support the 293 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type. 294 * 295 * @since 1.9 296 */ 297 default XPathEvaluationResult<?> evaluateExpression(Object item) 298 throws XPathExpressionException 299 { 300 return evaluateExpression(item, XPathEvaluationResult.class); 301 } 302 303 /** 304 * Evaluate the compiled XPath expression in the specified context, 305 * and return the result with the type specified through the {@code class type} 306 * <p> 307 * This method builds a data model for the {@link InputSource} and calls 308 * {@link #evaluateExpression(Object item, Class type)} on the resulting 309 * document object. 310 * <P> 311 * By default, the JDK's data model is {@link org.w3c.dom.Document}. 312 * 313 * @implSpec 314 * The default implementation in the XPath API is equivalent to: 315 * <pre> {@code 316 (T)evaluate(source, XPathEvaluationResult.XPathResultType.getQNameType(type)); 317 * }</pre> 318 * 319 * Since the {@code evaluate} method does not support the 320 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type, specifying 321 * XPathEvaluationResult as the type will result in IllegalArgumentException. 322 * Any implementation supporting the 323 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must override 324 * this method. 325 * 326 * @param <T> The class type that will be returned by the XPath expression. 327 * @param source The {@code InputSource} of the document to evaluate over. 328 * @param type The class type expected to be returned by the XPath expression. 329 * 330 * @return The result of evaluating the expression. 331 * 332 * @throws XPathExpressionException If the expression cannot be evaluated. 333 * @throws IllegalArgumentException If {@code type} is not of the types 334 * corresponding to the types defined in the {@link XPathEvaluationResult.XPathResultType 335 * XPathResultType}, or XPathEvaluationResult is specified as the type but an 336 * implementation supporting the 337 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type 338 * is not available. 339 * @throws NullPointerException If {@code source or type} is {@code null}. 340 * 341 * @since 1.9 342 */ 343 default <T>T evaluateExpression(InputSource source, Class<T> type) 344 throws XPathExpressionException 345 { 346 return type.cast(evaluate(source, XPathEvaluationResult.XPathResultType.getQNameType(type))); 347 } 348 349 /** 350 * Evaluate the compiled XPath expression in the specified context. This is 351 * equivalent to calling {@link #evaluateExpression(InputSource source, Class type)} 352 * with type {@link XPathEvaluationResult}: 353 * <pre> {@code 354 * evaluateExpression(source, XPathEvaluationResult.class); 355 * }</pre> 356 * 357 * @implSpec 358 * The default implementation in the XPath API is equivalent to: 359 * <pre> {@code 360 * (XPathEvaluationResult)evaluateExpression(source, XPathEvaluationResult.class); 361 * }</pre> 362 * 363 * Since the {@code evaluate} method does not support the 364 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} 365 * type, the default implementation of this method will always throw an 366 * IllegalArgumentException. Any implementation supporting the 367 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must therefore 368 * override this method. 369 * 370 * @param source The {@code InputSource} of the document to evaluate over. 371 * 372 * @return The result of evaluating the expression. 373 * 374 * @throws XPathExpressionException If the expression cannot be evaluated. 375 * @throws IllegalArgumentException If the implementation of this method 376 * does not support the 377 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type. 378 * @throws NullPointerException If {@code source} is {@code null}. 379 * 380 * @since 1.9 381 */ 382 default XPathEvaluationResult<?> evaluateExpression(InputSource source) 383 throws XPathExpressionException 384 { 385 return evaluateExpression(source, XPathEvaluationResult.class); 386 } 387 }