001/* 002 * Copyright 2001 (C) MetaStuff, Ltd. All Rights Reserved. 003 * 004 * This software is open source. 005 * See the bottom of this file for the licence. 006 * 007 * $Id: Branch.java,v 1.24 2001/10/24 09:41:15 jstrachan Exp $ 008 */ 009 010package org.dom4j; 011 012import java.util.Collection; 013import java.util.Collections; 014import java.util.Iterator; 015import java.util.List; 016 017import org.xml.sax.Attributes; 018 019 020/** <p><code>Branch</code> interface defines the common behaviour 021 * for Nodes which can contain child nodes (content) such as 022 * XML elements and documents. 023 * This interface allows both elements and documents to be treated in a 024 * polymorphic manner when changing or navigating child nodes (content).</p> 025 * 026 * @author <a href="mailto:jstrachan@apache.org">James Strachan</a> 027 * @version $Revision: 1.24 $ 028 */ 029public interface Branch extends Node { 030 031 /** Returns the <code>Node</code> at the specified index position. 032 * 033 * @param index the index of the node to return. 034 * @return the <code>Node</code> at the specified position. 035 * 036 * @throws IndexOutOfBoundsException if the index is out of range (index 037 * < 0 || index >= {@link #nodeCount}). 038 */ 039 public Node node(int index); 040 041 /** Returns the index of the given node if it is a child node of this 042 * branch or -1 if the given node is not a child node. 043 * 044 * @param node the content child node to find. 045 * @return the index of the given node starting at 0 or -1 if the node 046 * is not a child node of this branch 047 */ 048 public int indexOf(Node node); 049 050 /** Returns the number of <code>Node</code> instances that this branch 051 * contains. 052 * 053 * @return the number of nodes this branch contains 054 */ 055 public int nodeCount(); 056 057 /** Returns the element of the given ID attribute value. If this tree 058 * is capable of understanding which attribute value should be used for 059 * the ID then it should be used, otherwise this method should return null. 060 */ 061 public Element elementByID(String elementID); 062 063 064 /** <p>Returns the content nodes of this branch as a backed {@link List} 065 * so that the content of this branch may be modified directly using 066 * the {@link List} interface. 067 * The <code>List</code> is backed by the <code>Branch</code> so that 068 * changes to the list are reflected in the branch and vice versa.</p> 069 * 070 * @return the nodes that this branch contains as a <code>List</code> 071 */ 072 public List content(); 073 074 /** Returns an iterator through the content nodes of this branch 075 * 076 * @return an iterator through the content nodes of this branch 077 */ 078 public Iterator nodeIterator(); 079 080 /** Sets the contents of this branch as a <code>List</code> of 081 * <code>Node</code> instances. 082 * 083 * @param content is the list of nodes to use as the content for this 084 * branch. 085 */ 086 public void setContent(List content); 087 088 /** Appends the content of the given branch to this branch instance. 089 * This method behaves like the {@link Collection#addAll(java.util.Collection)} 090 * method. 091 * 092 * @param element is the element whose content will be added to me. 093 */ 094 public void appendContent(Branch branch); 095 096 /** Clears the content for this branch, removing any <code>Node</code> 097 * instances this branch may contain. 098 */ 099 public void clearContent(); 100 101 /** <p>Returns a list of all the processing instructions in this branch. 102 * The list is backed by this branch so that changes to the list will 103 * be reflected in the branch but the reverse is not the case.</p> 104 * 105 * @return a backed list of the processing instructions 106 */ 107 public List processingInstructions(); 108 109 /** <p>Returns a list of the processing instructions for the given target. 110 * The list is backed by this branch so that changes to the list will 111 * be reflected in the branch but the reverse is not the case.</p> 112 * 113 * @return a backed list of the processing instructions 114 */ 115 public List processingInstructions(String target); 116 117 /** @return the processing instruction for the given target 118 */ 119 public ProcessingInstruction processingInstruction(String target); 120 121 /** Sets all the processing instructions for this branch 122 */ 123 public void setProcessingInstructions(List listOfPIs); 124 125 126 /** Adds a new <code>Element</code> node with the given name to this branch 127 * and returns a reference to the new node. 128 * 129 * @param name is the name for the <code>Element</code> node. 130 * @return the newly added <code>Element</code> node. 131 */ 132 public Element addElement(String name); 133 134 /** Adds a new <code>Element</code> node with the given {@link QName} 135 * to this branch and returns a reference to the new node. 136 * 137 * @param qname is the qualified name for the <code>Element</code> node. 138 * @return the newly added <code>Element</code> node. 139 */ 140 public Element addElement(QName qname); 141 142 /** Adds a new <code>Element</code> node with the given qualified name 143 * and namespace URI to this branch and returns a reference to the new node. 144 * 145 * @param qualifiedName is the fully qualified name of the Element 146 * @param namespaceURI is the URI of the namespace to use 147 * @return the newly added <code>Element</code> node. 148 */ 149 public Element addElement(String qualifiedName, String namespaceURI); 150 151 /** Removes the processing instruction for the given target if it exists 152 * 153 * @return true if a processing instruction was removed else false 154 */ 155 public boolean removeProcessingInstruction(String target); 156 157 158 159 /** Adds the given <code>Node</code> or throws {@link IllegalAddException} 160 * if the given node is not of a valid type. This is a polymorphic method 161 * which will call the typesafe method for the node type such as 162 * add(Element) or add(Comment). 163 * 164 * @param node is the given node to add 165 */ 166 public void add(Node node); 167 168 /** Adds the given <code>Comment</code> to this branch. 169 * If the given node already has a parent defined then an 170 * <code>InvalidAddNodeException</code> will be thrown. 171 * 172 * @param comment is the comment to be added 173 */ 174 public void add(Comment comment); 175 176 /** Adds the given <code>Element</code> to this branch. 177 * If the given node already has a parent defined then an 178 * <code>InvalidAddNodeException</code> will be thrown. 179 * 180 * @param element is the element to be added 181 */ 182 public void add(Element element); 183 184 /** Adds the given <code>ProcessingInstruction</code> to this branch. 185 * If the given node already has a parent defined then an 186 * <code>InvalidAddNodeException</code> will be thrown. 187 * 188 * @param pi is the processing instruction to be added 189 */ 190 public void add(ProcessingInstruction pi); 191 192 /** Removes the given <code>Node</code> if the node is 193 * an immediate child of this branch. 194 * 195 * If the given node is not an immediate child of this branch 196 * then the {@link Node#detach()} method should be used instead. 197 * 198 * This is a polymorphic method which will call the typesafe method 199 * for the node type such as remove(Element) or remove(Comment). 200 * 201 * @param node is the given node to be removed 202 * @return true if the node was removed 203 */ 204 public boolean remove(Node node); 205 206 /** Removes the given <code>Comment</code> if the node is 207 * an immediate child of this branch. 208 * 209 * If the given node is not an immediate child of this branch 210 * then the {@link Node#detach()} method should be used instead. 211 * 212 * @param comment is the comment to be removed 213 * @return true if the comment was removed 214 */ 215 public boolean remove(Comment comment); 216 217 /** Removes the given <code>Element</code> if the node is 218 * an immediate child of this branch. 219 * 220 * If the given node is not an immediate child of this branch 221 * then the {@link Node#detach()} method should be used instead. 222 * 223 * @param element is the element to be removed 224 * @return true if the element was removed 225 */ 226 public boolean remove(Element element); 227 228 /** Removes the given <code>ProcessingInstruction</code> if the node is 229 * an immediate child of this branch. 230 * 231 * If the given node is not an immediate child of this branch 232 * then the {@link Node#detach()} method should be used instead. 233 * 234 * @param pi is the processing instruction to be removed 235 * @return true if the processing instruction was removed 236 */ 237 public boolean remove(ProcessingInstruction pi); 238 239 240 /** 241 * Puts all <code>Text</code> nodes in the full depth of the sub-tree 242 * underneath this <code>Node</code>, including attribute nodes, into a 243 * "normal" form where only structure (e.g., elements, comments, 244 * processing instructions, CDATA sections, and entity references) 245 * separates <code>Text</code> nodes, i.e., there are neither adjacent 246 * <code>Text</code> nodes nor empty <code>Text</code> nodes. This can 247 * be used to ensure that the DOM view of a document is the same as if 248 * it were saved and re-loaded, and is useful when operations (such as 249 * XPointer lookups) that depend on a particular document tree 250 * structure are to be used.In cases where the document contains 251 * <code>CDATASections</code>, the normalize operation alone may not be 252 * sufficient, since XPointers do not differentiate between 253 * <code>Text</code> nodes and <code>CDATASection</code> nodes. 254 * @version DOM Level 2 255 */ 256 public void normalize(); 257} 258 259 260 261 262/* 263 * Redistribution and use of this software and associated documentation 264 * ("Software"), with or without modification, are permitted provided 265 * that the following conditions are met: 266 * 267 * 1. Redistributions of source code must retain copyright 268 * statements and notices. Redistributions must also contain a 269 * copy of this document. 270 * 271 * 2. Redistributions in binary form must reproduce the 272 * above copyright notice, this list of conditions and the 273 * following disclaimer in the documentation and/or other 274 * materials provided with the distribution. 275 * 276 * 3. The name "DOM4J" must not be used to endorse or promote 277 * products derived from this Software without prior written 278 * permission of MetaStuff, Ltd. For written permission, 279 * please contact dom4j-info@metastuff.com. 280 * 281 * 4. Products derived from this Software may not be called "DOM4J" 282 * nor may "DOM4J" appear in their names without prior written 283 * permission of MetaStuff, Ltd. DOM4J is a registered 284 * trademark of MetaStuff, Ltd. 285 * 286 * 5. Due credit should be given to the DOM4J Project 287 * (http://dom4j.org/). 288 * 289 * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS 290 * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT 291 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 292 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 293 * METASTUFF, LTD. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 294 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 295 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 296 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 297 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 298 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 299 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 300 * OF THE POSSIBILITY OF SUCH DAMAGE. 301 * 302 * Copyright 2001 (C) MetaStuff, Ltd. All Rights Reserved. 303 * 304 * $Id: Branch.java,v 1.24 2001/10/24 09:41:15 jstrachan Exp $ 305 */