Branch


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  */
352
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags