XPath


1   /*
2    * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
3    *
4    * This software is open source.
5    * See the bottom of this file for the licence.
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  * Redistribution and use of this software and associated documentation
312  * ("Software"), with or without modification, are permitted provided that the
313  * following conditions are met:
314  * 
315  * 1. Redistributions of source code must retain copyright statements and
316  * notices. Redistributions must also contain a copy of this document.
317  * 
318  * 2. Redistributions in binary form must reproduce the above copyright notice,
319  * this list of conditions and the following disclaimer in the documentation
320  * and/or other materials provided with the distribution.
321  * 
322  * 3. The name "DOM4J" must not be used to endorse or promote products derived
323  * from this Software without prior written permission of MetaStuff, Ltd. For
324  * written permission, please contact dom4j-info@metastuff.com.
325  * 
326  * 4. Products derived from this Software may not be called "DOM4J" nor may
327  * "DOM4J" appear in their names without prior written permission of MetaStuff,
328  * Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
329  * 
330  * 5. Due credit should be given to the DOM4J Project - http://www.dom4j.org
331  * 
332  * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND
333  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
334  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
335  * ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE
336  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
337  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
338  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
339  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
340  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
341  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
342  * POSSIBILITY OF SUCH DAMAGE.
343  * 
344  * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
345  */
346
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags