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 List of node objects) or
57 * a Jaxen Context 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 a given context.
76 *
77 * <p>
78 * The context of evaluation my be a <i>document</i>,
79 * an <i>element</i>, or a set of <i>elements</i>.
80 * </p>
81 *
82 * <p>
83 * If the expression evaluates to a single primitive
84 * (String, Number or Boolean) type, it is returned
85 * directly. Otherwise, the returned value is a
86 * List (a <code>node-set</code>, in the terms of the
87 * specification) of values.
88 * </p>
89 *
90 * <p>
91 * When using this method, one must be careful to
92 * test the class of the returned objects, and of
93 * each of the composite members if a <code>List</code>
94 * is returned. If the returned members are XML entities,
95 * they will be the actual <code>Document</code>,
96 * <code>Element</code> or <code>Attribute</code> objects
97 * as defined by the concrete XML object-model implementation,
98 * directly from the context document. This <b>does not
99 * return <i>copies</i> of anything</b>, but merely returns
100 * references to entities within the source document.
101 * </p>
102 *
103 * @param context the node, node-set or Context object for evaluation.
104 * This value can be null.
105 *
106 * @return the result of evaluating the XPath expression
107 * against the supplied context
108 *
109 * @throws JaxenException if an error occurs while attempting
110 * to perform evaluation
111 */
112 Object evaluate(Object context) throws JaxenException;
113
114
115
116
117
118 /*** Retrieve a string-value interpretation of this XPath
119 * expression when evaluated against a given context.
120 *
121 * <p>
122 * The string-value of the expression is determined per
123 * the <code>string(..)</code> core function as defined
124 * in the XPath specification. This means that an expression
125 * that selects more than one nodes will return the string value
126 * of the first node in the node set..
127 * </p>
128 *
129 * @deprecated use {@link #stringValueOf(Object) instead}
130 *
131 * @param context the node, node-set or Context object for evaluation.
132 * This value can be null.
133 *
134 * @return the string-value of this expression
135 *
136 * @throws JaxenException if an error occurs while attempting
137 * to perform evaluation
138 */
139 String valueOf(Object context)
140 throws JaxenException;
141
142 /*** Retrieve a string-value interpretation of this XPath
143 * expression when evaluated against a given context.
144 *
145 * <p>
146 * The string-value of the expression is determined per
147 * the <code>string(..)</code> core function as defined
148 * in the XPath specification. This means that an expression
149 * that selects more than one nodes will return the string value
150 * of the first node in the node set..
151 * </p>
152 *
153 * @param context the node, node-set or Context object for evaluation. 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 perform evaluation
159 */
160 String stringValueOf(Object context)
161 throws JaxenException;
162
163 /*** Retrieve a boolean-value interpretation of this XPath
164 * expression when evaluated against a given context.
165 *
166 * <p>
167 * The boolean-value of the expression is determined per
168 * the <code>boolean()</code> core function as defined
169 * in the XPath specification. This means that an expression
170 * that selects zero nodes will return <code>false</code>,
171 * while an expression that selects one-or-more nodes will
172 * return <code>true</code>.
173 * </p>
174 *
175 * @param context the node, node-set or Context object for evaluation. This value can be null.
176 *
177 * @return the boolean-value of this expression
178 *
179 * @throws JaxenException if an error occurs while attempting
180 * to perform evaluation.
181 */
182 boolean booleanValueOf(Object context)
183 throws JaxenException;
184
185
186 /*** Retrieve a number-value interpretation of this XPath
187 * expression when evaluated against a given context.
188 *
189 * <p>
190 * The number-value of the expression is determined per
191 * the <code>number(..)</code> core function as defined
192 * in the XPath specification. This means that if this
193 * expression selects multiple nodes, the number-value
194 * of the first node is returned.
195 * </p>
196 *
197 * @param context the node, node-set or Context object for evaluation. This value can be null
198 *
199 * @return the number-value interpretation of this expression.
200 *
201 * @throws JaxenException if an error occurs while attempting
202 * to perform evaluation.
203 */
204 Number numberValueOf(Object context)
205 throws JaxenException;
206
207
208
209
210
211 /*** Select all nodes that are selectable by this XPath
212 * expression. If multiple nodes match, multiple nodes
213 * will be returned.
214 *
215 * <p>
216 * <b>NOTE:</b> In most cases, nodes will be returned
217 * in document-order, as defined by the XML Canonicalization
218 * specification. The exception occurs when using XPath
219 * expressions involving the <code>union</code> operator
220 * (denoted with the pipe '|' character).
221 * </p>
222 *
223 * @see #selectSingleNode
224 *
225 * @param context the node, node-set or Context object for evaluation. This value can be null
226 *
227 * @return the <code>node-set</code> of all items selected
228 * by this XPath expression.
229 *
230 * @throws JaxenException if an error occurs while attempting
231 * to perform evaluation.
232 */
233 List selectNodes(Object context)
234 throws JaxenException;
235
236 /*** Select only the first node that is selectable by this XPath
237 * expression. If multiple nodes match, only one node will be
238 * returned.
239 *
240 * <b>NOTE:</b> In most cases, the selected node will be the first
241 * selectable node in document-order, as defined by the XML Canonicalization
242 * specification. The exception occurs when using XPath
243 * expressions involving the <code>union</code> operator
244 * (denoted with the pipe '|' character).
245 * This is a bug and needs to be fixed.
246 * </p>
247 *
248 * @see #selectNodes
249 *
250 * @param context the node, node-set or Context object for evaluation. This value can be null.
251 *
252 * @return the <code>node-set</code> of all items selected
253 * by this XPath expression
254 *
255 * @throws JaxenException if an error occurs while attempting
256 * to perform evaluation
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 use with 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 use with 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 use with 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 * for us in evaluating this XPath expression.
407 *
408 * @return the implementation-specific <code>Navigator</code>
409 */
410 Navigator getNavigator();
411 }