1 package org.jaxen; 2 3 /* 4 $Id$ 5 6 Copyright 2003 The Werken Company. All Rights Reserved. 7 8 Redistribution and use in source and binary forms, with or without 9 modification, are permitted provided that the following conditions are 10 met: 11 12 * Redistributions of source code must retain the above copyright 13 notice, this list of conditions and the following disclaimer. 14 15 * Redistributions in binary form must reproduce the above copyright 16 notice, this list of conditions and the following disclaimer in the 17 documentation and/or other materials provided with the distribution. 18 19 * Neither the name of the Jaxen Project nor the names of its 20 contributors may be used to endorse or promote products derived 21 from this software without specific prior written permission. 22 23 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 24 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 25 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 26 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 27 OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 28 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 29 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 30 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 31 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 32 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 33 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 34 35 */ 36 37 import java.util.List; 38 39 /** Represents an XPath 1.0 expression which 40 * can be evaluated against a variety of different XML object models. 41 * 42 * <p> 43 * Most of the evaluation methods take a context object. This is typically a 44 * node or node-set object (which is typically a <code>List</code> 45 * of node objects) or a Jaxen <code>Context</code> object. 46 * A null context is allowed, meaning that 47 * there are no XML nodes on which to evaluate. 48 * </p> 49 * 50 * @see org.jaxen.dom4j.Dom4jXPath XPath for dom4j 51 * @see org.jaxen.jdom.JDOMXPath XPath for JDOM 52 * @see org.jaxen.dom.DOMXPath XPath for W3C DOM 53 * 54 * @author <a href="mailto:bob@eng.werken.com">bob mcwhirter</a> 55 * @author <a href="mailto:jstrachan@apache.org">James Strachan</a> 56 */ 57 public interface XPath 58 { 59 // ---------------------------------------------------------------------- 60 // Basic Evaluation 61 // ---------------------------------------------------------------------- 62 63 /** Evaluate this XPath against the given context. 64 * 65 * <p> 66 * The context of evaluation my be a <em>document</em>, 67 * an <em>element</em>, or a set of <em>elements</em>. 68 * </p> 69 * 70 * <p> 71 * If the expression evaluates to an XPath string, number, or boolean 72 * type, then the equivalent Java object type is returned. 73 * Otherwise, if the result is a node-set, then the returned value is a 74 * <code>List</code>. 75 * </p> 76 * 77 * <p> 78 * When using this method, one must be careful to 79 * test the class of the returned objects, and of 80 * each of the composite members if a <code>List</code> 81 * is returned. If the returned members are XML nodes, 82 * they will be the actual <code>Document</code>, 83 * <code>Element</code> or <code>Attribute</code> objects 84 * as defined by the concrete XML object-model implementation, 85 * directly from the context document. This method <strong>does not 86 * return <em>copies</em> of anything</strong>. It merely returns 87 * references to nodes within the source document. 88 * </p> 89 * 90 * @param context the node, node-set or Context object for evaluation. 91 * This value can be null. 92 * 93 * @return the result of evaluating the XPath expression 94 * against the supplied context 95 * 96 * @throws JaxenException if an error occurs while attempting 97 * to evaluate the expression 98 */ 99 Object evaluate(Object context) throws JaxenException; 100 101 // ---------------------------------------------------------------------- 102 // Advanced Evaluation 103 // ---------------------------------------------------------------------- 104 105 /** Retrieve a string-value interpretation of this XPath 106 * expression when evaluated against the given context. 107 * 108 * <p> 109 * The string-value of the expression is determined per 110 * the <code>string(..)</code> core function as defined 111 * in the XPath specification. This means that an expression 112 * that selects more than one nodes will return the string value 113 * of the first node in the node set.. 114 * </p> 115 * 116 * @deprecated use {@link #stringValueOf(Object)} instead 117 * 118 * @param context the node, node-set or Context object for evaluation. 119 * This value can be null. 120 * 121 * @return the string-value of this expression 122 * 123 * @throws JaxenException if an error occurs while attempting 124 * to evaluate the expression 125 */ 126 String valueOf(Object context) 127 throws JaxenException; 128 129 /** Retrieve a string-value interpretation of this XPath 130 * expression when evaluated against the given context. 131 * 132 * <p> 133 * The string-value of the expression is determined per 134 * the <code>string(..)</code> core function as defined 135 * in the XPath specification. This means that an expression 136 * that selects more than one nodes will return the string value 137 * of the first node in the node set.. 138 * </p> 139 * 140 * @param context the node, node-set or Context object for evaluation. 141 * This value can be null 142 * 143 * @return the string-value interpretation of this expression 144 * 145 * @throws JaxenException if an error occurs while attempting 146 * to evaluate the expression 147 */ 148 String stringValueOf(Object context) 149 throws JaxenException; 150 151 /** Retrieve the boolean value of the first node in document order 152 * returned by this XPath expression when evaluated in 153 * the given context. 154 * 155 * <p> 156 * The boolean-value of the expression is determined per 157 * the <code>boolean()</code> function defined 158 * in the XPath specification. This means that an expression 159 * that selects zero nodes will return <code>false</code>, 160 * while an expression that selects one or more nodes will 161 * return <code>true</code>. An expression that returns a string 162 * returns false for empty strings and true for all other strings. 163 * An expression that returns a number 164 * returns false for zero and true for non-zero numbers. 165 * </p> 166 * 167 * @param context the node, node-set or Context object for evaluation. This value can be null. 168 * 169 * @return the boolean-value of this expression 170 * 171 * @throws JaxenException if an error occurs while attempting 172 * to evaluate the expression 173 */ 174 boolean booleanValueOf(Object context) 175 throws JaxenException; 176 177 178 /** Retrieve the number-value of the first node in document order 179 * returned by this XPath expression when evaluated in 180 * the given context. 181 * 182 * <p> 183 * The number-value of the expression is determined per 184 * the <code>number(..)</code> core function as defined 185 * in the XPath specification. This means that if this 186 * expression selects multiple nodes, the number-value 187 * of the first node is returned. 188 * </p> 189 * 190 * @param context the node, node-set or Context object for evaluation. This value can be null. 191 * 192 * @return the number-value interpretation of this expression 193 * 194 * @throws JaxenException if an error occurs while attempting 195 * to evaluate the expression 196 */ 197 Number numberValueOf(Object context) 198 throws JaxenException; 199 200 // ---------------------------------------------------------------------- 201 // Selection 202 // ---------------------------------------------------------------------- 203 204 /** Select all nodes that are selectable by this XPath 205 * expression. If multiple nodes match, multiple nodes 206 * will be returned. 207 * 208 * <p> 209 * <strong>NOTE:</strong> In most cases, nodes will be returned 210 * in document-order, as defined by the XML Canonicalization 211 * specification. The exception occurs when using XPath 212 * expressions involving the <code>union</code> operator 213 * (denoted with the pipe '|' character). 214 * </p> 215 * 216 * @see #selectSingleNode 217 * 218 * @param context the node, node-set or Context object for evaluation. 219 * This value can be null. 220 * 221 * @return the node-set of all items selected 222 * by this XPath expression. 223 * 224 * @throws JaxenException if an error occurs while attempting 225 * to evaluate the expression 226 */ 227 List selectNodes(Object context) 228 throws JaxenException; 229 230 /** 231 * <p> 232 * Return the first node in document order that is selected by this 233 * XPath expression. 234 * </p> 235 * 236 * @see #selectNodes 237 * 238 * @param context the node, node-set or Context object for evaluation. 239 * This value can be null. 240 * 241 * @return the first node in document order selected by this XPath expression 242 * 243 * @throws JaxenException if an error occurs while attempting 244 * to evaluate the expression 245 */ 246 Object selectSingleNode(Object context) 247 throws JaxenException; 248 249 // ---------------------------------------------------------------------- 250 // Helpers 251 // ---------------------------------------------------------------------- 252 253 /** Add a namespace prefix-to-URI mapping for this XPath 254 * expression. 255 * 256 * <p> 257 * Namespace prefix-to-URI mappings in an XPath are independent 258 * of those used within any document. Only the mapping explicitly 259 * added to this XPath will be available for resolving the 260 * XPath expression. 261 * </p> 262 * 263 * <p> 264 * This is a convenience method for adding mappings to the 265 * default {@link NamespaceContext} in place for this XPath. 266 * If you have installed a specific custom <code>NamespaceContext</code>, 267 * then this method will throw a <code>JaxenException</code>. 268 * </p> 269 * 270 * @param prefix the namespace prefix 271 * @param uri the namespace URI 272 * 273 * @throws JaxenException if a <code>NamespaceContext</code> 274 * used by this XPath has been explicitly installed 275 */ 276 void addNamespace(String prefix, 277 String uri) 278 throws JaxenException; 279 280 // ---------------------------------------------------------------------- 281 // Properties 282 // ---------------------------------------------------------------------- 283 284 /** Set a <code>NamespaceContext</code> for this 285 * XPath expression. 286 * 287 * <p> 288 * A <code>NamespaceContext</code> is responsible for translating 289 * namespace prefixes within the expression into namespace URIs. 290 * </p> 291 * 292 * @see NamespaceContext 293 * @see NamespaceContext#translateNamespacePrefixToUri 294 * 295 * @param namespaceContext the <code>NamespaceContext</code> to 296 * install for this expression 297 */ 298 void setNamespaceContext(NamespaceContext namespaceContext); 299 300 /** Set a <code>FunctionContext</code> for this XPath 301 * expression. 302 * 303 * <p> 304 * A <code>FunctionContext</code> is responsible for resolving 305 * all function calls used within the expression. 306 * </p> 307 * 308 * @see FunctionContext 309 * @see FunctionContext#getFunction 310 * 311 * @param functionContext the <code>FunctionContext</code> to 312 * install for this expression 313 */ 314 void setFunctionContext(FunctionContext functionContext); 315 316 /** Set a <code>VariableContext</code> for this XPath 317 * expression. 318 * 319 * <p> 320 * A <code>VariableContext</code> is responsible for resolving 321 * all variables referenced within the expression. 322 * </p> 323 * 324 * @see VariableContext 325 * @see VariableContext#getVariableValue 326 * 327 * @param variableContext the <code>VariableContext</code> to 328 * install for this expression. 329 */ 330 void setVariableContext(VariableContext variableContext); 331 332 /** Retrieve the <code>NamespaceContext</code> used by this XPath 333 * expression. 334 * 335 * <p> 336 * A <code>FunctionContext</code> is responsible for resolving 337 * all function calls used within the expression. 338 * </p> 339 * 340 * <p> 341 * If this XPath expression has not previously had a <code>NamespaceContext</code> 342 * installed, a new default <code>NamespaceContext</code> will be created, 343 * installed and returned. 344 * </p> 345 * 346 * @see NamespaceContext 347 * 348 * @return the <code>NamespaceContext</code> used by this expression 349 */ 350 NamespaceContext getNamespaceContext(); 351 352 /** Retrieve the <code>FunctionContext</code> used by this XPath 353 * expression. 354 * 355 * <p> 356 * A <code>FunctionContext</code> is responsible for resolving 357 * all function calls used within the expression. 358 * </p> 359 * 360 * <p> 361 * If this XPath expression has not previously had a <code>FunctionContext</code> 362 * installed, a new default <code>FunctionContext</code> will be created, 363 * installed and returned. 364 * </p> 365 * 366 * @see FunctionContext 367 * 368 * @return the <code>FunctionContext</code> used by this expression 369 */ 370 FunctionContext getFunctionContext(); 371 372 /** Retrieve the <code>VariableContext</code> used by this XPath 373 * expression. 374 * 375 * <p> 376 * A <code>VariableContext</code> is responsible for resolving 377 * all variables referenced within the expression. 378 * </p> 379 * 380 * <p> 381 * If this XPath expression has not previously had a <code>VariableContext</code> 382 * installed, a new default <code>VariableContext</code> will be created, 383 * installed and returned. 384 * </p> 385 * 386 * @see VariableContext 387 * 388 * @return the <code>VariableContext</code> used by this expression 389 */ 390 VariableContext getVariableContext(); 391 392 393 /** Retrieve the XML object-model-specific {@link Navigator} 394 * used to evaluate this XPath expression. 395 * 396 * @return the implementation-specific <code>Navigator</code> 397 */ 398 Navigator getNavigator(); 399 }