Clover coverage report - dom4j - 1.6.1
Coverage timestamp: ma mei 16 2005 14:23:01 GMT+01:00
file stats: LOC: 351   Methods: 0
NCLOC: 31   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
Branch.java - - - -
coverage
 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    */