001/*
002 * Copyright 2001 (C) MetaStuff, Ltd. All Rights Reserved.
003 * 
004 * This software is open source. 
005 * See the bottom of this file for the licence.
006 * 
007 * $Id: XPath.java,v 1.11 2002/03/13 03:29:55 jstrachan Exp $
008 */
009
010package org.dom4j;
011
012import java.util.Comparator;
013import java.util.List;
014import java.util.Map;
015
016import org.jaxen.FunctionContext;
017import org.jaxen.NamespaceContext;
018import org.jaxen.VariableContext;
019
020/** <p><code>XPath</code> represents an XPath expression after 
021  * it has been parsed from a String.</p>
022  *
023  * @author <a href="mailto:james.strachan@metastuff.com">James Strachan</a>
024  * @version $Revision: 1.11 $
025  */
026public interface XPath extends NodeFilter {
027
028    /** <p><code>getText</code> will return the textual version of 
029      * the XPath expression.</p>
030      *
031      * @return the textual format of the XPath expression.
032      */
033    public String getText();
034
035    
036    /** <p><code>matches</code> returns true if the given node matches 
037      * the XPath expression. To be more precise when evaluating this XPath
038      * expression on the given node the result set must include the node.</p>
039      *
040      * @return true if the given node matches this XPath expression
041      */
042    public boolean matches(Node node);
043
044    /** <p><code>evaluate</code> evaluates an XPath expression and returns 
045      * the result as an {@link Object}. The object returned can
046      * either be a {@link List} of {@link Node} instances, a {@link Node} 
047      * instance, a {@link String} or a {@link Number} instance depending on 
048      * the XPath expression. 
049      *
050      * @param context is either a node or a list of nodes on which to 
051      *    evalute the XPath
052      * @return the value of the XPath expression as a
053      * {@link List} of {@link Node} instances, a {@link Node} 
054      * instance, a {@link String} or a {@link Number} instance depending on 
055      * the XPath expression. 
056      */
057    public Object evaluate(Object context);
058
059    /** <p><code>selectObject</code> evaluates an XPath expression and returns 
060      * the result as an {@link Object}. The object returned can
061      * either be a {@link List} of {@link Node} instances, a {@link Node} 
062      * instance, a {@link String} or a {@link Number} instance depending on 
063      * the XPath expression. 
064      *
065      * @param context is either a node or a list of nodes on which to 
066      *    evalute the XPath
067      * @return the value of the XPath expression as a
068      * {@link List} of {@link Node} instances, a {@link Node} 
069      * instance, a {@link String} or a {@link Number} instance depending on 
070      * the XPath expression. 
071      *
072      * @deprecated please use evaluate(Object) instead.
073      */
074    public Object selectObject(Object context);
075
076    /** <p><code>selectNodes</code> performs this XPath expression
077      * on the given {@link Node} or {@link List} of {@link Node}s 
078      * instances appending all the results together into a single list.</p>
079      *
080      * @param context is either a node or a list of nodes on which to 
081      *    evalute the XPath
082      * @return the results of all the XPath evaluations as a single list
083      */
084    public List selectNodes(Object context);
085    
086    
087    /** <p><code>selectNodes</code> evaluates the XPath expression
088      * on the given {@link Node} or {@link List} of {@link Node}s 
089      * and returns the result as a <code>List</code> of 
090      * <code>Node</code>s sorted by the sort XPath expression.</p>
091      *
092      * @param context is either a node or a list of nodes on which to 
093      *    evalute the XPath
094      * @param sortXPath is the XPath expression to sort by
095      * @return a list of <code>Node</code> instances 
096      */
097    public List selectNodes(Object context, XPath sortXPath);
098    
099    /** <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 in 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    /** <p><code>sort</code> sorts the given List of Nodes
148      * using this XPath expression as a {@link Comparator}.</p>
149      *
150      * @param list is the list of Nodes to sort
151      */
152    public void sort( List list );
153    
154    /** <p><code>sort</code> sorts the given List of Nodes
155      * using this XPath expression as a {@link Comparator} 
156      * and optionally removing duplicates.</p>
157      *
158      * @param list is the list of Nodes to sort
159      * @param distinct if true then duplicate values (using the sortXPath for 
160      *     comparisions) will be removed from the List
161      */
162    public void sort( List list, boolean distinct );
163    
164    
165    /** @return the current function context
166      */
167    public FunctionContext getFunctionContext();
168    
169    /** Sets the function context to be used when evaluating XPath
170      * expressions
171      */
172    public void setFunctionContext(FunctionContext functionContext);
173    
174    /** @return the current namespace context
175      */
176    public NamespaceContext getNamespaceContext();
177    
178    /** Sets the namespace context to be used when evaluating XPath
179      * expressions
180      */
181    public void setNamespaceContext(NamespaceContext namespaceContext);
182    
183    /** Sets the current NamespaceContext from a Map where the keys
184      * are the String namespace prefixes and the values are the namespace
185      * URIs For example.<br>
186      *
187      * <pre>
188      * Map uris = new HashMap();<br/>
189      * uris.put( "SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/" );<br/>
190      * uris.put( "m", "urn:xmethodsBabelFish" );<br/>
191      * XPath xpath = document.createXPath( "/SOAP-ENV:Envelope/SOAP-ENV:Body/m:BabelFish" );<br/>
192      * xpath.setNamespaceURIs( uris );<br/>
193      * Node babelfish = xpath.selectSingleNode( document );<br/>
194      * </pre>
195      *
196      */
197    public void setNamespaceURIs(Map map);
198    
199    /** @return the current variable context
200      */
201    public VariableContext getVariableContext();
202    
203    /** Sets the variable context to be used when evaluating XPath
204      * expressions
205      */
206    public void setVariableContext(VariableContext variableContext);
207    
208}
209
210
211
212
213/*
214 * Redistribution and use of this software and associated documentation
215 * ("Software"), with or without modification, are permitted provided
216 * that the following conditions are met:
217 *
218 * 1. Redistributions of source code must retain copyright
219 *    statements and notices.  Redistributions must also contain a
220 *    copy of this document.
221 *
222 * 2. Redistributions in binary form must reproduce the
223 *    above copyright notice, this list of conditions and the
224 *    following disclaimer in the documentation and/or other
225 *    materials provided with the distribution.
226 *
227 * 3. The name "DOM4J" must not be used to endorse or promote
228 *    products derived from this Software without prior written
229 *    permission of MetaStuff, Ltd.  For written permission,
230 *    please contact dom4j-info@metastuff.com.
231 *
232 * 4. Products derived from this Software may not be called "DOM4J"
233 *    nor may "DOM4J" appear in their names without prior written
234 *    permission of MetaStuff, Ltd. DOM4J is a registered
235 *    trademark of MetaStuff, Ltd.
236 *
237 * 5. Due credit should be given to the DOM4J Project
238 *    (http://dom4j.org/).
239 *
240 * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS
241 * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
242 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
243 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
244 * METASTUFF, LTD. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
245 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
246 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
247 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
248 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
249 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
250 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
251 * OF THE POSSIBILITY OF SUCH DAMAGE.
252 *
253 * Copyright 2001 (C) MetaStuff, Ltd. All Rights Reserved.
254 *
255 * $Id: XPath.java,v 1.11 2002/03/13 03:29:55 jstrachan Exp $
256 */