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.Iterator;
    11  import java.util.List;
    12
    13  /***
    14   * <p>
    15   * <code>Branch</code> interface defines the common behaviour for Nodes which
    16   * can contain child nodes (content) such as XML elements and documents. This
    17   * interface allows both elements and documents to be treated in a polymorphic
    18   * manner when changing or navigating child nodes (content).
    19   * </p>
    20   *
    21   * @author <a href="mailto:jstrachan@apache.org">James Strachan </a>
    22   * @version $Revision: 1.32 $
    23   */
    24  public interface Branch extends Node {
    25      /***
    26       * Returns the <code>Node</code> at the specified index position.
    27       *
    28       * @param index
    29       *            the index of the node to return.
    30       *
    31       * @return the <code>Node</code> at the specified position.
    32       *
    33       * @throws IndexOutOfBoundsException
    34       *             if the index is out of range (index &lt; 0 || index &gt;=
    35       *             {@link Branch#nodeCount()}).
    36       */
    37      Node node(int index) throws IndexOutOfBoundsException;
    38
    39      /***
    40       * Returns the index of the given node if it is a child node of this branch
    41       * or -1 if the given node is not a child node.
    42       *
    43       * @param node
    44       *            the content child node to find.
    45       *
    46       * @return the index of the given node starting at 0 or -1 if the node is
    47       *         not a child node of this branch
    48       */
    49      int indexOf(Node node);
    50
    51      /***
    52       * Returns the number of <code>Node</code> instances that this branch
    53       * contains.
    54       *
    55       * @return the number of nodes this branch contains
    56       */
    57      int nodeCount();
    58
    59      /***
    60       * Returns the element of the given ID attribute value. If this tree is
    61       * capable of understanding which attribute value should be used for the ID
    62       * then it should be used, otherwise this method should return null.
    63       *
    64       * @param elementID
    65       *            DOCUMENT ME!
    66       *
    67       * @return DOCUMENT ME!
    68       */
    69      Element elementByID(String elementID);
    70
    71      /***
    72       * <p>
    73       * Returns the content nodes of this branch as a backed {@link List}so that
    74       * the content of this branch may be modified directly using the
    75       * {@link List}interface. The <code>List</code> is backed by the
    76       * <code>Branch</code> so that changes to the list are reflected in the
    77       * branch and vice versa.
    78       * </p>
    79       *
    80       * @return the nodes that this branch contains as a <code>List</code>
    81       */
    82      List content();
    83
    84      /***
    85       * Returns an iterator through the content nodes of this branch
    86       *
    87       * @return an iterator through the content nodes of this branch
    88       */
    89      Iterator nodeIterator();
    90
    91      /***
    92       * Sets the contents of this branch as a <code>List</code> of
    93       * <code>Node</code> instances.
    94       *
    95       * @param content
    96       *            is the list of nodes to use as the content for this branch.
    97       */
    98      void setContent(List content);
    99
    100     /***
    101      * Appends the content of the given branch to this branch instance. This
    102      * method behaves like the {@link
    103      * java.util.Collection#addAll(java.util.Collection)} method.
    104      *
    105      * @param branch
    106      *            is the branch whose content will be added to me.
    107      */
    108     void appendContent(Branch branch);
    109
    110     /***
    111      * Clears the content for this branch, removing any <code>Node</code>
    112      * instances this branch may contain.
    113      */
    114     void clearContent();
    115
    116     /***
    117      * <p>
    118      * Returns a list of all the processing instructions in this branch. The
    119      * list is backed by this branch so that changes to the list will be
    120      * reflected in the branch but the reverse is not the case.
    121      * </p>
    122      *
    123      * @return a backed list of the processing instructions
    124      */
    125     List processingInstructions();
    126
    127     /***
    128      * <p>
    129      * Returns a list of the processing instructions for the given target. The
    130      * list is backed by this branch so that changes to the list will be
    131      * reflected in the branch but the reverse is not the case.
    132      * </p>
    133      *
    134      * @param target
    135      *            DOCUMENT ME!
    136      *
    137      * @return a backed list of the processing instructions
    138      */
    139     List processingInstructions(String target);
    140
    141     /***
    142      * DOCUMENT ME!
    143      *
    144      * @param target
    145      *            DOCUMENT ME!
    146      *
    147      * @return the processing instruction for the given target
    148      */
    149     ProcessingInstruction processingInstruction(String target);
    150
    151     /***
    152      * Sets all the processing instructions for this branch
    153      *
    154      * @param listOfPIs
    155      *            DOCUMENT ME!
    156      */
    157     void setProcessingInstructions(List listOfPIs);
    158
    159     /***
    160      * Adds a new <code>Element</code> node with the given name to this branch
    161      * and returns a reference to the new node.
    162      *
    163      * @param name
    164      *            is the name for the <code>Element</code> node.
    165      *
    166      * @return the newly added <code>Element</code> node.
    167      */
    168     Element addElement(String name);
    169
    170     /***
    171      * Adds a new <code>Element</code> node with the given {@link QName}to
    172      * this branch and returns a reference to the new node.
    173      *
    174      * @param qname
    175      *            is the qualified name for the <code>Element</code> node.
    176      *
    177      * @return the newly added <code>Element</code> node.
    178      */
    179     Element addElement(QName qname);
    180
    181     /***
    182      * Adds a new <code>Element</code> node with the given qualified name and
    183      * namespace URI to this branch and returns a reference to the new node.
    184      *
    185      * @param qualifiedName
    186      *            is the fully qualified name of the Element
    187      * @param namespaceURI
    188      *            is the URI of the namespace to use
    189      *
    190      * @return the newly added <code>Element</code> node.
    191      */
    192     Element addElement(String qualifiedName, String namespaceURI);
    193
    194     /***
    195      * Removes the processing instruction for the given target if it exists
    196      *
    197      * @param target
    198      *            DOCUMENT ME!
    199      *
    200      * @return true if a processing instruction was removed else false
    201      */
    202     boolean removeProcessingInstruction(String target);
    203
    204     /***
    205      * Adds the given <code>Node</code> or throws {@link IllegalAddException}
    206      * if the given node is not of a valid type. This is a polymorphic method
    207      * which will call the typesafe method for the node type such as
    208      * add(Element) or add(Comment).
    209      *
    210      * @param node
    211      *            is the given node to add
    212      */
    213     void add(Node node);
    214
    215     /***
    216      * Adds the given <code>Comment</code> to this branch. If the given node
    217      * already has a parent defined then an <code>IllegalAddException</code>
    218      * will be thrown.
    219      *
    220      * @param comment
    221      *            is the comment to be added
    222      */
    223     void add(Comment comment);
    224
    225     /***
    226      * Adds the given <code>Element</code> to this branch. If the given node
    227      * already has a parent defined then an <code>IllegalAddException</code>
    228      * will be thrown.
    229      *
    230      * @param element
    231      *            is the element to be added
    232      */
    233     void add(Element element);
    234
    235     /***
    236      * Adds the given <code>ProcessingInstruction</code> to this branch. If
    237      * the given node already has a parent defined then an
    238      * <code>IllegalAddException</code> will be thrown.
    239      *
    240      * @param pi
    241      *            is the processing instruction to be added
    242      */
    243     void add(ProcessingInstruction pi);
    244
    245     /***
    246      * Removes the given <code>Node</code> if the node is an immediate child
    247      * of this branch. If the given node is not an immediate child of this
    248      * branch then the {@link Node#detach()}method should be used instead. This
    249      * is a polymorphic method which will call the typesafe method for the node
    250      * type such as remove(Element) or remove(Comment).
    251      *
    252      * @param node
    253      *            is the given node to be removed
    254      *
    255      * @return true if the node was removed
    256      */
    257     boolean remove(Node node);
    258
    259     /***
    260      * Removes the given <code>Comment</code> if the node is an immediate
    261      * child of this branch. If the given node is not an immediate child of this
    262      * branch then the {@link Node#detach()}method should be used instead.
    263      *
    264      * @param comment
    265      *            is the comment to be removed
    266      *
    267      * @return true if the comment was removed
    268      */
    269     boolean remove(Comment comment);
    270
    271     /***
    272      * Removes the given <code>Element</code> if the node is an immediate
    273      * child of this branch. If the given node is not an immediate child of this
    274      * branch then the {@link Node#detach()}method should be used instead.
    275      *
    276      * @param element
    277      *            is the element to be removed
    278      *
    279      * @return true if the element was removed
    280      */
    281     boolean remove(Element element);
    282
    283     /***
    284      * Removes the given <code>ProcessingInstruction</code> if the node is an
    285      * immediate child of this branch. If the given node is not an immediate
    286      * child of this branch then the {@link Node#detach()}method should be used
    287      * instead.
    288      *
    289      * @param pi
    290      *            is the processing instruction to be removed
    291      *
    292      * @return true if the processing instruction was removed
    293      */
    294     boolean remove(ProcessingInstruction pi);
    295
    296     /***
    297      * Puts all <code>Text</code> nodes in the full depth of the sub-tree
    298      * underneath this <code>Node</code>, including attribute nodes, into a
    299      * "normal" form where only structure (e.g., elements, comments, processing
    300      * instructions, CDATA sections, and entity references) separates
    301      * <code>Text</code> nodes, i.e., there are neither adjacent
    302      * <code>Text</code> nodes nor empty <code>Text</code> nodes. This can
    303      * be used to ensure that the DOM view of a document is the same as if it
    304      * were saved and re-loaded, and is useful when operations (such as XPointer
    305      * lookups) that depend on a particular document tree structure are to be
    306      * used.In cases where the document contains <code>CDATASections</code>,
    307      * the normalize operation alone may not be sufficient, since XPointers do
    308      * not differentiate between <code>Text</code> nodes and
    309      * <code>CDATASection</code> nodes.
    310      *
    311      * @since DOM Level 2
    312      */
    313     void normalize();
    314 }
    315
    316 /*
    317  * Redistribution and use of this software and associated documentation
    318  * ("Software"), with or without modification, are permitted provided that the
    319  * following conditions are met:
    320  *
    321  * 1. Redistributions of source code must retain copyright statements and
    322  * notices. Redistributions must also contain a copy of this document.
    323  *
    324  * 2. Redistributions in binary form must reproduce the above copyright notice,
    325  * this list of conditions and the following disclaimer in the documentation
    326  * and/or other materials provided with the distribution.
    327  *
    328  * 3. The name "DOM4J" must not be used to endorse or promote products derived
    329  * from this Software without prior written permission of MetaStuff, Ltd. For
    330  * written permission, please contact dom4j-info@metastuff.com.
    331  *
    332  * 4. Products derived from this Software may not be called "DOM4J" nor may
    333  * "DOM4J" appear in their names without prior written permission of MetaStuff,
    334  * Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
    335  *
    336  * 5. Due credit should be given to the DOM4J Project - http://www.dom4j.org
    337  *
    338  * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND
    339  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    340  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    341  * ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE
    342  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
    343  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
    344  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    345  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
    346  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    347  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    348  * POSSIBILITY OF SUCH DAMAGE.
    349  *
    350  * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
    351  */