View Javadoc

1   /*
2    * Copyright 2001-2004 (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    * $Id: XPath.java,v 1.18 2004/06/25 12:34:47 maartenc Exp $
8    */
9   
10  package org.dom4j;
11  
12  import java.util.List;
13  import java.util.Map;
14  
15  import org.jaxen.FunctionContext;
16  import org.jaxen.NamespaceContext;
17  import org.jaxen.VariableContext;
18  
19  /*** <p><code>XPath</code> represents an XPath expression after 
20    * it has been parsed from a String.</p>
21    *
22    * @author <a href="mailto:james.strachan@metastuff.com">James Strachan</a>
23    * @version $Revision: 1.18 $
24    */
25  public interface XPath extends NodeFilter {
26  
27      /*** <p><code>getText</code> will return the textual version of 
28        * the XPath expression.</p>
29        *
30        * @return the textual format of the XPath expression.
31        */
32      public String getText();
33  
34      
35      /*** <p><code>matches</code> returns true if the given node matches 
36        * the XPath expression. To be more precise when evaluating this XPath
37        * expression on the given node the result set must include the node.</p>
38        *
39        * @return true if the given node matches this XPath expression
40        */
41      public boolean matches(Node node);
42  
43      /*** <p><code>evaluate</code> evaluates an XPath expression and returns 
44        * the result as an {@link Object}. The object returned can
45        * either be a {@link List} of {@link Node} instances, a {@link Node} 
46        * instance, a {@link String} or a {@link Number} instance depending on 
47        * the XPath expression. 
48        *
49        * @param context is either a node or a list of nodes on which to 
50        *    evalute the XPath
51        * @return the value of the XPath expression as a
52        * {@link List} of {@link Node} instances, a {@link Node} 
53        * instance, a {@link String} or a {@link Number} instance depending on 
54        * the XPath expression. 
55        */
56      public Object evaluate(Object context);
57  
58      /*** <p><code>selectObject</code> evaluates an XPath expression and returns 
59        * the result as an {@link Object}. The object returned can
60        * either be a {@link List} of {@link Node} instances, a {@link Node} 
61        * instance, a {@link String} or a {@link Number} instance depending on 
62        * the XPath expression. 
63        *
64        * @param context is either a node or a list of nodes on which to 
65        *    evalute the XPath
66        * @return the value of the XPath expression as a
67        * {@link List} of {@link Node} instances, a {@link Node} 
68        * instance, a {@link String} or a {@link Number} instance depending on 
69        * the XPath expression. 
70        *
71        * @deprecated please use evaluate(Object) instead.
72        *             WILL BE REMOVED IN dom4j-1.6 !!
73        */
74      public Object selectObject(Object context);
75  
76      /*** <p><code>selectNodes</code> performs this XPath expression
77        * on the given {@link Node} or {@link List} of {@link Node}s 
78        * instances appending all the results together into a single list.</p>
79        *
80        * @param context is either a node or a list of nodes on which to 
81        *    evalute the XPath
82        * @return the results of all the XPath evaluations as a single list
83        */
84      public List selectNodes(Object context);
85      
86      
87      /*** <p><code>selectNodes</code> evaluates the XPath expression
88        * on the given {@link Node} or {@link List} of {@link Node}s 
89        * and returns the result as a <code>List</code> of 
90        * <code>Node</code>s sorted by the sort XPath expression.</p>
91        *
92        * @param context is either a node or a list of nodes on which to 
93        *    evalute the XPath
94        * @param sortXPath is the XPath expression to sort by
95        * @return a list of <code>Node</code> instances 
96        */
97      public List selectNodes(Object context, XPath sortXPath);
98      
99      /*** <p><code>selectNodes</code> evaluates the XPath expression
100       * on the given {@link Node} or {@link List} of {@link Node}s 
101       * and returns the result as a <code>List</code> of 
102       * <code>Node</code>s sorted by the sort XPath expression.</p>
103       *
104       * @param context is either a node or a list of nodes on which to 
105       *    evalute the XPath
106       * @param sortXPath is the XPath expression to sort by
107       * @param distinct specifies whether or not duplicate values of the 
108       *     sort expression are allowed. If this parameter is true then only 
109       *     distinct sort expressions values are included in the result
110       * @return a list of <code>Node</code> instances 
111       */
112     public List selectNodes(Object context, XPath sortXPath, boolean distinct);
113     
114     
115     /*** <p><code>selectSingleNode</code> evaluates this XPath expression
116       * on the given {@link Node} or {@link List} of {@link Node}s 
117       * and returns the result as a single <code>Node</code> instance.</p>
118       *
119       * @param context is either a node or a list of nodes on which to 
120       *    evalute the XPath
121       * @return a single matching <code>Node</code> instance
122       */
123     public Node selectSingleNode(Object context);
124     
125     
126     /*** <p><code>valueOf</code> evaluates this XPath expression
127       * and returns the textual representation of the results using the 
128       * XPath string() function.</p>
129       *
130       * @param context is either a node or a list of nodes on which to 
131       *    evalute the XPath
132       * @return the string representation of the results of the XPath expression
133       */
134     public String valueOf(Object context);
135     
136     /*** <p><code>numberValueOf</code> evaluates an XPath expression
137       * and returns the numeric value of the XPath expression if the XPath
138       * expression results is a number, or null if the result is not a number.
139       *
140       * @param context is either a node or a list of nodes on which to 
141       *    evalute the XPath
142       * @return the numeric result of the XPath expression or null
143       * if the result is not a number.
144       */
145     public Number numberValueOf(Object context);
146 
147     /*** 
148      * Retrieve a boolean-value interpretation of this XPath
149      * expression when evaluated against a given context.
150      *
151      * <p>
152      * The boolean-value of the expression is determined per
153      * the <code>boolean(..)</code> core function as defined
154      * in the XPath specification.  This means that an expression
155      * that selects zero nodes will return <code>false</code>,
156      * while an expression that selects one-or-more nodes will
157      * return <code>true</code>.
158      * </p>
159      *
160      * @param context The node, nodeset or Context object for evaluation. This value can be null
161      * @return The boolean-value interpretation of this expression.
162      * @since 1.5
163      */
164     public boolean booleanValueOf(Object context);
165 
166     /*** <p><code>sort</code> sorts the given List of Nodes
167       * using this XPath expression as a {@link java.util.Comparator}.</p>
168       *
169       * @param list is the list of Nodes to sort
170       */
171     public void sort( List list );
172     
173     /*** <p><code>sort</code> sorts the given List of Nodes
174       * using this XPath expression as a {@link java.util.Comparator} 
175       * and optionally removing duplicates.</p>
176       *
177       * @param list is the list of Nodes to sort
178       * @param distinct if true then duplicate values (using the sortXPath for 
179       *     comparisions) will be removed from the List
180       */
181     public void sort( List list, boolean distinct );
182     
183     
184     /*** @return the current function context
185       */
186     public FunctionContext getFunctionContext();
187     
188     /*** Sets the function context to be used when evaluating XPath
189       * expressions
190       */
191     public void setFunctionContext(FunctionContext functionContext);
192     
193     /*** @return the current namespace context
194       */
195     public NamespaceContext getNamespaceContext();
196     
197     /*** Sets the namespace context to be used when evaluating XPath
198       * expressions
199       */
200     public void setNamespaceContext(NamespaceContext namespaceContext);
201     
202     /*** Sets the current NamespaceContext from a Map where the keys
203       * are the String namespace prefixes and the values are the namespace
204       * URIs For example.<br>
205       *
206       * <pre>
207       * Map uris = new HashMap();<br/>
208       * uris.put( "SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/" );<br/>
209       * uris.put( "m", "urn:xmethodsBabelFish" );<br/>
210       * XPath xpath = document.createXPath( "/SOAP-ENV:Envelope/SOAP-ENV:Body/m:BabelFish" );<br/>
211       * xpath.setNamespaceURIs( uris );<br/>
212       * Node babelfish = xpath.selectSingleNode( document );<br/>
213       * </pre>
214       *
215       */
216     public void setNamespaceURIs(Map map);
217     
218     /*** @return the current variable context
219       */
220     public VariableContext getVariableContext();
221     
222     /*** Sets the variable context to be used when evaluating XPath
223       * expressions
224       */
225     public void setVariableContext(VariableContext variableContext);
226     
227 }
228 
229 
230 
231 
232 /*
233  * Redistribution and use of this software and associated documentation
234  * ("Software"), with or without modification, are permitted provided
235  * that the following conditions are met:
236  *
237  * 1. Redistributions of source code must retain copyright
238  *    statements and notices.  Redistributions must also contain a
239  *    copy of this document.
240  *
241  * 2. Redistributions in binary form must reproduce the
242  *    above copyright notice, this list of conditions and the
243  *    following disclaimer in the documentation and/or other
244  *    materials provided with the distribution.
245  *
246  * 3. The name "DOM4J" must not be used to endorse or promote
247  *    products derived from this Software without prior written
248  *    permission of MetaStuff, Ltd.  For written permission,
249  *    please contact dom4j-info@metastuff.com.
250  *
251  * 4. Products derived from this Software may not be called "DOM4J"
252  *    nor may "DOM4J" appear in their names without prior written
253  *    permission of MetaStuff, Ltd. DOM4J is a registered
254  *    trademark of MetaStuff, Ltd.
255  *
256  * 5. Due credit should be given to the DOM4J Project - 
257  *    http://www.dom4j.org
258  *
259  * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS
260  * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
261  * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
262  * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
263  * METASTUFF, LTD. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
264  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
265  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
266  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
267  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
268  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
269  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
270  * OF THE POSSIBILITY OF SUCH DAMAGE.
271  *
272  * Copyright 2001-2004 (C) MetaStuff, Ltd. All Rights Reserved.
273  *
274  * $Id: XPath.java,v 1.18 2004/06/25 12:34:47 maartenc Exp $
275  */