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 * The XPath evaluation is affected by the factors described in the following table.
35 *
36 * <a id="XPath-evaluation"></a>
37 * <table class="striped">
38 * <caption>Evaluation of XPath Expressions</caption>
39 * <thead>
40 * <tr>
41 * <th>Factor</th>
42 * <th>Behavior</th>
43 * </tr>
44 * </thead>
45 * <tbody>
46 * <tr>
47 * <td>context</td>
48 * <td>
49 * The type of the context is implementation-dependent. If the value is
50 * null, the operation must have no dependency on the context, otherwise
51 * an XPathExpressionException will be thrown.
52 *
53 * For the purposes of evaluating XPath expressions, a DocumentFragment
54 * is treated like a Document node.
55 * </td>
56 * </tr>
57 * <tr>
58 * <td>variables</td>
59 * <td>
60 * If the expression contains a variable reference, its value will be found through the {@link XPathVariableResolver}
61 * set with {@link #setXPathVariableResolver(XPathVariableResolver resolver)}.
62 * An {@link XPathExpressionException} is raised if the variable resolver is undefined or
63 * the resolver returns {@code null} for the variable.
64 * The value of a variable must be immutable through the course of any single evaluation.
65 * </td>
66 * </tr>
67 * <tr>
68 * <td>functions</td>
69 * <td>
70 * If the expression contains a function reference, the function will be found through the {@link XPathFunctionResolver}
71 * set with {@link #setXPathFunctionResolver(XPathFunctionResolver resolver)}.
72 * An {@link XPathExpressionException} is raised if the function resolver is undefined or
73 * the function resolver returns {@code null} for the function.
74 * </td>
75 * </tr>
76 * <tr>
77 * <td>QNames</td>
78 * <td>
79 * QNames in the expression are resolved against the XPath namespace context
80 * set with {@link #setNamespaceContext(NamespaceContext nsContext)}.
81 * </td>
82 * </tr>
83 * <tr>
84 * <td>result</td>
85 * <td>
86 * This result of evaluating an expression is converted to an instance of the desired return type.
87 * Valid return types are defined in {@link XPathConstants}.
88 * Conversion to the return type follows XPath conversion rules.
89 * </td>
90 * </tr>
91 * </tbody>
92 * </table>
93 *
94 * <p>An XPath object is not thread-safe and not reentrant.
95 * In other words, it is the application's responsibility to make
96 * sure that one {@link XPath} object is not used from
97 * more than one thread at any given time, and while the {@code evaluate}
98 * method is invoked, applications may not recursively call
99 * the {@code evaluate} method.
100 *
101 * @author <a href="Norman.Walsh@Sun.com">Norman Walsh</a>
102 * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
103 * @see <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a>
104 * @since 1.5
|
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 * The XPath evaluation is affected by the factors described in the following table.
35 *
36 * <a id="XPath-evaluation"></a>
37 * <table class="striped">
38 * <caption>Evaluation of XPath Expressions</caption>
39 * <thead>
40 * <tr>
41 * <th scope="col">Factor</th>
42 * <th scope="col">Behavior</th>
43 * </tr>
44 * </thead>
45 * <tbody>
46 * <tr>
47 * <th scope="row">context</th>
48 * <td>
49 * The type of the context is implementation-dependent. If the value is
50 * null, the operation must have no dependency on the context, otherwise
51 * an XPathExpressionException will be thrown.
52 *
53 * For the purposes of evaluating XPath expressions, a DocumentFragment
54 * is treated like a Document node.
55 * </td>
56 * </tr>
57 * <tr>
58 * <th scope="row">variables</th>
59 * <td>
60 * If the expression contains a variable reference, its value will be found through the {@link XPathVariableResolver}
61 * set with {@link #setXPathVariableResolver(XPathVariableResolver resolver)}.
62 * An {@link XPathExpressionException} is raised if the variable resolver is undefined or
63 * the resolver returns {@code null} for the variable.
64 * The value of a variable must be immutable through the course of any single evaluation.
65 * </td>
66 * </tr>
67 * <tr>
68 * <th scope="row">functions</th>
69 * <td>
70 * If the expression contains a function reference, the function will be found through the {@link XPathFunctionResolver}
71 * set with {@link #setXPathFunctionResolver(XPathFunctionResolver resolver)}.
72 * An {@link XPathExpressionException} is raised if the function resolver is undefined or
73 * the function resolver returns {@code null} for the function.
74 * </td>
75 * </tr>
76 * <tr>
77 * <th scope="row">QNames</th>
78 * <td>
79 * QNames in the expression are resolved against the XPath namespace context
80 * set with {@link #setNamespaceContext(NamespaceContext nsContext)}.
81 * </td>
82 * </tr>
83 * <tr>
84 * <th scope="row">result</th>
85 * <td>
86 * This result of evaluating an expression is converted to an instance of the desired return type.
87 * Valid return types are defined in {@link XPathConstants}.
88 * Conversion to the return type follows XPath conversion rules.
89 * </td>
90 * </tr>
91 * </tbody>
92 * </table>
93 *
94 * <p>An XPath object is not thread-safe and not reentrant.
95 * In other words, it is the application's responsibility to make
96 * sure that one {@link XPath} object is not used from
97 * more than one thread at any given time, and while the {@code evaluate}
98 * method is invoked, applications may not recursively call
99 * the {@code evaluate} method.
100 *
101 * @author <a href="Norman.Walsh@Sun.com">Norman Walsh</a>
102 * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
103 * @see <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a>
104 * @since 1.5
|