1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements.  See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License.  You may obtain a copy of the License at
8  *
9  *     http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 // $Id: XPathExpression.java 446598 2006-09-15 12:55:40Z jeremias $
18 
19 package javax.xml.xpath;
20 
21 import javax.xml.namespace.QName;
22 import org.xml.sax.InputSource;
23 
24 /**
25  * <p><code>XPathExpression</code> provides access to compiled XPath expressions.</p>
26  *
27  * <table id="XPathExpression-evaluation" border="1" cellpadding="2">
28  *   <thead>
29  *     <tr>
30  *       <th colspan="2">Evaluation of XPath Expressions.</th>
31  *     </tr>
32  *   </thead>
33  *   <tbody>
34  *     <tr>
35  *       <td>context</td>
36  *       <td>
37  *         If a request is made to evaluate the expression in the absence
38  * of a context item, an empty document node will be used for the context.
39  * For the purposes of evaluating XPath expressions, a DocumentFragment
40  * is treated like a Document node.
41  *      </td>
42  *    </tr>
43  *    <tr>
44  *      <td>variables</td>
45  *      <td>
46  *        If the expression contains a variable reference, its value will be found through the {@link XPathVariableResolver}.
47  *        An {@link XPathExpressionException} is raised if the variable resolver is undefined or
48  *        the resolver returns <code>null</code> for the variable.
49  *        The value of a variable must be immutable through the course of any single evaluation.</p>
50  *      </td>
51  *    </tr>
52  *    <tr>
53  *      <td>functions</td>
54  *      <td>
55  *        If the expression contains a function reference, the function will be found through the {@link XPathFunctionResolver}.
56  *        An {@link XPathExpressionException} is raised if the function resolver is undefined or
57  *        the function resolver returns <code>null</code> for the function.</p>
58  *      </td>
59  *    </tr>
60  *    <tr>
61  *      <td>QNames</td>
62  *      <td>
63  *        QNames in the expression are resolved against the XPath namespace context.
64  *      </td>
65  *    </tr>
66  *    <tr>
67  *      <td>result</td>
68  *      <td>
69  *        This result of evaluating an expression is converted to an instance of the desired return type.
70  *        Valid return types are defined in {@link XPathConstants}.
71  *        Conversion to the return type follows XPath conversion rules.</p>
72  *      </td>
73  *    </tr>
74  * </table>
75  *
76  * @author  <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a>
77  * @author  <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
78  * @version $Revision: 446598 $, $Date: 2006-09-15 05:55:40 -0700 (Fri, 15 Sep 2006) $
79  * @see <a href="http://www.w3.org/TR/xpath#section-Expressions">XML Path Language (XPath) Version 1.0, Expressions</a>
80  * @since 1.5
81  */
82 public interface XPathExpression {
83 
84     /**
85      * <p>Evaluate the compiled XPath expression in the specified context and return the result as the specified type.</p>
86      *
87      * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
88      * variable, function and QName resolution and return type conversion.</p>
89      *
90      * <p>If <code>returnType</code> is not one of the types defined in {@link XPathConstants},
91      * then an <code>IllegalArgumentException</code> is thrown.</p>
92      *
93      * <p>If a <code>null</code> value is provided for
94      * <code>item</code>, an empty document will be used for the
95      * context.
96      * If <code>returnType</code> is <code>null</code>, then a <code>NullPointerException</code> is thrown.</p>
97      *
98      * @param item The starting context (node or node list, for example).
99      * @param returnType The desired return type.
100      *
101      * @return The <code>Object</code> that is the result of evaluating the expression and converting the result to
102      *   <code>returnType</code>.
103      *
104      * @throws XPathExpressionException If the expression cannot be evaluated.
105      * @throws IllegalArgumentException If <code>returnType</code> is not one of the types defined in {@link XPathConstants}.
106      * @throws NullPointerException If  <code>returnType</code> is <code>null</code>.
107      */
evaluate(Object item, QName returnType)108     public Object evaluate(Object item, QName returnType)
109         throws XPathExpressionException;
110 
111     /**
112      * <p>Evaluate the compiled XPath expression in the specified context and return the result as a <code>String</code>.</p>
113      *
114      * <p>This method calls {@link #evaluate(Object item, QName returnType)} with a <code>returnType</code> of
115      * {@link XPathConstants#STRING}.</p>
116      *
117      * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
118      * variable, function and QName resolution and return type conversion.</p>
119      *
120      * <p>If a <code>null</code> value is provided for
121      * <code>item</code>, an empty document will be used for the
122      * context.
123      *
124      * @param item The starting context (node or node list, for example).
125      *
126      * @return The <code>String</code> that is the result of evaluating the expression and converting the result to a
127      *   <code>String</code>.
128      *
129      * @throws XPathExpressionException If the expression cannot be evaluated.
130      */
evaluate(Object item)131     public String evaluate(Object item)
132         throws XPathExpressionException;
133 
134     /**
135      * <p>Evaluate the compiled XPath expression in the context of the specified <code>InputSource</code> and return the result as the
136      * specified type.</p>
137      *
138      * <p>This method builds a data model for the {@link InputSource} and calls
139      * {@link #evaluate(Object item, QName returnType)} on the resulting document object.</p>
140      *
141      * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
142      * variable, function and QName resolution and return type conversion.</p>
143      *
144      * <p>If <code>returnType</code> is not one of the types defined in {@link XPathConstants},
145      * then an <code>IllegalArgumentException</code> is thrown.</p>
146      *
147      * <p>If <code>source</code> or <code>returnType</code> is <code>null</code>,
148      * then a <code>NullPointerException</code> is thrown.</p>
149      *
150      * @param source The <code>InputSource</code> of the document to evaluate over.
151      * @param returnType The desired return type.
152      *
153      * @return The <code>Object</code> that is the result of evaluating the expression and converting the result to
154      *   <code>returnType</code>.
155      *
156      * @throws XPathExpressionException If the expression cannot be evaluated.
157      * @throws IllegalArgumentException If <code>returnType</code> is not one of the types defined in {@link XPathConstants}.
158      * @throws NullPointerException If  <code>source</code> or <code>returnType</code> is <code>null</code>.
159      */
evaluate(InputSource source, QName returnType)160     public Object evaluate(InputSource source, QName returnType)
161         throws XPathExpressionException;
162 
163     /**
164      * <p>Evaluate the compiled XPath expression in the context of the specified <code>InputSource</code> and return the result as a
165      * <code>String</code>.</p>
166      *
167      * <p>This method calls {@link #evaluate(InputSource source, QName returnType)} with a <code>returnType</code> of
168      * {@link XPathConstants#STRING}.</p>
169      *
170      * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
171      * variable, function and QName resolution and return type conversion.</p>
172      *
173      * <p>If <code>source</code> is <code>null</code>, then a <code>NullPointerException</code> is thrown.</p>
174      *
175      * @param source The <code>InputSource</code> of the document to evaluate over.
176      *
177      * @return The <code>String</code> that is the result of evaluating the expression and converting the result to a
178      *   <code>String</code>.
179      *
180      * @throws XPathExpressionException If the expression cannot be evaluated.
181      * @throws NullPointerException If  <code>source</code> is <code>null</code>.
182      */
evaluate(InputSource source)183     public String evaluate(InputSource source)
184         throws XPathExpressionException;
185 }
186