1   
2   
3   
4   
5   
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 < 0 || index >=
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 
318 
319 
320 
321 
322 
323 
324 
325 
326 
327 
328 
329 
330 
331 
332 
333 
334 
335 
336 
337 
338 
339 
340 
341 
342 
343 
344 
345 
346 
347 
348 
349 
350 
351