| Clover coverage report - dom4j - 1.5 |
|
 |
|
|||||||||||||||||||
| Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
| Branch.java | - | - | - | - |
|
||||||||||||||
| 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 | * < 0 || index >= {@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 | */ |
|
||||||||||
