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 */