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 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
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
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
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
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
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 }