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