View Javadoc

    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 }