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