1
2
3
4
5
6
7
8 package org.dom4j;
9
10 import java.util.List;
11 import java.util.Map;
12
13 import org.jaxen.FunctionContext;
14 import org.jaxen.NamespaceContext;
15 import org.jaxen.VariableContext;
16
17 /***
18 * <p>
19 * <code>XPath</code> represents an XPath expression after it has been parsed
20 * from a String.
21 * </p>
22 *
23 * @author <a href="mailto:james.strachan@metastuff.com">James Strachan </a>
24 * @version $Revision: 1.20 $
25 */
26 public interface XPath extends NodeFilter {
27 /***
28 * <p>
29 * <code>getText</code> will return the textual version of the XPath
30 * expression.
31 * </p>
32 *
33 * @return the textual format of the XPath expression.
34 */
35 String getText();
36
37 /***
38 * <p>
39 * <code>matches</code> returns true if the given node matches the XPath
40 * expression. To be more precise when evaluating this XPath expression on
41 * the given node the result set must include the node.
42 * </p>
43 *
44 * @param node
45 * DOCUMENT ME!
46 *
47 * @return true if the given node matches this XPath expression
48 */
49 boolean matches(Node node);
50
51 /***
52 * <p>
53 * <code>evaluate</code> evaluates an XPath expression and returns the
54 * result as an {@link Object}. The object returned can either be a {@link
55 * List} of {@link Node}instances, a {@link Node}instance, a {@link
56 * String} or a {@link Number}instance depending on the XPath expression.
57 * </p>
58 *
59 * @param context
60 * is either a node or a list of nodes on which to evalute the
61 * XPath
62 *
63 * @return the value of the XPath expression as a {@link List}of {@link
64 * Node} instances, a {@link Node}instance, a {@link String}or a
65 * {@link Number}instance depending on the XPath expression.
66 */
67 Object evaluate(Object context);
68
69 /***
70 * <p>
71 * <code>selectObject</code> evaluates an XPath expression and returns the
72 * result as an {@link Object}. The object returned can either be a {@link
73 * List} of {@link Node}instances, a {@link Node}instance, a {@link
74 * String} or a {@link Number}instance depending on the XPath expression.
75 * </p>
76 *
77 * @param context
78 * is either a node or a list of nodes on which to evalute the
79 * XPath
80 *
81 * @return the value of the XPath expression as a {@link List}of {@link
82 * Node} instances, a {@link Node}instance, a {@link String}or a
83 * {@link Number}instance depending on the XPath expression.
84 *
85 * @deprecated please use evaluate(Object) instead. WILL BE REMOVED IN
86 * dom4j-1.6 !!
87 */
88 Object selectObject(Object context);
89
90 /***
91 * <p>
92 * <code>selectNodes</code> performs this XPath expression on the given
93 * {@link Node}or {@link List}of {@link Node}s instances appending all
94 * the results together into a single list.
95 * </p>
96 *
97 * @param context
98 * is either a node or a list of nodes on which to evalute the
99 * XPath
100 *
101 * @return the results of all the XPath evaluations as a single list
102 */
103 List selectNodes(Object context);
104
105 /***
106 * <p>
107 * <code>selectNodes</code> evaluates the XPath expression on the given
108 * {@link Node}or {@link List}of {@link Node}s and returns the result as
109 * a <code>List</code> of <code>Node</code> s sorted by the sort XPath
110 * expression.
111 * </p>
112 *
113 * @param context
114 * is either a node or a list of nodes on which to evalute the
115 * XPath
116 * @param sortXPath
117 * is the XPath expression to sort by
118 *
119 * @return a list of <code>Node</code> instances
120 */
121 List selectNodes(Object context, XPath sortXPath);
122
123 /***
124 * <p>
125 * <code>selectNodes</code> evaluates the XPath expression on the given
126 * {@link Node}or {@link List}of {@link Node}s and returns the result as
127 * a <code>List</code> of <code>Node</code> s sorted by the sort XPath
128 * expression.
129 * </p>
130 *
131 * @param context
132 * is either a node or a list of nodes on which to evalute the
133 * XPath
134 * @param sortXPath
135 * is the XPath expression to sort by
136 * @param distinct
137 * specifies whether or not duplicate values of the sort
138 * expression are allowed. If this parameter is true then only
139 * distinct sort expressions values are included in the result
140 *
141 * @return a list of <code>Node</code> instances
142 */
143 List selectNodes(Object context, XPath sortXPath, boolean distinct);
144
145 /***
146 * <p>
147 * <code>selectSingleNode</code> evaluates this XPath expression on the
148 * given {@link Node}or {@link List}of {@link Node}s and returns the
149 * result as a single <code>Node</code> instance.
150 * </p>
151 *
152 * @param context
153 * is either a node or a list of nodes on which to evalute the
154 * XPath
155 *
156 * @return a single matching <code>Node</code> instance
157 */
158 Node selectSingleNode(Object context);
159
160 /***
161 * <p>
162 * <code>valueOf</code> evaluates this XPath expression and returns the
163 * textual representation of the results using the XPath string() function.
164 * </p>
165 *
166 * @param context
167 * is either a node or a list of nodes on which to evalute the
168 * XPath
169 *
170 * @return the string representation of the results of the XPath expression
171 */
172 String valueOf(Object context);
173
174 /***
175 * <p>
176 * <code>numberValueOf</code> evaluates an XPath expression and returns
177 * the numeric value of the XPath expression if the XPath expression results
178 * is a number, or null if the result is not a number.
179 * </p>
180 *
181 * @param context
182 * is either a node or a list of nodes on which to evalute the
183 * XPath
184 *
185 * @return the numeric result of the XPath expression or null if the result
186 * is not a number.
187 */
188 Number numberValueOf(Object context);
189
190 /***
191 * Retrieve a boolean-value interpretation of this XPath expression when
192 * evaluated against a given context.
193 *
194 * <p>
195 * The boolean-value of the expression is determined per the
196 * <code>boolean(..)</code> core function as defined in the XPath
197 * specification. This means that an expression that selects zero nodes will
198 * return <code>false</code>, while an expression that selects
199 * one-or-more nodes will return <code>true</code>.
200 * </p>
201 *
202 * @param context
203 * The node, nodeset or Context object for evaluation. This value
204 * can be null
205 *
206 * @return The boolean-value interpretation of this expression.
207 *
208 * @since 1.5
209 */
210 boolean booleanValueOf(Object context);
211
212 /***
213 * <p>
214 * <code>sort</code> sorts the given List of Nodes using this XPath
215 * expression as a {@link java.util.Comparator}.
216 * </p>
217 *
218 * @param list
219 * is the list of Nodes to sort
220 */
221 void sort(List list);
222
223 /***
224 * <p>
225 * <code>sort</code> sorts the given List of Nodes using this XPath
226 * expression as a {@link java.util.Comparator}and optionally removing
227 * duplicates.
228 * </p>
229 *
230 * @param list
231 * is the list of Nodes to sort
232 * @param distinct
233 * if true then duplicate values (using the sortXPath for
234 * comparisions) will be removed from the List
235 */
236 void sort(List list, boolean distinct);
237
238 /***
239 * DOCUMENT ME!
240 *
241 * @return the current function context
242 */
243 FunctionContext getFunctionContext();
244
245 /***
246 * Sets the function context to be used when evaluating XPath expressions
247 *
248 * @param functionContext
249 * DOCUMENT ME!
250 */
251 void setFunctionContext(FunctionContext functionContext);
252
253 /***
254 * DOCUMENT ME!
255 *
256 * @return the current namespace context
257 */
258 NamespaceContext getNamespaceContext();
259
260 /***
261 * Sets the namespace context to be used when evaluating XPath expressions
262 *
263 * @param namespaceContext
264 * DOCUMENT ME!
265 */
266 void setNamespaceContext(NamespaceContext namespaceContext);
267
268 /***
269 * <p>
270 * Sets the current NamespaceContext from a Map where the keys are the
271 * String namespace prefixes and the values are the namespace URIs.
272 * </p>
273 *
274 * <p>
275 * For example:
276 *
277 * <pre>
278 * Map uris = new HashMap();
279 * uris.put("SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/");
280 * uris.put("m", "urn:xmethodsBabelFish");
281 * XPath xpath = document
282 * .createXPath("SOAP-ENV:Envelope/SOAP-ENV:Body/m:BabelFish");
283 * xpath.setNamespaceURIs(uris);
284 * Node babelfish = xpath.selectSingleNode(document);
285 * </pre>
286 *
287 * </p>
288 *
289 * @param map
290 * the map containing the namespace mappings
291 */
292 void setNamespaceURIs(Map map);
293
294 /***
295 * DOCUMENT ME!
296 *
297 * @return the current variable context
298 */
299 VariableContext getVariableContext();
300
301 /***
302 * Sets the variable context to be used when evaluating XPath expressions
303 *
304 * @param variableContext
305 * DOCUMENT ME!
306 */
307 void setVariableContext(VariableContext variableContext);
308 }
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345