1 package org.jaxen;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
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
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
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
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
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
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 }