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