1 /* 2 * Copyright (c) 2003, 2016, 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 * <tr> 42 * <td>context</td> 43 * <td> 44 * The type of the context is implementation-dependent. If the value is 45 * null, the operation must have no dependency on the context, otherwise 46 * an XPathExpressionException will be thrown. 47 * 48 * For the purposes of evaluating XPath expressions, a DocumentFragment 49 * is treated like a Document node. 50 * </td> 51 * </tr> 52 * <tr> 53 * <td>variables</td> 54 * <td> 55 * If the expression contains a variable reference, its value will be found through the {@link XPathVariableResolver}. 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 * An {@link XPathExpressionException} is raised if the function resolver is undefined or 66 * the function resolver returns {@code null} for the function. 67 * </td> 68 * </tr> 69 * <tr> 70 * <td>QNames</td> 71 * <td> 72 * QNames in the expression are resolved against the XPath namespace context. 73 * </td> 74 * </tr> 75 * <tr> 76 * <td>result</td> 77 * <td> 78 * This result of evaluating an expression is converted to an instance of the desired return type. 79 * Valid return types are defined in {@link XPathConstants}. 80 * Conversion to the return type follows XPath conversion rules. 81 * </td> 82 * </tr> 83 * </tbody> 84 * </table> 85 * 86 * <p>An XPath expression is not thread-safe and not reentrant. 87 * In other words, it is the application's responsibility to make 88 * sure that one {@link XPathExpression} object is not used from 89 * more than one thread at any given time, and while the {@code evaluate} 90 * method is invoked, applications may not recursively call 91 * the {@code evaluate} method. 92 * 93 * @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a> 94 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> 95 * @see <a href="http://www.w3.org/TR/xpath#section-Expressions">XML Path Language (XPath) Version 1.0, Expressions</a> 96 * @since 1.5 97 */ 98 public interface XPathExpression { 99 100 101 /** 102 * Evaluate the compiled XPath expression in the specified context and return the result as the specified type. 103 * 104 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 105 * variable, function and QName resolution and return type conversion. 106 * 107 * <p> 108 * The parameter {@code item} represents the context the XPath expression 109 * will be operated on. The type of the context is implementation-dependent. 110 * If the value is {@code null}, the operation must have no dependency on 111 * the context, otherwise an XPathExpressionException will be thrown. 112 * 113 * @implNote 114 * The type of the context is usually {@link org.w3c.dom.Node}. 115 * 116 * @param item The context the XPath expression will be evaluated in. 117 * @param returnType The result type expected to be returned by the XPath expression. 118 * 119 * @return The {@code Object} that is the result of evaluating the expression and converting the result to 120 * {@code returnType}. 121 * 122 * @throws XPathExpressionException If the expression cannot be evaluated. 123 * @throws IllegalArgumentException If {@code returnType} is not one of the types defined in {@link XPathConstants}. 124 * @throws NullPointerException If {@code returnType} is {@code null}. 125 */ 126 public Object evaluate(Object item, QName returnType) 127 throws XPathExpressionException; 128 129 /** 130 * Evaluate the compiled XPath expression in the specified context and return the result as a {@code String}. 131 * 132 * <p>This method calls {@link #evaluate(Object item, QName returnType)} with a {@code returnType} of 133 * {@link XPathConstants#STRING}. 134 * 135 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 136 * variable, function and QName resolution and return type conversion. 137 * 138 * <p> 139 * The parameter {@code item} represents the context the XPath expression 140 * will be operated on. The type of the context is implementation-dependent. 141 * If the value is {@code null}, the operation must have no dependency on 142 * the context, otherwise an XPathExpressionException will be thrown. 143 * 144 * @implNote 145 * The type of the context is usually {@link org.w3c.dom.Node}. 146 * 147 * @param item The context the XPath expression will be evaluated in. 148 * 149 * @return The result of evaluating an XPath expression as a {@code String}. 150 * 151 * @throws XPathExpressionException If the expression cannot be evaluated. 152 */ 153 public String evaluate(Object item) 154 throws XPathExpressionException; 155 156 /** 157 * Evaluate the compiled XPath expression in the context 158 * of the specified {@code InputSource} and return the result as the 159 * specified type. 160 * 161 * <p>This method builds a data model for the {@link InputSource} and calls 162 * {@link #evaluate(Object item, QName returnType)} on the resulting document object. 163 * 164 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 165 * variable, function and QName resolution and return type conversion. 166 * 167 * <p>If {@code returnType} is not one of the types defined in {@link XPathConstants}, 168 * then an {@code IllegalArgumentException} is thrown. 169 * 170 * <p>If {@code source} or {@code returnType} is {@code null}, 171 * then a {@code NullPointerException} is thrown. 172 * 173 * @param source The {@code InputSource} of the document to evaluate over. 174 * @param returnType The desired return type. 175 * 176 * @return The {@code Object} that is the result of evaluating the expression and converting the result to 177 * {@code returnType}. 178 * 179 * @throws XPathExpressionException If the expression cannot be evaluated. 180 * @throws IllegalArgumentException If {@code returnType} is not one of the types defined in {@link XPathConstants}. 181 * @throws NullPointerException If {@code source or returnType} is {@code null}. 182 */ 183 public Object evaluate(InputSource source, QName returnType) 184 throws XPathExpressionException; 185 186 /** 187 * Evaluate the compiled XPath expression in the context 188 * of the specified {@code InputSource} and return the result as a 189 * {@code String}. 190 * 191 * <p>This method calls {@link #evaluate(InputSource source, QName returnType)} with a {@code returnType} of 192 * {@link XPathConstants#STRING}. 193 * 194 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 195 * variable, function and QName resolution and return type conversion. 196 * 197 * <p>If {@code source} is {@code null}, then a {@code NullPointerException} is thrown. 198 * 199 * @param source The {@code InputSource} of the document to evaluate over. 200 * 201 * @return The {@code String} that is the result of evaluating the expression and converting the result to a 202 * {@code String}. 203 * 204 * @throws XPathExpressionException If the expression cannot be evaluated. 205 * @throws NullPointerException If {@code source} is {@code null}. 206 */ 207 public String evaluate(InputSource source) 208 throws XPathExpressionException; 209 210 /** 211 * Evaluate the compiled XPath expression in the specified context, and return 212 * the result with the type specified through the {@code class type}. 213 * 214 * <p> 215 * The parameter {@code item} represents the context the XPath expression 216 * will be operated on. The type of the context is implementation-dependent. 217 * If the value is {@code null}, the operation must have no dependency on 218 * the context, otherwise an XPathExpressionException will be thrown. 219 * 220 * @implNote 221 * The type of the context is usually {@link org.w3c.dom.Node}. 222 * 223 * @implSpec 224 * The default implementation in the XPath API is equivalent to: 225 * <pre> {@code 226 * (T)evaluate(item, XPathEvaluationResult.XPathResultType.getQNameType(type)); 227 * }</pre> 228 * 229 * Since the {@code evaluate} method does not support the 230 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type, specifying 231 * XPathEvaluationResult as the type will result in IllegalArgumentException. 232 * Any implementation supporting the 233 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must override 234 * this method. 235 * 236 * @param <T> The class type that will be returned by the XPath expression. 237 * @param item The context the XPath expression will be evaluated in. 238 * @param type The class type expected to be returned by the XPath expression. 239 * 240 * @return The result of evaluating the expression. 241 * 242 * @throws XPathExpressionException If the expression cannot be evaluated. 243 * @throws IllegalArgumentException If {@code type} is not of the types 244 * corresponding to the types defined in the {@link XPathEvaluationResult.XPathResultType 245 * XPathResultType}, or XPathEvaluationResult is specified as the type but an 246 * implementation supporting the 247 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type is not available. 248 * @throws NullPointerException If {@code type} is {@code null}. 249 * 250 * @since 9 251 */ 252 default <T>T evaluateExpression(Object item, Class<T> type) 253 throws XPathExpressionException 254 { 255 return type.cast(evaluate(item, XPathEvaluationResult.XPathResultType.getQNameType(type))); 256 } 257 258 /** 259 * Evaluate the compiled XPath expression in the specified context. This is 260 * equivalent to calling {@link #evaluateExpression(Object item, Class type)} 261 * with type {@link XPathEvaluationResult}: 262 * <pre> {@code 263 * evaluateExpression(item, XPathEvaluationResult.class); 264 * }</pre> 265 * <p> 266 * The parameter {@code item} represents the context the XPath expression 267 * will be operated on. The type of the context is implementation-dependent. 268 * If the value is {@code null}, the operation must have no dependency on 269 * the context, otherwise an XPathExpressionException will be thrown. 270 * 271 * @implNote 272 * The type of the context is usually {@link org.w3c.dom.Node}. 273 * 274 * @implSpec 275 * The default implementation in the XPath API is equivalent to: 276 * <pre> {@code 277 * evaluateExpression(item, XPathEvaluationResult.class); 278 * }</pre> 279 * 280 * Since the {@code evaluate} method does not support the 281 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} 282 * type, the default implementation of this method will always throw an 283 * IllegalArgumentException. Any implementation supporting the 284 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must therefore 285 * override this method. 286 * 287 * @param item The context the XPath expression will be evaluated in. 288 * 289 * @return The result of evaluating the expression. 290 * 291 * @throws XPathExpressionException If the expression cannot be evaluated. 292 * @throws IllegalArgumentException If the implementation of this method 293 * does not support the 294 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type. 295 * 296 * @since 9 297 */ 298 default XPathEvaluationResult<?> evaluateExpression(Object item) 299 throws XPathExpressionException 300 { 301 return evaluateExpression(item, XPathEvaluationResult.class); 302 } 303 304 /** 305 * Evaluate the compiled XPath expression in the specified context, 306 * and return the result with the type specified through the {@code class type} 307 * <p> 308 * This method builds a data model for the {@link InputSource} and calls 309 * {@link #evaluateExpression(Object item, Class type)} on the resulting 310 * document object. 311 * <P> 312 * By default, the JDK's data model is {@link org.w3c.dom.Document}. 313 * 314 * @implSpec 315 * The default implementation in the XPath API is equivalent to: 316 * <pre> {@code 317 (T)evaluate(source, XPathEvaluationResult.XPathResultType.getQNameType(type)); 318 * }</pre> 319 * 320 * Since the {@code evaluate} method does not support the 321 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type, specifying 322 * XPathEvaluationResult as the type will result in IllegalArgumentException. 323 * Any implementation supporting the 324 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must override 325 * this method. 326 * 327 * @param <T> The class type that will be returned by the XPath expression. 328 * @param source The {@code InputSource} of the document to evaluate over. 329 * @param type The class type expected to be returned by the XPath expression. 330 * 331 * @return The result of evaluating the expression. 332 * 333 * @throws XPathExpressionException If the expression cannot be evaluated. 334 * @throws IllegalArgumentException If {@code type} is not of the types 335 * corresponding to the types defined in the {@link XPathEvaluationResult.XPathResultType 336 * XPathResultType}, or XPathEvaluationResult is specified as the type but an 337 * implementation supporting the 338 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type 339 * is not available. 340 * @throws NullPointerException If {@code source or type} is {@code null}. 341 * 342 * @since 9 343 */ 344 default <T>T evaluateExpression(InputSource source, Class<T> type) 345 throws XPathExpressionException 346 { 347 return type.cast(evaluate(source, XPathEvaluationResult.XPathResultType.getQNameType(type))); 348 } 349 350 /** 351 * Evaluate the compiled XPath expression in the specified context. This is 352 * equivalent to calling {@link #evaluateExpression(InputSource source, Class type)} 353 * with type {@link XPathEvaluationResult}: 354 * <pre> {@code 355 * evaluateExpression(source, XPathEvaluationResult.class); 356 * }</pre> 357 * 358 * @implSpec 359 * The default implementation in the XPath API is equivalent to: 360 * <pre> {@code 361 * (XPathEvaluationResult)evaluateExpression(source, XPathEvaluationResult.class); 362 * }</pre> 363 * 364 * Since the {@code evaluate} method does not support the 365 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} 366 * type, the default implementation of this method will always throw an 367 * IllegalArgumentException. Any implementation supporting the 368 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must therefore 369 * override this method. 370 * 371 * @param source The {@code InputSource} of the document to evaluate over. 372 * 373 * @return The result of evaluating the expression. 374 * 375 * @throws XPathExpressionException If the expression cannot be evaluated. 376 * @throws IllegalArgumentException If the implementation of this method 377 * does not support the 378 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type. 379 * @throws NullPointerException If {@code source} is {@code null}. 380 * 381 * @since 9 382 */ 383 default XPathEvaluationResult<?> evaluateExpression(InputSource source) 384 throws XPathExpressionException 385 { 386 return evaluateExpression(source, XPathEvaluationResult.class); 387 } 388 }