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.NamespaceContext; 29 import javax.xml.namespace.QName; 30 import org.xml.sax.InputSource; 31 32 /** 33 * {@code XPath} provides access to the XPath evaluation environment and expressions. 34 * 35 * <a name="XPath-evaluation"></a> 36 * <table border="1" cellpadding="2"> 37 * <thead> 38 * <tr> 39 * <th colspan="2">Evaluation of XPath Expressions.</th> 40 * </tr> 41 * </thead> 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 * set with {@link #setXPathVariableResolver(XPathVariableResolver resolver)}. 56 * An {@link XPathExpressionException} is raised if the variable resolver is undefined or 57 * the resolver returns {@code null} for the variable. 58 * The value of a variable must be immutable through the course of any single evaluation. 59 * </td> 60 * </tr> 61 * <tr> 62 * <td>functions</td> 63 * <td> 64 * If the expression contains a function reference, the function will be found through the {@link XPathFunctionResolver} 65 * set with {@link #setXPathFunctionResolver(XPathFunctionResolver resolver)}. 66 * An {@link XPathExpressionException} is raised if the function resolver is undefined or 67 * the function resolver returns {@code null} for the function. 68 * </td> 69 * </tr> 70 * <tr> 71 * <td>QNames</td> 72 * <td> 73 * QNames in the expression are resolved against the XPath namespace context 74 * set with {@link #setNamespaceContext(NamespaceContext nsContext)}. 75 * </td> 76 * </tr> 77 * <tr> 78 * <td>result</td> 79 * <td> 80 * This result of evaluating an expression is converted to an instance of the desired return type. 81 * Valid return types are defined in {@link XPathConstants}. 82 * Conversion to the return type follows XPath conversion rules. 83 * </td> 84 * </tr> 85 * </table> 86 * 87 * <p>An XPath object is not thread-safe and not reentrant. 88 * In other words, it is the application's responsibility to make 89 * sure that one {@link XPath} object is not used from 90 * more than one thread at any given time, and while the {@code evaluate} 91 * method is invoked, applications may not recursively call 92 * the {@code evaluate} method. 93 * 94 * @author <a href="Norman.Walsh@Sun.com">Norman Walsh</a> 95 * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a> 96 * @see <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a> 97 * @since 1.5 98 */ 99 public interface XPath { 100 101 102 /** 103 * Reset this {@code XPath} to its original configuration. 104 * 105 * <p>{@code XPath} is reset to the same state as when it was created with 106 * {@link XPathFactory#newXPath()}. 107 * {@code reset()} is designed to allow the reuse of existing {@code XPath}s 108 * thus saving resources associated with the creation of new {@code XPath}s. 109 * 110 * <p>The reset {@code XPath} is not guaranteed to have the same 111 * {@link XPathFunctionResolver}, {@link XPathVariableResolver} 112 * or {@link NamespaceContext} {@code Object}s, e.g. {@link Object#equals(Object obj)}. 113 * It is guaranteed to have a functionally equal {@code XPathFunctionResolver}, 114 * {@code XPathVariableResolver} and {@code NamespaceContext}. 115 */ 116 public void reset(); 117 118 /** 119 * Establish a variable resolver. 120 * 121 * <p>A {@code NullPointerException} is thrown if {@code resolver} is {@code null}. 122 * 123 * @param resolver Variable resolver. 124 * 125 * @throws NullPointerException If {@code resolver} is {@code null}. 126 */ 127 public void setXPathVariableResolver(XPathVariableResolver resolver); 128 129 /** 130 * Return the current variable resolver. 131 * 132 * <p>{@code null} is returned in no variable resolver is in effect. 133 * 134 * @return Current variable resolver. 135 */ 136 public XPathVariableResolver getXPathVariableResolver(); 137 138 /** 139 * Establish a function resolver. 140 * 141 * <p>A {@code NullPointerException} is thrown if {@code resolver} is {@code null}. 142 * 143 * @param resolver XPath function resolver. 144 * 145 * @throws NullPointerException If {@code resolver} is {@code null}. 146 */ 147 public void setXPathFunctionResolver(XPathFunctionResolver resolver); 148 149 /** 150 * Return the current function resolver. 151 * <p> 152 * {@code null} is returned in no function resolver is in effect. 153 * 154 * @return Current function resolver. 155 */ 156 public XPathFunctionResolver getXPathFunctionResolver(); 157 158 /** 159 * Establish a namespace context. 160 * 161 * <p>A {@code NullPointerException} is thrown if {@code nsContext} is {@code null}. 162 * 163 * @param nsContext Namespace context to use. 164 * 165 * @throws NullPointerException If {@code nsContext} is {@code null}. 166 */ 167 public void setNamespaceContext(NamespaceContext nsContext); 168 169 /** 170 * Return the current namespace context. 171 * 172 * <p>{@code null} is returned in no namespace context is in effect. 173 * 174 * @return Current Namespace context. 175 */ 176 public NamespaceContext getNamespaceContext(); 177 178 /** 179 * Compile an XPath expression for later evaluation. 180 * 181 * <p>If {@code expression} contains any {@link XPathFunction}s, 182 * they must be available via the {@link XPathFunctionResolver}. 183 * An {@link XPathExpressionException} will be thrown if the 184 * {@code XPathFunction} 185 * cannot be resovled with the {@code XPathFunctionResolver}. 186 * 187 * <p>If {@code expression} contains any variables, the 188 * {@link XPathVariableResolver} in effect 189 * <strong>at compile time</strong> will be used to resolve them. 190 * 191 * @param expression The XPath expression. 192 * 193 * @return Compiled XPath expression. 194 195 * @throws XPathExpressionException If {@code expression} cannot be compiled. 196 * @throws NullPointerException If {@code expression} is {@code null}. 197 */ 198 public XPathExpression compile(String expression) 199 throws XPathExpressionException; 200 201 /** 202 * Evaluate an {@code XPath} expression in the specified context and 203 * return the result as the specified type. 204 * 205 * <p> 206 * See <a href="#XPath-evaluation">Evaluation of XPath Expressions</a> 207 * for context item evaluation, variable, function and {@code QName} resolution 208 * and return type conversion. 209 * <p> 210 * The parameter {@code item} represents the context the XPath expression 211 * will be operated on. The type of the context is implementation-dependent. 212 * If the value is {@code null}, the operation must have no dependency on 213 * the context, otherwise an XPathExpressionException will be thrown. 214 * 215 * @implNote 216 * The type of the context is usually {@link org.w3c.dom.Node}. 217 * 218 * @param expression The XPath expression. 219 * @param item The context the XPath expression will be evaluated in. 220 * @param returnType The result type expected to be returned by the XPath expression. 221 * 222 * @return The result of evaluating an XPath expression as an {@code Object} of {@code returnType}. 223 * 224 * @throws XPathExpressionException If {@code expression} cannot be evaluated. 225 * @throws IllegalArgumentException If {@code returnType} is not one of the types defined in {@link XPathConstants} ( 226 * {@link XPathConstants#NUMBER NUMBER}, 227 * {@link XPathConstants#STRING STRING}, 228 * {@link XPathConstants#BOOLEAN BOOLEAN}, 229 * {@link XPathConstants#NODE NODE} or 230 * {@link XPathConstants#NODESET NODESET}). 231 * @throws NullPointerException If {@code expression or returnType} is {@code null}. 232 */ 233 public Object evaluate(String expression, Object item, QName returnType) 234 throws XPathExpressionException; 235 236 /** 237 * Evaluate an XPath expression in the specified context and return the result as a {@code String}. 238 * 239 * <p>This method calls {@link #evaluate(String expression, Object item, QName returnType)} with a {@code returnType} of 240 * {@link XPathConstants#STRING}. 241 * 242 * <p>See <a href="#XPath-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 243 * variable, function and QName resolution and return type conversion. 244 * 245 * <p> 246 * The parameter {@code item} represents the context the XPath expression 247 * will be operated on. The type of the context is implementation-dependent. 248 * If the value is {@code null}, the operation must have no dependency on 249 * the context, otherwise an XPathExpressionException will be thrown. 250 * 251 * @implNote 252 * The type of the context is usually {@link org.w3c.dom.Node}. 253 * 254 * @param expression The XPath expression. 255 * @param item The context the XPath expression will be evaluated in. 256 * 257 * @return The result of evaluating an XPath expression as a {@code String}. 258 * 259 * @throws XPathExpressionException If {@code expression} cannot be evaluated. 260 * @throws NullPointerException If {@code expression} is {@code null}. 261 */ 262 public String evaluate(String expression, Object item) 263 throws XPathExpressionException; 264 265 /** 266 * Evaluate an XPath expression in the context of the specified {@code InputSource} 267 * and return the result as the specified type. 268 * 269 * <p>This method builds a data model for the {@link InputSource} and calls 270 * {@link #evaluate(String expression, Object item, QName returnType)} on the resulting document object. 271 * 272 * <p>See <a href="#XPath-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 273 * variable, function and QName resolution and return type conversion. 274 * 275 * @param expression The XPath expression. 276 * @param source The input source of the document to evaluate over. 277 * @param returnType The desired return type. 278 * 279 * @return The {@code Object} that encapsulates the result of evaluating the expression. 280 * 281 * @throws XPathExpressionException If expression cannot be evaluated. 282 * @throws IllegalArgumentException If {@code returnType} is not one of the types defined in {@link XPathConstants}. 283 * @throws NullPointerException If {@code expression, source or returnType} is {@code null}. 284 */ 285 public Object evaluate( 286 String expression, 287 InputSource source, 288 QName returnType) 289 throws XPathExpressionException; 290 291 /** 292 * Evaluate an XPath expression in the context of the specified {@code InputSource} 293 * and return the result as a {@code String}. 294 * 295 * <p>This method calls {@link #evaluate(String expression, InputSource source, QName returnType)} with a 296 * {@code returnType} of {@link XPathConstants#STRING}. 297 * 298 * <p>See <a href="#XPath-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 299 * variable, function and QName resolution and return type conversion. 300 * 301 * @param expression The XPath expression. 302 * @param source The {@code InputSource} of the document to evaluate over. 303 * 304 * @return The {@code String} that is the result of evaluating the expression and 305 * converting the result to a {@code String}. 306 * 307 * @throws XPathExpressionException If expression cannot be evaluated. 308 * @throws NullPointerException If {@code expression or source} is {@code null}. 309 */ 310 public String evaluate(String expression, InputSource source) 311 throws XPathExpressionException; 312 313 /** 314 * Evaluate an XPath expression in the specified context and return 315 * the result with the type specified through the {@code class type} 316 * 317 * <p> 318 * The parameter {@code item} represents the context the XPath expression 319 * will be operated on. The type of the context is implementation-dependent. 320 * If the value is {@code null}, the operation must have no dependency on 321 * the context, otherwise an XPathExpressionException will be thrown. 322 * 323 * @implNote 324 * The type of the context is usually {@link org.w3c.dom.Node}. 325 * 326 * @implSpec 327 * The default implementation in the XPath API is equivalent to: 328 * <pre> {@code 329 * (T)evaluate(expression, item, 330 * XPathEvaluationResult.XPathResultType.getQNameType(type)); 331 * }</pre> 332 * 333 * Since the {@code evaluate} method does not support the 334 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type, specifying 335 * XPathEvaluationResult as the type will result in IllegalArgumentException. 336 * Any implementation supporting the 337 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must override 338 * this method. 339 * 340 * @param <T> The class type that will be returned by the XPath expression. 341 * @param expression The XPath expression. 342 * @param item The context the XPath expression will be evaluated in. 343 * @param type The class type expected to be returned by the XPath expression. 344 * 345 * @return The result of evaluating the expression. 346 * 347 * @throws XPathExpressionException If the expression cannot be evaluated. 348 * @throws IllegalArgumentException If {@code type} is not of the types 349 * corresponding to the types defined in the {@link XPathEvaluationResult.XPathResultType}, 350 * or XPathEvaluationResult is specified as the type but an implementation supporting the 351 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type is not available. 352 * @throws NullPointerException If {@code expression or type} is {@code null}. 353 * 354 * @since 1.9 355 */ 356 default <T>T evaluateExpression(String expression, Object item, Class<T> type) 357 throws XPathExpressionException { 358 return type.cast(evaluate(expression, item, 359 XPathEvaluationResult.XPathResultType.getQNameType(type))); 360 } 361 362 /** 363 * Evaluate an XPath expression in the specified context. This is equivalent to 364 * calling {@link #evaluateExpression(String expression, Object item, Class type)} 365 * with type {@link XPathEvaluationResult}: 366 * <pre> {@code 367 * evaluateExpression(expression, item, XPathEvaluationResult.class); 368 * }</pre> 369 * <p> 370 * The parameter {@code item} represents the context the XPath expression 371 * will be operated on. The type of the context is implementation-dependent. 372 * If the value is {@code null}, the operation must have no dependency on 373 * the context, otherwise an XPathExpressionException will be thrown. 374 * 375 * @implNote 376 * The type of the context is usually {@link org.w3c.dom.Node}. 377 * 378 * @implSpec 379 * The default implementation in the XPath API is equivalent to: 380 * <pre> {@code 381 * evaluateExpression(expression, item, XPathEvaluationResult.class); 382 * }</pre> 383 * 384 * Since the {@code evaluate} method does not support the 385 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} 386 * type, the default implementation of this method will always throw an 387 * IllegalArgumentException. Any implementation supporting the 388 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must therefore 389 * override this method. 390 * 391 * @param expression The XPath expression. 392 * @param item The context the XPath expression will be evaluated in. 393 * 394 * @return The result of evaluating the expression. 395 * 396 * @throws XPathExpressionException If the expression cannot be evaluated. 397 * @throws IllegalArgumentException If the implementation of this method 398 * does not support the 399 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type. 400 * @throws NullPointerException If {@code expression} is {@code null}. 401 * 402 * @since 1.9 403 */ 404 default XPathEvaluationResult<?> evaluateExpression(String expression, Object item) 405 throws XPathExpressionException 406 { 407 return evaluateExpression(expression, item, XPathEvaluationResult.class); 408 } 409 410 /** 411 * Evaluate an XPath expression in the context of the specified {@code source} 412 * and return the result as specified. 413 * <p> 414 * This method builds a data model for the {@link InputSource} and calls 415 * {@link #evaluateExpression(String expression, Object item, Class type)} 416 * on the resulting document object. The data model is usually 417 * {@link org.w3c.dom.Document} 418 * 419 * @implSpec 420 * The default implementation in the XPath API is equivalent to: 421 * <pre> {@code 422 (T)evaluate(expression, source, 423 XPathEvaluationResult.XPathResultType.getQNameType(type)); 424 * }</pre> 425 * 426 * Since the {@code evaluate} method does not support the 427 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type, specifying 428 * XPathEvaluationResult as the type will result in IllegalArgumentException. 429 * Any implementation supporting the 430 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must override 431 * this method. 432 * 433 * @param <T> The class type that will be returned by the XPath expression. 434 * @param expression The XPath expression. 435 * @param source The input source of the document to evaluate over. 436 * @param type The class type expected to be returned by the XPath expression. 437 * 438 * @return The result of evaluating the expression. 439 * 440 * @throws XPathExpressionException If the expression cannot be evaluated. 441 * @throws IllegalArgumentException If {@code type} is not of the types 442 * corresponding to the types defined in the {@link XPathEvaluationResult.XPathResultType 443 * XPathResultType}, or XPathEvaluationResult is specified as the type but an 444 * implementation supporting the 445 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type is not available. 446 * @throws NullPointerException If {@code expression, source or type}is {@code null}. 447 * 448 * @since 1.9 449 */ 450 default <T>T evaluateExpression(String expression, InputSource source, Class<T> type) 451 throws XPathExpressionException 452 { 453 return type.cast(evaluate(expression, source, 454 XPathEvaluationResult.XPathResultType.getQNameType(type))); 455 } 456 457 /** 458 * Evaluate an XPath expression in the specified context. This is equivalent to 459 * calling {@link #evaluateExpression(String expression, Object item, Class type)} 460 * with type {@link XPathEvaluationResult}: 461 * <pre> {@code 462 * evaluateExpression(expression, item, XPathEvaluationResult.class); 463 * }</pre> 464 * 465 * @implSpec 466 * The default implementation in the XPath API is equivalent to: 467 * <pre> {@code 468 * evaluateExpression(expression, source, XPathEvaluationResult.class); 469 * }</pre> 470 * 471 * Since the {@code evaluate} method does not support the 472 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} 473 * type, the default implementation of this method will always throw an 474 * IllegalArgumentException. Any implementation supporting the 475 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must therefore 476 * override this method. 477 * 478 * @param expression The XPath expression. 479 * @param source The input source of the document to evaluate over. 480 * 481 * @return The result of evaluating the expression. 482 * 483 * @throws XPathExpressionException If the expression cannot be evaluated. 484 * @throws IllegalArgumentException If the implementation of this method 485 * does not support the 486 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type. 487 * @throws NullPointerException If {@code expression or source} is {@code null}. 488 * 489 * @since 1.9 490 */ 491 default XPathEvaluationResult<?> evaluateExpression(String expression, InputSource source) 492 throws XPathExpressionException 493 { 494 return evaluateExpression(expression, source, XPathEvaluationResult.class); 495 } 496 }