Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||||
XPath |
|
| 1.0;1 |
1 | package org.jaxen; |
|
2 | ||
3 | /* |
|
4 | $Id: XPath.java,v 1.10 2005/05/07 17:42:14 elharo Exp $ |
|
5 | ||
6 | Copyright 2003 (C) The Werken Company. All Rights Reserved. |
|
7 | |
|
8 | Redistribution and use of this software and associated documentation |
|
9 | ("Software"), with or without modification, are permitted provided |
|
10 | that the following conditions are met: |
|
11 | ||
12 | 1. Redistributions of source code must retain copyright |
|
13 | statements and notices. Redistributions must also contain a |
|
14 | copy of this document. |
|
15 | |
|
16 | 2. Redistributions in binary form must reproduce the |
|
17 | above copyright notice, this list of conditions and the |
|
18 | following disclaimer in the documentation and/or other |
|
19 | materials provided with the distribution. |
|
20 | |
|
21 | 3. The name "jaxen" must not be used to endorse or promote |
|
22 | products derived from this Software without prior written |
|
23 | permission of The Werken Company. For written permission, |
|
24 | please contact bob@werken.com. |
|
25 | |
|
26 | 4. Products derived from this Software may not be called "jaxen" |
|
27 | nor may "jaxen" appear in their names without prior written |
|
28 | permission of The Werken Company. "jaxen" is a registered |
|
29 | trademark of The Werken Company. |
|
30 | |
|
31 | 5. Due credit should be given to The Werken Company. |
|
32 | (http://jaxen.werken.com/). |
|
33 | |
|
34 | THIS SOFTWARE IS PROVIDED BY THE WERKEN COMPANY AND CONTRIBUTORS |
|
35 | ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT |
|
36 | NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND |
|
37 | FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL |
|
38 | THE WERKEN COMPANY OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, |
|
39 | INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES |
|
40 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR |
|
41 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
|
42 | HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, |
|
43 | STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
|
44 | ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED |
|
45 | OF THE POSSIBILITY OF SUCH DAMAGE. |
|
46 | ||
47 | */ |
|
48 | ||
49 | import java.util.List; |
|
50 | ||
51 | /** Defines the interface to an object which represents an XPath 1.0 expression which |
|
52 | * can be evaluated against a variety of different XML object models. |
|
53 | * |
|
54 | * <p> |
|
55 | * Most of the evaluation methods take a context object. This is typically a |
|
56 | * node or node-set object (which is typically a <code>List</code> |
|
57 | * of node objects) or a Jaxen <code>Context</code> object. |
|
58 | * A null context is allowed, meaning that |
|
59 | * there are no XML nodes on which to evaluate. |
|
60 | * </p> |
|
61 | * |
|
62 | * @see org.jaxen.dom4j.Dom4jXPath XPath for dom4j |
|
63 | * @see org.jaxen.jdom.JDOMXPath XPath for JDOM |
|
64 | * @see org.jaxen.dom.DOMXPath XPath for W3C DOM |
|
65 | * |
|
66 | * @author <a href="mailto:bob@eng.werken.com">bob mcwhirter</a> |
|
67 | * @author <a href="mailto:jstrachan@apache.org">James Strachan</a> |
|
68 | */ |
|
69 | public interface XPath |
|
70 | { |
|
71 | // ---------------------------------------------------------------------- |
|
72 | // Basic Evaluation |
|
73 | // ---------------------------------------------------------------------- |
|
74 | ||
75 | /** Evaluate this XPath against the given context. |
|
76 | * |
|
77 | * <p> |
|
78 | * The context of evaluation my be a <em>document</em>, |
|
79 | * an <em>element</em>, or a set of <em>elements</em>. |
|
80 | * </p> |
|
81 | * |
|
82 | * <p> |
|
83 | * If the expression evaluates to an XPath string, number, or boolean |
|
84 | * type, then the equivalent Java object type is returned. |
|
85 | * Otherwise, if the result is a node-set, then the returned value is a |
|
86 | * <code>List</code>. |
|
87 | * </p> |
|
88 | * |
|
89 | * <p> |
|
90 | * When using this method, one must be careful to |
|
91 | * test the class of the returned objects, and of |
|
92 | * each of the composite members if a <code>List</code> |
|
93 | * is returned. If the returned members are XML nodes, |
|
94 | * they will be the actual <code>Document</code>, |
|
95 | * <code>Element</code> or <code>Attribute</code> objects |
|
96 | * as defined by the concrete XML object-model implementation, |
|
97 | * directly from the context document. This method <strong>does not |
|
98 | * return <em>copies</em> of anything</strong>. It merely returns |
|
99 | * references to nodes within the source document. |
|
100 | * </p> |
|
101 | * |
|
102 | * @param context the node, node-set or Context object for evaluation. |
|
103 | * This value can be null. |
|
104 | * |
|
105 | * @return the result of evaluating the XPath expression |
|
106 | * against the supplied context |
|
107 | * |
|
108 | * @throws JaxenException if an error occurs while attempting |
|
109 | * to evaluate the expression |
|
110 | */ |
|
111 | Object evaluate(Object context) throws JaxenException; |
|
112 | ||
113 | // ---------------------------------------------------------------------- |
|
114 | // Advanced Evaluation |
|
115 | // ---------------------------------------------------------------------- |
|
116 | ||
117 | /** Retrieve a string-value interpretation of this XPath |
|
118 | * expression when evaluated against the given context. |
|
119 | * |
|
120 | * <p> |
|
121 | * The string-value of the expression is determined per |
|
122 | * the <code>string(..)</code> core function as defined |
|
123 | * in the XPath specification. This means that an expression |
|
124 | * that selects more than one nodes will return the string value |
|
125 | * of the first node in the node set.. |
|
126 | * </p> |
|
127 | * |
|
128 | * @deprecated use {@link #stringValueOf(Object)} instead |
|
129 | * |
|
130 | * @param context the node, node-set or Context object for evaluation. |
|
131 | * This value can be null. |
|
132 | * |
|
133 | * @return the string-value of this expression |
|
134 | * |
|
135 | * @throws JaxenException if an error occurs while attempting |
|
136 | * to evaluate the expression |
|
137 | */ |
|
138 | String valueOf(Object context) |
|
139 | throws JaxenException; |
|
140 | ||
141 | /** Retrieve a string-value interpretation of this XPath |
|
142 | * expression when evaluated against the given context. |
|
143 | * |
|
144 | * <p> |
|
145 | * The string-value of the expression is determined per |
|
146 | * the <code>string(..)</code> core function as defined |
|
147 | * in the XPath specification. This means that an expression |
|
148 | * that selects more than one nodes will return the string value |
|
149 | * of the first node in the node set.. |
|
150 | * </p> |
|
151 | * |
|
152 | * @param context the node, node-set or Context object for evaluation. |
|
153 | * This value can be null |
|
154 | * |
|
155 | * @return the string-value interpretation of this expression |
|
156 | * |
|
157 | * @throws JaxenException if an error occurs while attempting |
|
158 | * to evaluate the expression |
|
159 | */ |
|
160 | String stringValueOf(Object context) |
|
161 | throws JaxenException; |
|
162 | ||
163 | /** Retrieve the boolean value of the first node in document order |
|
164 | * returned by this XPath expression when evaluated in |
|
165 | * the given context. |
|
166 | * |
|
167 | * <p> |
|
168 | * The boolean-value of the expression is determined per |
|
169 | * the <code>boolean()</code> function defined |
|
170 | * in the XPath specification. This means that an expression |
|
171 | * that selects zero nodes will return <code>false</code>, |
|
172 | * while an expression that selects one or more nodes will |
|
173 | * return <code>true</code>. An expression that returns a string |
|
174 | * returns false for empty strings and true for all other strings. |
|
175 | * An expression that returns a number |
|
176 | * returns false for zero and true for non-zero numbers. |
|
177 | * </p> |
|
178 | * |
|
179 | * @param context the node, node-set or Context object for evaluation. This value can be null. |
|
180 | * |
|
181 | * @return the boolean-value of this expression |
|
182 | * |
|
183 | * @throws JaxenException if an error occurs while attempting |
|
184 | * to evaluate the expression |
|
185 | */ |
|
186 | boolean booleanValueOf(Object context) |
|
187 | throws JaxenException; |
|
188 | ||
189 | ||
190 | /** Retrieve the number-value of the first node in document order |
|
191 | * returned by this XPath expression when evaluated in |
|
192 | * the given context. |
|
193 | * |
|
194 | * <p> |
|
195 | * The number-value of the expression is determined per |
|
196 | * the <code>number(..)</code> core function as defined |
|
197 | * in the XPath specification. This means that if this |
|
198 | * expression selects multiple nodes, the number-value |
|
199 | * of the first node is returned. |
|
200 | * </p> |
|
201 | * |
|
202 | * @param context the node, node-set or Context object for evaluation. This value can be null. |
|
203 | * |
|
204 | * @return the number-value interpretation of this expression |
|
205 | * |
|
206 | * @throws JaxenException if an error occurs while attempting |
|
207 | * to evaluate the expression |
|
208 | */ |
|
209 | Number numberValueOf(Object context) |
|
210 | throws JaxenException; |
|
211 | ||
212 | // ---------------------------------------------------------------------- |
|
213 | // Selection |
|
214 | // ---------------------------------------------------------------------- |
|
215 | ||
216 | /** Select all nodes that are selectable by this XPath |
|
217 | * expression. If multiple nodes match, multiple nodes |
|
218 | * will be returned. |
|
219 | * |
|
220 | * <p> |
|
221 | * <b>NOTE:</b> In most cases, nodes will be returned |
|
222 | * in document-order, as defined by the XML Canonicalization |
|
223 | * specification. The exception occurs when using XPath |
|
224 | * expressions involving the <code>union</code> operator |
|
225 | * (denoted with the pipe '|' character). |
|
226 | * </p> |
|
227 | * |
|
228 | * @see #selectSingleNode |
|
229 | * |
|
230 | * @param context the node, node-set or Context object for evaluation. |
|
231 | * This value can be null. |
|
232 | * |
|
233 | * @return the node-set of all items selected |
|
234 | * by this XPath expression. |
|
235 | * |
|
236 | * @throws JaxenException if an error occurs while attempting |
|
237 | * to evaluate the expression |
|
238 | */ |
|
239 | List selectNodes(Object context) |
|
240 | throws JaxenException; |
|
241 | ||
242 | /** |
|
243 | * <p> |
|
244 | * Return the first node in document order that is selected by this |
|
245 | * XPath expression. |
|
246 | * </p> |
|
247 | * |
|
248 | * @see #selectNodes |
|
249 | * |
|
250 | * @param context the node, node-set or Context object for evaluation. |
|
251 | * This value can be null. |
|
252 | * |
|
253 | * @return the first node in document order selected by this XPath expression |
|
254 | * |
|
255 | * @throws JaxenException if an error occurs while attempting |
|
256 | * to evaluate the expression |
|
257 | */ |
|
258 | Object selectSingleNode(Object context) |
|
259 | throws JaxenException; |
|
260 | ||
261 | // ---------------------------------------------------------------------- |
|
262 | // Helpers |
|
263 | // ---------------------------------------------------------------------- |
|
264 | ||
265 | /** Add a namespace prefix-to-URI mapping for this XPath |
|
266 | * expression. |
|
267 | * |
|
268 | * <p> |
|
269 | * Namespace prefix-to-URI mappings in an XPath are independent |
|
270 | * of those used within any document. Only the mapping explicitly |
|
271 | * added to this XPath will be available for resolving the |
|
272 | * XPath expression. |
|
273 | * </p> |
|
274 | * |
|
275 | * <p> |
|
276 | * This is a convenience method for adding mappings to the |
|
277 | * default {@link NamespaceContext} in place for this XPath. |
|
278 | * If you have installed a specific custom <code>NamespaceContext</code>, |
|
279 | * then this method will throw a <code>JaxenException</code>. |
|
280 | * </p> |
|
281 | * |
|
282 | * @param prefix the namespace prefix |
|
283 | * @param uri the namespace URI |
|
284 | * |
|
285 | * @throws JaxenException if a <code>NamespaceContext</code> |
|
286 | * used by this XPath has been explicitly installed |
|
287 | */ |
|
288 | void addNamespace(String prefix, |
|
289 | String uri) |
|
290 | throws JaxenException; |
|
291 | ||
292 | // ---------------------------------------------------------------------- |
|
293 | // Properties |
|
294 | // ---------------------------------------------------------------------- |
|
295 | ||
296 | /** Set a <code>NamespaceContext</code> for this |
|
297 | * XPath expression. |
|
298 | * |
|
299 | * <p> |
|
300 | * A <code>NamespaceContext</code> is responsible for translating |
|
301 | * namespace prefixes within the expression into namespace URIs. |
|
302 | * </p> |
|
303 | * |
|
304 | * @see NamespaceContext |
|
305 | * @see NamespaceContext#translateNamespacePrefixToUri |
|
306 | * |
|
307 | * @param namespaceContext the <code>NamespaceContext</code> to |
|
308 | * install for this expression |
|
309 | */ |
|
310 | void setNamespaceContext(NamespaceContext namespaceContext); |
|
311 | ||
312 | /** Set a <code>FunctionContext</code> for this XPath |
|
313 | * expression. |
|
314 | * |
|
315 | * <p> |
|
316 | * A <code>FunctionContext</code> is responsible for resolving |
|
317 | * all function calls used within the expression. |
|
318 | * </p> |
|
319 | * |
|
320 | * @see FunctionContext |
|
321 | * @see FunctionContext#getFunction |
|
322 | * |
|
323 | * @param functionContext the <code>FunctionContext</code> to |
|
324 | * install for this expression |
|
325 | */ |
|
326 | void setFunctionContext(FunctionContext functionContext); |
|
327 | ||
328 | /** Set a <code>VariableContext</code> for this XPath |
|
329 | * expression. |
|
330 | * |
|
331 | * <p> |
|
332 | * A <code>VariableContext</code> is responsible for resolving |
|
333 | * all variables referenced within the expression. |
|
334 | * </p> |
|
335 | * |
|
336 | * @see VariableContext |
|
337 | * @see VariableContext#getVariableValue |
|
338 | * |
|
339 | * @param variableContext the <code>VariableContext</code> to |
|
340 | * install for this expression. |
|
341 | */ |
|
342 | void setVariableContext(VariableContext variableContext); |
|
343 | ||
344 | /** Retrieve the <code>NamespaceContext</code> used by this XPath |
|
345 | * expression. |
|
346 | * |
|
347 | * <p> |
|
348 | * A <code>FunctionContext</code> is responsible for resolving |
|
349 | * all function calls used within the expression. |
|
350 | * </p> |
|
351 | * |
|
352 | * <p> |
|
353 | * If this XPath expression has not previously had a <code>NamespaceContext</code> |
|
354 | * installed, a new default <code>NamespaceContext</code> will be created, |
|
355 | * installed and returned. |
|
356 | * </p> |
|
357 | * |
|
358 | * @see NamespaceContext |
|
359 | * |
|
360 | * @return the <code>NamespaceContext</code> used by this expression |
|
361 | */ |
|
362 | NamespaceContext getNamespaceContext(); |
|
363 | ||
364 | /** Retrieve the <code>FunctionContext</code> used by this XPath |
|
365 | * expression. |
|
366 | * |
|
367 | * <p> |
|
368 | * A <code>FunctionContext</code> is responsible for resolving |
|
369 | * all function calls used within the expression. |
|
370 | * </p> |
|
371 | * |
|
372 | * <p> |
|
373 | * If this XPath expression has not previously had a <code>FunctionContext</code> |
|
374 | * installed, a new default <code>FunctionContext</code> will be created, |
|
375 | * installed and returned. |
|
376 | * </p> |
|
377 | * |
|
378 | * @see FunctionContext |
|
379 | * |
|
380 | * @return the <code>FunctionContext</code> used by this expression |
|
381 | */ |
|
382 | FunctionContext getFunctionContext(); |
|
383 | ||
384 | /** Retrieve the <code>VariableContext</code> used by this XPath |
|
385 | * expression. |
|
386 | * |
|
387 | * <p> |
|
388 | * A <code>VariableContext</code> is responsible for resolving |
|
389 | * all variables referenced within the expression. |
|
390 | * </p> |
|
391 | * |
|
392 | * <p> |
|
393 | * If this XPath expression has not previously had a <code>VariableContext</code> |
|
394 | * installed, a new default <code>VariableContext</code> will be created, |
|
395 | * installed and returned. |
|
396 | * </p> |
|
397 | * |
|
398 | * @see VariableContext |
|
399 | * |
|
400 | * @return the <code>VariableContext</code> used by this expression |
|
401 | */ |
|
402 | VariableContext getVariableContext(); |
|
403 | ||
404 | ||
405 | /** Retrieve the XML object-model-specific {@link Navigator} |
|
406 | * used to evaluate this XPath expression. |
|
407 | * |
|
408 | * @return the implementation-specific <code>Navigator</code> |
|
409 | */ |
|
410 | Navigator getNavigator(); |
|
411 | } |