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