1
2
3
4
5
6
7
8
9
10 package org.dom4j;
11
12 import java.util.Iterator;
13 import java.util.List;
14
15
16 /*** <p><code>Branch</code> interface defines the common behaviour
17 * for Nodes which can contain child nodes (content) such as
18 * XML elements and documents.
19 * This interface allows both elements and documents to be treated in a
20 * polymorphic manner when changing or navigating child nodes (content).</p>
21 *
22 * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
23 * @version $Revision: 1.30 $
24 */
25 public interface Branch extends Node {
26
27 /*** Returns the <code>Node</code> at the specified index position.
28 *
29 * @param index the index of the node to return.
30 * @return the <code>Node</code> at the specified position.
31 *
32 * @throws IndexOutOfBoundsException if the index is out of range (index
33 * < 0 || index >= {@link #nodeCount}).
34 */
35 public Node node(int index);
36
37 /*** Returns the index of the given node if it is a child node of this
38 * branch or -1 if the given node is not a child node.
39 *
40 * @param node the content child node to find.
41 * @return the index of the given node starting at 0 or -1 if the node
42 * is not a child node of this branch
43 */
44 public int indexOf(Node node);
45
46 /*** Returns the number of <code>Node</code> instances that this branch
47 * contains.
48 *
49 * @return the number of nodes this branch contains
50 */
51 public int nodeCount();
52
53 /*** Returns the element of the given ID attribute value. If this tree
54 * is capable of understanding which attribute value should be used for
55 * the ID then it should be used, otherwise this method should return null.
56 */
57 public Element elementByID(String elementID);
58
59
60 /*** <p>Returns the content nodes of this branch as a backed {@link List}
61 * so that the content of this branch may be modified directly using
62 * the {@link List} interface.
63 * The <code>List</code> is backed by the <code>Branch</code> so that
64 * changes to the list are reflected in the branch and vice versa.</p>
65 *
66 * @return the nodes that this branch contains as a <code>List</code>
67 */
68 public List content();
69
70 /*** Returns an iterator through the content nodes of this branch
71 *
72 * @return an iterator through the content nodes of this branch
73 */
74 public Iterator nodeIterator();
75
76 /*** Sets the contents of this branch as a <code>List</code> of
77 * <code>Node</code> instances.
78 *
79 * @param content is the list of nodes to use as the content for this
80 * branch.
81 */
82 public void setContent(List content);
83
84 /*** Appends the content of the given branch to this branch instance.
85 * This method behaves like the {@link java.util.Collection#addAll(java.util.Collection)}
86 * method.
87 *
88 * @param branch is the branch whose content will be added to me.
89 */
90 public void appendContent(Branch branch);
91
92 /*** Clears the content for this branch, removing any <code>Node</code>
93 * instances this branch may contain.
94 */
95 public void clearContent();
96
97 /*** <p>Returns a list of all the processing instructions in this branch.
98 * The list is backed by this branch so that changes to the list will
99 * be reflected in the branch but the reverse is not the case.</p>
100 *
101 * @return a backed list of the processing instructions
102 */
103 public List processingInstructions();
104
105 /*** <p>Returns a list of the processing instructions for the given target.
106 * The list is backed by this branch so that changes to the list will
107 * be reflected in the branch but the reverse is not the case.</p>
108 *
109 * @return a backed list of the processing instructions
110 */
111 public List processingInstructions(String target);
112
113 /*** @return the processing instruction for the given target
114 */
115 public ProcessingInstruction processingInstruction(String target);
116
117 /*** Sets all the processing instructions for this branch
118 */
119 public void setProcessingInstructions(List listOfPIs);
120
121
122 /*** Adds a new <code>Element</code> node with the given name to this branch
123 * and returns a reference to the new node.
124 *
125 * @param name is the name for the <code>Element</code> node.
126 * @return the newly added <code>Element</code> node.
127 */
128 public Element addElement(String name);
129
130 /*** Adds a new <code>Element</code> node with the given {@link QName}
131 * to this branch and returns a reference to the new node.
132 *
133 * @param qname is the qualified name for the <code>Element</code> node.
134 * @return the newly added <code>Element</code> node.
135 */
136 public Element addElement(QName qname);
137
138 /*** Adds a new <code>Element</code> node with the given qualified name
139 * and namespace URI to this branch and returns a reference to the new node.
140 *
141 * @param qualifiedName is the fully qualified name of the Element
142 * @param namespaceURI is the URI of the namespace to use
143 * @return the newly added <code>Element</code> node.
144 */
145 public Element addElement(String qualifiedName, String namespaceURI);
146
147 /*** Removes the processing instruction for the given target if it exists
148 *
149 * @return true if a processing instruction was removed else false
150 */
151 public boolean removeProcessingInstruction(String target);
152
153
154
155 /*** Adds the given <code>Node</code> or throws {@link IllegalAddException}
156 * if the given node is not of a valid type. This is a polymorphic method
157 * which will call the typesafe method for the node type such as
158 * add(Element) or add(Comment).
159 *
160 * @param node is the given node to add
161 */
162 public void add(Node node);
163
164 /*** Adds the given <code>Comment</code> to this branch.
165 * If the given node already has a parent defined then an
166 * <code>IllegalAddException</code> will be thrown.
167 *
168 * @param comment is the comment to be added
169 */
170 public void add(Comment comment);
171
172 /*** Adds the given <code>Element</code> to this branch.
173 * If the given node already has a parent defined then an
174 * <code>IllegalAddException</code> will be thrown.
175 *
176 * @param element is the element to be added
177 */
178 public void add(Element element);
179
180 /*** Adds the given <code>ProcessingInstruction</code> to this branch.
181 * If the given node already has a parent defined then an
182 * <code>IllegalAddException</code> will be thrown.
183 *
184 * @param pi is the processing instruction to be added
185 */
186 public void add(ProcessingInstruction pi);
187
188 /*** Removes the given <code>Node</code> if the node is
189 * an immediate child of this branch.
190 *
191 * If the given node is not an immediate child of this branch
192 * then the {@link Node#detach()} method should be used instead.
193 *
194 * This is a polymorphic method which will call the typesafe method
195 * for the node type such as remove(Element) or remove(Comment).
196 *
197 * @param node is the given node to be removed
198 * @return true if the node was removed
199 */
200 public boolean remove(Node node);
201
202 /*** Removes the given <code>Comment</code> if the node is
203 * an immediate child of this branch.
204 *
205 * If the given node is not an immediate child of this branch
206 * then the {@link Node#detach()} method should be used instead.
207 *
208 * @param comment is the comment to be removed
209 * @return true if the comment was removed
210 */
211 public boolean remove(Comment comment);
212
213 /*** Removes the given <code>Element</code> if the node is
214 * an immediate child of this branch.
215 *
216 * If the given node is not an immediate child of this branch
217 * then the {@link Node#detach()} method should be used instead.
218 *
219 * @param element is the element to be removed
220 * @return true if the element was removed
221 */
222 public boolean remove(Element element);
223
224 /*** Removes the given <code>ProcessingInstruction</code> if the node is
225 * an immediate child of this branch.
226 *
227 * If the given node is not an immediate child of this branch
228 * then the {@link Node#detach()} method should be used instead.
229 *
230 * @param pi is the processing instruction to be removed
231 * @return true if the processing instruction was removed
232 */
233 public boolean remove(ProcessingInstruction pi);
234
235
236 /***
237 * Puts all <code>Text</code> nodes in the full depth of the sub-tree
238 * underneath this <code>Node</code>, including attribute nodes, into a
239 * "normal" form where only structure (e.g., elements, comments,
240 * processing instructions, CDATA sections, and entity references)
241 * separates <code>Text</code> nodes, i.e., there are neither adjacent
242 * <code>Text</code> nodes nor empty <code>Text</code> nodes. This can
243 * be used to ensure that the DOM view of a document is the same as if
244 * it were saved and re-loaded, and is useful when operations (such as
245 * XPointer lookups) that depend on a particular document tree
246 * structure are to be used.In cases where the document contains
247 * <code>CDATASections</code>, the normalize operation alone may not be
248 * sufficient, since XPointers do not differentiate between
249 * <code>Text</code> nodes and <code>CDATASection</code> nodes.
250 * @since DOM Level 2
251 */
252 public void normalize();
253 }
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301