View Javadoc

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