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"/>
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)}.
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 * <p>
94 *
95 * @author <a href="Norman.Walsh@Sun.com">Norman Walsh</a>
96 * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
97 * @see <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a>
98 * @since 1.5
99 */
100 public interface XPath {
101
102
103 /**
104 * Reset this {@code XPath} to its original configuration.
105 *
106 * <p>{@code XPath} is reset to the same state as when it was created with
107 * {@link XPathFactory#newXPath()}.
108 * {@code reset()} is designed to allow the reuse of existing {@code XPath}s
109 * thus saving resources associated with the creation of new {@code XPath}s.
110 *
111 * <p>The reset {@code XPath} is not guaranteed to have the same
112 * {@link XPathFunctionResolver}, {@link XPathVariableResolver}
113 * or {@link NamespaceContext} {@code Object}s, e.g. {@link Object#equals(Object obj)}.
445 * implementation supporting the
446 * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type is not available.
447 * @throws NullPointerException If {@code expression, source or type}is {@code null}.
448 *
449 * @since 1.9
450 */
451 default <T>T evaluateExpression(String expression, InputSource source, Class<T> type)
452 throws XPathExpressionException
453 {
454 return type.cast(evaluate(expression, source,
455 XPathEvaluationResult.XPathResultType.getQNameType(type)));
456 }
457
458 /**
459 * Evaluate an XPath expression in the specified context. This is equivalent to
460 * calling {@link #evaluateExpression(String expression, Object item, Class type)}
461 * with type {@link XPathEvaluationResult}:
462 * <pre> {@code
463 * evaluateExpression(expression, item, XPathEvaluationResult.class);
464 * }</pre>
465 * <p>
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.
|
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)}.
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)}.
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.
|