77 * </td>
78 * </tr>
79 * <tr>
80 * <th scope="row">result</th>
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 * </tbody>
88 * </table>
89 *
90 * <p>An XPath expression is not thread-safe and not reentrant.
91 * In other words, it is the application's responsibility to make
92 * sure that one {@link XPathExpression} object is not used from
93 * more than one thread at any given time, and while the {@code evaluate}
94 * method is invoked, applications may not recursively call
95 * the {@code evaluate} method.
96 *
97 * @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a>
98 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
99 * @see <a href="http://www.w3.org/TR/xpath#section-Expressions">XML Path Language (XPath) Version 1.0, Expressions</a>
100 * @since 1.5
101 */
102 public interface XPathExpression {
103
104
105 /**
106 * Evaluate the compiled XPath expression in the specified context and return the result as the specified type.
107 *
108 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
109 * variable, function and QName resolution and return type conversion.
110 *
111 * <p>
112 * The parameter {@code item} represents the context the XPath expression
113 * will be operated on. The type of the context is implementation-dependent.
114 * If the value is {@code null}, the operation must have no dependency on
115 * the context, otherwise an XPathExpressionException will be thrown.
116 *
117 * @implNote
118 * The type of the context is usually {@link org.w3c.dom.Node}.
|
77 * </td>
78 * </tr>
79 * <tr>
80 * <th scope="row">result</th>
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 * </tbody>
88 * </table>
89 *
90 * <p>An XPath expression is not thread-safe and not reentrant.
91 * In other words, it is the application's responsibility to make
92 * sure that one {@link XPathExpression} object is not used from
93 * more than one thread at any given time, and while the {@code evaluate}
94 * method is invoked, applications may not recursively call
95 * the {@code evaluate} method.
96 *
97 * @author Norman Walsh
98 * @author Jeff Suttor
99 * @see <a href="http://www.w3.org/TR/xpath#section-Expressions">XML Path Language (XPath) Version 1.0, Expressions</a>
100 * @since 1.5
101 */
102 public interface XPathExpression {
103
104
105 /**
106 * Evaluate the compiled XPath expression in the specified context and return the result as the specified type.
107 *
108 * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
109 * variable, function and QName resolution and return type conversion.
110 *
111 * <p>
112 * The parameter {@code item} represents the context the XPath expression
113 * will be operated on. The type of the context is implementation-dependent.
114 * If the value is {@code null}, the operation must have no dependency on
115 * the context, otherwise an XPathExpressionException will be thrown.
116 *
117 * @implNote
118 * The type of the context is usually {@link org.w3c.dom.Node}.
|