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