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
19package javax.xml.xpath;
20
21import javax.xml.namespace.QName;
22import 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 */
82public 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     */
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     */
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     */
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     */
183    public String evaluate(InputSource source)
184        throws XPathExpressionException;
185}
186