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      *                   &lt; 0 || index &gt;= {@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 */