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