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