View Javadoc

    1   package org.jaxen;
    2
    3   /*
    4    * $Header: /home/projects/jaxen/scm/jaxen/src/java/main/org/jaxen/Navigator.java,v 1.27 2005/09/23 23:49:20 elharo Exp $
    5    * $Revision: 1.27 $
    6    * $Date: 2005/09/23 23:49:20 $
    7    *
    8    * ====================================================================
    9    *
    10   * Copyright (C) 2000-2005 bob mcwhirter & James Strachan.
    11   * All rights reserved.
    12   *
    13   * Redistribution and use in source and binary forms, with or without
    14   * modification, are permitted provided that the following conditions
    15   * are met:
    16   *
    17   * 1. Redistributions of source code must retain the above copyright
    18   *    notice, this list of conditions, and the following disclaimer.
    19   *
    20   * 2. Redistributions in binary form must reproduce the above copyright
    21   *    notice, this list of conditions, and the disclaimer that follows
    22   *    these conditions in the documentation and/or other materials
    23   *    provided with the distribution.
    24   *
    25   * 3. The name "Jaxen" must not be used to endorse or promote products
    26   *    derived from this software without prior written permission.  For
    27   *    written permission, please contact license@jaxen.org.
    28   *
    29   * 4. Products derived from this software may not be called "Jaxen", nor
    30   *    may "Jaxen" appear in their name, without prior written permission
    31   *    from the Jaxen Project Management (pm@jaxen.org).
    32   *
    33   * In addition, we request (but do not require) that you include in the
    34   * end-user documentation provided with the redistribution and/or in the
    35   * software itself an acknowledgement equivalent to the following:
    36   *     "This product includes software developed by the
    37   *      Jaxen Project <http://www.jaxen.org/>."
    38   * Alternatively, the acknowledgment may be graphical using the logos
    39   * available at http://www.jaxen.org/
    40   *
    41   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
    42   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
    43   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    44   * DISCLAIMED.  IN NO EVENT SHALL THE Jaxen AUTHORS OR THE PROJECT
    45   * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    46   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    47   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
    48   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
    49   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
    50   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
    51   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    52   * SUCH DAMAGE.
    53   *
    54   * ====================================================================
    55   * This software consists of voluntary contributions made by many
    56   * individuals on behalf of the Jaxen Project and was originally
    57   * created by bob mcwhirter <bob@werken.com> and
    58   * James Strachan <jstrachan@apache.org>.  For more information on the
    59   * Jaxen Project, please see <http://www.jaxen.org/>.
    60   *
    61   * $Id: Navigator.java,v 1.27 2005/09/23 23:49:20 elharo Exp $
    62  */
    63
    64  import java.io.Serializable;
    65  import java.util.Iterator;
    66
    67  import org.jaxen.saxpath.SAXPathException;
    68
    69  /*** Interface for navigating around an arbitrary object
    70   *  model, using XPath semantics.
    71   *
    72   *  <p>
    73   *  There is a method to obtain a <code>java.util.Iterator</code>,
    74   *  for each axis specified by XPath.  If the target object model
    75   *  does not support the semantics of a particular axis, an
    76   *  {@link UnsupportedAxisException} is to be thrown. If there are
    77   *  no nodes on that axis, an empty iterator should be returned.
    78   *  </p>
    79   *
    80   *  @author <a href="mailto:bob@eng.werken.com">bob mcwhirter</a>
    81   *  @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
    82   *
    83   *  @version $Id: Navigator.java,v 1.27 2005/09/23 23:49:20 elharo Exp $
    84   */
    85  public interface Navigator extends Serializable
    86  {
    87      // ----------------------------------------------------------------------
    88      //     Axis Iterators
    89      // ----------------------------------------------------------------------
    90
    91      /*** Retrieve an <code>Iterator</code> matching the <code>child</code>
    92       *  XPath axis.
    93       *
    94       *  @param contextNode the original context node
    95       *
    96       *  @return an Iterator capable of traversing the axis, not null
    97       *
    98       *  @throws UnsupportedAxisException if the semantics of the child axis are
    99       *          not supported by this object model
    100      */
    101     Iterator getChildAxisIterator(Object contextNode)
    102         throws UnsupportedAxisException;
    103
    104     /*** Retrieve an <code>Iterator</code> matching the <code>descendant</code>
    105      *  XPath axis.
    106      *
    107      *  @param contextNode the original context node
    108      *
    109      *  @return an Iterator capable of traversing the axis, not null
    110      *
    111      *  @throws UnsupportedAxisException if the semantics of the desscendant axis are
    112      *          not supported by this object model
    113      */
    114     Iterator getDescendantAxisIterator(Object contextNode)
    115         throws UnsupportedAxisException;
    116
    117     /*** Retrieve an <code>Iterator</code> matching the <code>parent</code> XPath axis.
    118      *
    119      *  @param contextNode the original context node
    120      *
    121      *  @return an Iterator capable of traversing the axis, not null
    122      *
    123      *  @throws UnsupportedAxisException if the semantics of the parent axis are
    124      *          not supported by this object model
    125      */
    126     Iterator getParentAxisIterator(Object contextNode)
    127         throws UnsupportedAxisException;
    128
    129     /*** Retrieve an <code>Iterator</code> matching the <code>ancestor</code>
    130      *  XPath axis.
    131      *
    132      *  @param contextNode the original context node
    133      *
    134      *  @return an Iterator capable of traversing the axis, not null
    135      *
    136      *  @throws UnsupportedAxisException if the semantics of the ancestor axis are
    137      *          not supported by this object model
    138      */
    139     Iterator getAncestorAxisIterator(Object contextNode)
    140         throws UnsupportedAxisException;
    141
    142     /*** Retrieve an <code>Iterator</code> matching the
    143      *  <code>following-sibling</code> XPath axis.
    144      *
    145      *  @param contextNode the original context node
    146      *
    147      *  @return an Iterator capable of traversing the axis, not null
    148      *
    149      *  @throws UnsupportedAxisException if the semantics of the following-sibling axis are
    150      *          not supported by this object model
    151      */
    152     Iterator getFollowingSiblingAxisIterator(Object contextNode)
    153         throws UnsupportedAxisException;
    154
    155     /*** Retrieve an <code>Iterator</code> matching the
    156      *  <code>preceding-sibling</code> XPath axis.
    157      *
    158      *  @param contextNode the original context node
    159      *
    160      *  @return an Iterator capable of traversing the axis, not null
    161      *
    162      *  @throws UnsupportedAxisException if the semantics of the preceding-sibling axis are
    163      *          not supported by this object model
    164      */
    165     Iterator getPrecedingSiblingAxisIterator(Object contextNode)
    166         throws UnsupportedAxisException;
    167
    168     /*** Retrieve an <code>Iterator</code> matching the <code>following</code>
    169      *  XPath axis.
    170      *
    171      *  @param contextNode the original context node
    172      *
    173      *  @return an Iterator capable of traversing the axis, not null
    174      *
    175      *  @throws UnsupportedAxisException if the semantics of the following axis are
    176      *          not supported by this object model
    177      */
    178     Iterator getFollowingAxisIterator(Object contextNode)
    179         throws UnsupportedAxisException;
    180
    181     /*** Retrieve an <code>Iterator</code> matching the <code>preceding</code> XPath axis.
    182      *
    183      *  @param contextNode the original context node
    184      *
    185      *  @return an Iterator capable of traversing the axis, not null
    186      *
    187      *  @throws UnsupportedAxisException if the semantics of the preceding axis are
    188      *          not supported by this object model
    189      */
    190     Iterator getPrecedingAxisIterator(Object contextNode)
    191         throws UnsupportedAxisException;
    192
    193     /*** Retrieve an <code>Iterator</code> matching the <code>attribute</code>
    194      *  XPath axis.
    195      *
    196      *  @param contextNode the original context node
    197      *
    198      *  @return an Iterator capable of traversing the axis, not null
    199      *
    200      *  @throws UnsupportedAxisException if the semantics of the attribute axis are
    201      *          not supported by this object model
    202      */
    203     Iterator getAttributeAxisIterator(Object contextNode)
    204         throws UnsupportedAxisException;
    205
    206     /*** Retrieve an <code>Iterator</code> matching the <code>namespace</code>
    207      *  XPath axis.
    208      *
    209      *  @param contextNode the original context node
    210      *
    211      *  @return an Iterator capable of traversing the axis, not null
    212      *
    213      *  @throws UnsupportedAxisException if the semantics of the namespace axis are
    214      *          not supported by this object model
    215      */
    216     Iterator getNamespaceAxisIterator(Object contextNode)
    217         throws UnsupportedAxisException;
    218
    219     /*** Retrieve an <code>Iterator</code> matching the <code>self</code> XPath
    220      *  axis.
    221      *
    222      *  @param contextNode the original context node
    223      *
    224      *  @return an Iterator capable of traversing the axis, not null
    225      *
    226      *  @throws UnsupportedAxisException if the semantics of the self axis are
    227      *          not supported by this object model
    228      */
    229     Iterator getSelfAxisIterator(Object contextNode)
    230         throws UnsupportedAxisException;
    231
    232     /*** Retrieve an <code>Iterator</code> matching the
    233      *  <code>descendant-or-self</code> XPath axis.
    234      *
    235      *  @param contextNode the original context node
    236      *
    237      *  @return an Iterator capable of traversing the axis, not null
    238      *
    239      *  @throws UnsupportedAxisException if the semantics of the descendant-or-self axis are
    240      *          not supported by this object model
    241      */
    242     Iterator getDescendantOrSelfAxisIterator(Object contextNode)
    243         throws UnsupportedAxisException;
    244
    245     /*** Retrieve an <code>Iterator</code> matching the
    246      *  <code>ancestor-or-self</code> XPath axis.
    247      *
    248      *  @param contextNode the original context node
    249      *
    250      *  @return an Iterator capable of traversing the axis, not null
    251      *
    252      *  @throws UnsupportedAxisException if the semantics of the ancestor-or-self axis are
    253      *          not supported by this object model
    254      */
    255     Iterator getAncestorOrSelfAxisIterator(Object contextNode)
    256         throws UnsupportedAxisException;
    257
    258     // ----------------------------------------------------------------------
    259     //     Extractors
    260     // ----------------------------------------------------------------------
    261
    262     /*** Loads a document from the given URI
    263      *
    264      *  @param uri the URI of the document to load
    265      *
    266      *  @return the document
    267      *
    268       * @throws FunctionCallException if the document could not be loaded
    269      */
    270     Object getDocument(String uri)
    271         throws FunctionCallException;
    272
    273     /*** Returns the document node that contains the given context node.
    274      *
    275      *  @see #isDocument(Object)
    276      *
    277      *  @param contextNode the context node
    278      *
    279      *  @return the document of the context node
    280      */
    281     Object getDocumentNode(Object contextNode);
    282
    283     /*** Returns the parent of the given context node.
    284      *
    285      *  <p>
    286      *  The parent of any node must either be a document
    287      *  node or an element node.
    288      *  </p>
    289      *
    290      *  @see #isDocument
    291      *  @see #isElement
    292      *
    293      *  @param contextNode the context node
    294      *
    295      *  @return the parent of the context node, or null if this is a document node.
    296      *
    297      *  @throws UnsupportedAxisException if the parent axis is not
    298      *          supported by the model
    299      */
    300     Object getParentNode(Object contextNode)
    301         throws UnsupportedAxisException;
    302
    303     /*** Retrieve the namespace URI of the given element node.
    304      *
    305      *  @param element the context element node
    306      *
    307      *  @return the namespace URI of the element node
    308      */
    309     String getElementNamespaceUri(Object element);
    310
    311     /*** Retrieve the name of the given element node.
    312      *
    313      *  @param element the context element node
    314      *
    315      *  @return the name of the element node
    316      */
    317     String getElementName(Object element);
    318
    319     /*** Retrieve the QName of the given element node.
    320      *
    321      *  @param element the context element node
    322      *
    323      *  @return the QName of the element node
    324      */
    325     String getElementQName(Object element);
    326
    327     /*** Retrieve the namespace URI of the given attribute node.
    328      *
    329      *  @param attr the context attribute node
    330      *
    331      *  @return the namespace URI of the attribute node
    332      */
    333     String getAttributeNamespaceUri(Object attr);
    334
    335     /*** Retrieve the name of the given attribute node.
    336      *
    337      *  @param attr the context attribute node
    338      *
    339      *  @return the name of the attribute node
    340      */
    341     String getAttributeName(Object attr);
    342
    343     /*** Retrieve the QName of the given attribute node.
    344      *
    345      *  @param attr the context attribute node
    346      *
    347      *  @return the qualified name of the attribute node
    348      */
    349     String getAttributeQName(Object attr);
    350
    351     /*** Retrieve the target of a processing-instruction.
    352      *
    353      *  @param pi the context processing-instruction node
    354      *
    355      *  @return the target of the processing-instruction node
    356      */
    357     String getProcessingInstructionTarget(Object pi);
    358
    359     /*** Retrieve the data of a processing-instruction.
    360      *
    361      *  @param pi the context processing-instruction node
    362      *
    363      *  @return the data of the processing-instruction node
    364      */
    365     String getProcessingInstructionData(Object pi);
    366
    367     // ----------------------------------------------------------------------
    368     //     isXXX testers
    369     // ----------------------------------------------------------------------
    370
    371     /*** Returns whether the given object is a document node. A document node
    372      *  is the node that is selected by the XPath expression <code>/</code>.
    373      *
    374      *  @param object the object to test
    375      *
    376      *  @return <code>true</code> if the object is a document node,
    377      *          else <code>false</code>
    378      */
    379     boolean isDocument(Object object);
    380
    381     /*** Returns whether the given object is an element node.
    382      *
    383      *  @param object the object to test
    384      *
    385      *  @return <code>true</code> if the object is an element node,
    386      *          else <code>false</code>
    387      */
    388     boolean isElement(Object object);
    389
    390     /*** Returns whether the given object is an attribute node.
    391      *
    392      *  @param object the object to test
    393      *
    394      *  @return <code>true</code> if the object is an attribute node,
    395      *          else <code>false</code>
    396      */
    397     boolean isAttribute(Object object);
    398
    399     /*** Returns whether the given object is a namespace node.
    400      *
    401      *  @param object the object to test
    402      *
    403      *  @return <code>true</code> if the object is a namespace node,
    404      *          else <code>false</code>
    405      */
    406     boolean isNamespace(Object object);
    407
    408     /*** Returns whether the given object is a comment node.
    409      *
    410      *  @param object the object to test
    411      *
    412      *  @return <code>true</code> if the object is a comment node,
    413      *          else <code>false</code>
    414      */
    415     boolean isComment(Object object);
    416
    417     /*** Returns whether the given object is a text node.
    418      *
    419      *  @param object the object to test
    420      *
    421      *  @return <code>true</code> if the object is a text node,
    422      *          else <code>false</code>
    423      */
    424     boolean isText(Object object);
    425
    426     /*** Returns whether the given object is a processing-instruction node.
    427      *
    428      *  @param object the object to test
    429      *
    430      *  @return <code>true</code> if the object is a processing-instruction node,
    431      *          else <code>false</code>
    432      */
    433     boolean isProcessingInstruction(Object object);
    434
    435     // ----------------------------------------------------------------------
    436     //     String-Value extractors
    437     // ----------------------------------------------------------------------
    438
    439     /*** Retrieve the string-value of a comment node.
    440      * This may be the empty string if the comment is empty,
    441      * but must not be null.
    442      *
    443      *  @param comment the comment node
    444      *
    445      *  @return the string-value of the node
    446      */
    447     String getCommentStringValue(Object comment);
    448
    449     /*** Retrieve the string-value of an element node.
    450      * This may be the empty string if the element is empty,
    451      * but must not be null.
    452      *
    453      *  @param element the comment node.
    454      *
    455      *  @return the string-value of the node.
    456      */
    457     String getElementStringValue(Object element);
    458
    459     /*** Retrieve the string-value of an attribute node.
    460      *  This should be the XML 1.0 normalized attribute value.
    461      *  This may be the empty string but must not be null.
    462      *
    463      *  @param attr the attribute node
    464      *
    465      *  @return the string-value of the node
    466      */
    467     String getAttributeStringValue(Object attr);
    468
    469     /*** Retrieve the string-value of a namespace node.
    470      * This is generally the namespace URI.
    471      * This may be the empty string but must not be null.
    472      *
    473      *  @param ns the namespace node
    474      *
    475      *  @return the string-value of the node
    476      */
    477     String getNamespaceStringValue(Object ns);
    478
    479     /*** Retrieve the string-value of a text node.
    480      * This must not be null and should not be the empty string.
    481      * The XPath data model does not allow empty text nodes.
    482      *
    483      *  @param text the text node
    484      *
    485      *  @return the string-value of the node
    486      */
    487     String getTextStringValue(Object text);
    488
    489     // ----------------------------------------------------------------------
    490     //     General utilities
    491     // ----------------------------------------------------------------------
    492
    493     /*** Retrieve the namespace prefix of a namespace node.
    494      *
    495      *  @param ns the namespace node
    496      *
    497      *  @return the prefix associated with the node
    498      */
    499     String getNamespacePrefix(Object ns);
    500
    501
    502     /*** Translate a namespace prefix to a namespace URI, <b>possibly</b>
    503      *  considering a particular element node.
    504      *
    505      *  <p>
    506      *  Strictly speaking, prefix-to-URI translation should occur
    507      *  irrespective of any element in the document.  This method
    508      *  is provided to allow a non-conforming ease-of-use enhancement.
    509      *  </p>
    510      *
    511      *  @see NamespaceContext
    512      *
    513      *  @param prefix the prefix to translate
    514      *  @param element the element to consider during translation
    515      *
    516      *  @return the namespace URI associated with the prefix
    517      */
    518     String translateNamespacePrefixToUri(String prefix,
    519                                          Object element);
    520
    521     /*** Returns a parsed form of the given XPath string, which will be suitable
    522      *  for queries on documents that use the same navigator as this one.
    523      *
    524      *  @see XPath
    525      *
    526      *  @param xpath the XPath expression
    527      *
    528      *  @return a new XPath expression object
    529      *
    530      *  @throws SAXPathException if the string is not a syntactically
    531      *      correct XPath expression
    532      */
    533     XPath parseXPath(String xpath) throws SAXPathException;
    534
    535     /***
    536      *  Returns the element whose ID is given by elementId.
    537      *  If no such element exists, returns null.
    538      *  Attributes with the name "ID" are not of type ID unless so defined.
    539      *  Implementations that do not know whether attributes are of type ID or
    540      *  not are expected to return null.
    541      *
    542      *  @param contextNode   a node from the document in which to look for the
    543      *                       id
    544      *  @param elementId   id to look for
    545      *
    546      *  @return   element whose ID is given by elementId, or null if no such
    547      *            element exists in the document or if the implementation
    548      *            does not know about attribute types
    549      */
    550     Object getElementById(Object contextNode,
    551                           String elementId);
    552
    553     /*** Returns a number that identifies the type of node that the given
    554      *  object represents in this navigator.
    555      *
    556      * @param node ????
    557      * @return ????
    558      *
    559      *  @see org.jaxen.pattern.Pattern
    560      */
    561     short getNodeType(Object node);
    562 }