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