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