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, Iterable<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<Node> 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<Node> nodeIterator();
90
91 /**
92 * Returns an iterator through the content nodes of this branch
93 *
94 * @return an iterator through the content nodes of this branch
95 */
96 Iterator<Node> iterator();
97
98 /**
99 * Sets the contents of this branch as a <code>List</code> of
100 * <code>Node</code> instances.
101 *
102 * @param content
103 * is the list of nodes to use as the content for this branch.
104 */
105 void setContent(List<Node> content);
106
107 /**
108 * Appends the content of the given branch to this branch instance. This
109 * method behaves like the {@link
110 * java.util.Collection#addAll(java.util.Collection)} method.
111 *
112 * @param branch
113 * is the branch whose content will be added to me.
114 */
115 void appendContent(Branch branch);
116
117 /**
118 * Clears the content for this branch, removing any <code>Node</code>
119 * instances this branch may contain.
120 */
121 void clearContent();
122
123 /**
124 * <p>
125 * Returns a list of all the processing instructions in this branch. The
126 * list is backed by this branch so that changes to the list will be
127 * reflected in the branch but the reverse is not the case.
128 * </p>
129 *
130 * @return a backed list of the processing instructions
131 */
132 List<ProcessingInstruction> processingInstructions();
133
134 /**
135 * <p>
136 * Returns a list of the processing instructions for the given target. The
137 * list is backed by this branch so that changes to the list will be
138 * reflected in the branch but the reverse is not the case.
139 * </p>
140 *
141 * @param target
142 * DOCUMENT ME!
143 *
144 * @return a backed list of the processing instructions
145 */
146 List<ProcessingInstruction> processingInstructions(String target);
147
148 /**
149 * DOCUMENT ME!
150 *
151 * @param target
152 * DOCUMENT ME!
153 *
154 * @return the processing instruction for the given target
155 */
156 ProcessingInstruction processingInstruction(String target);
157
158 /**
159 * Sets all the processing instructions for this branch
160 *
161 * @param listOfPIs
162 * DOCUMENT ME!
163 */
164 void setProcessingInstructions(List<ProcessingInstruction> listOfPIs);
165
166 /**
167 * Adds a new <code>Element</code> node with the given name to this branch
168 * and returns a reference to the new node.
169 *
170 * @param name
171 * is the name for the <code>Element</code> node.
172 *
173 * @return the newly added <code>Element</code> node.
174 */
175 Element addElement(String name);
176
177 /**
178 * Adds a new <code>Element</code> node with the given {@link QName}to
179 * this branch and returns a reference to the new node.
180 *
181 * @param qname
182 * is the qualified name for the <code>Element</code> node.
183 *
184 * @return the newly added <code>Element</code> node.
185 */
186 Element addElement(QName qname);
187
188 /**
189 * Adds a new <code>Element</code> node with the given qualified name and
190 * namespace URI to this branch and returns a reference to the new node.
191 *
192 * @param qualifiedName
193 * is the fully qualified name of the Element
194 * @param namespaceURI
195 * is the URI of the namespace to use
196 *
197 * @return the newly added <code>Element</code> node.
198 */
199 Element addElement(String qualifiedName, String namespaceURI);
200
201 /**
202 * Removes the processing instruction for the given target if it exists
203 *
204 * @param target
205 * DOCUMENT ME!
206 *
207 * @return true if a processing instruction was removed else false
208 */
209 boolean removeProcessingInstruction(String target);
210
211 /**
212 * Adds the given <code>Node</code> or throws {@link IllegalAddException}
213 * if the given node is not of a valid type. This is a polymorphic method
214 * which will call the typesafe method for the node type such as
215 * add(Element) or add(Comment).
216 *
217 * @param node
218 * is the given node to add
219 */
220 void add(Node node);
221
222 /**
223 * Adds the given <code>Comment</code> to this branch. If the given node
224 * already has a parent defined then an <code>IllegalAddException</code>
225 * will be thrown.
226 *
227 * @param comment
228 * is the comment to be added
229 */
230 void add(Comment comment);
231
232 /**
233 * Adds the given <code>Element</code> to this branch. If the given node
234 * already has a parent defined then an <code>IllegalAddException</code>
235 * will be thrown.
236 *
237 * @param element
238 * is the element to be added
239 */
240 void add(Element element);
241
242 /**
243 * Adds the given <code>ProcessingInstruction</code> to this branch. If
244 * the given node already has a parent defined then an
245 * <code>IllegalAddException</code> will be thrown.
246 *
247 * @param pi
248 * is the processing instruction to be added
249 */
250 void add(ProcessingInstruction pi);
251
252 /**
253 * Removes the given <code>Node</code> if the node is an immediate child
254 * of this branch. If the given node is not an immediate child of this
255 * branch then the {@link Node#detach()}method should be used instead. This
256 * is a polymorphic method which will call the typesafe method for the node
257 * type such as remove(Element) or remove(Comment).
258 *
259 * @param node
260 * is the given node to be removed
261 *
262 * @return true if the node was removed
263 */
264 boolean remove(Node node);
265
266 /**
267 * Removes the given <code>Comment</code> if the node is an immediate
268 * child of this branch. If the given node is not an immediate child of this
269 * branch then the {@link Node#detach()}method should be used instead.
270 *
271 * @param comment
272 * is the comment to be removed
273 *
274 * @return true if the comment was removed
275 */
276 boolean remove(Comment comment);
277
278 /**
279 * Removes the given <code>Element</code> if the node is an immediate
280 * child of this branch. If the given node is not an immediate child of this
281 * branch then the {@link Node#detach()}method should be used instead.
282 *
283 * @param element
284 * is the element to be removed
285 *
286 * @return true if the element was removed
287 */
288 boolean remove(Element element);
289
290 /**
291 * Removes the given <code>ProcessingInstruction</code> if the node is an
292 * immediate child of this branch. If the given node is not an immediate
293 * child of this branch then the {@link Node#detach()}method should be used
294 * instead.
295 *
296 * @param pi
297 * is the processing instruction to be removed
298 *
299 * @return true if the processing instruction was removed
300 */
301 boolean remove(ProcessingInstruction pi);
302
303 /**
304 * Puts all <code>Text</code> nodes in the full depth of the sub-tree
305 * underneath this <code>Node</code>, including attribute nodes, into a
306 * "normal" form where only structure (e.g., elements, comments, processing
307 * instructions, CDATA sections, and entity references) separates
308 * <code>Text</code> nodes, i.e., there are neither adjacent
309 * <code>Text</code> nodes nor empty <code>Text</code> nodes. This can
310 * be used to ensure that the DOM view of a document is the same as if it
311 * were saved and re-loaded, and is useful when operations (such as XPointer
312 * lookups) that depend on a particular document tree structure are to be
313 * used.In cases where the document contains <code>CDATASections</code>,
314 * the normalize operation alone may not be sufficient, since XPointers do
315 * not differentiate between <code>Text</code> nodes and
316 * <code>CDATASection</code> nodes.
317 *
318 * @since DOM Level 2
319 */
320 void normalize();
321 }
322
323 /*
324 * Redistribution and use of this software and associated documentation
325 * ("Software"), with or without modification, are permitted provided that the
326 * following conditions are met:
327 *
328 * 1. Redistributions of source code must retain copyright statements and
329 * notices. Redistributions must also contain a copy of this document.
330 *
331 * 2. Redistributions in binary form must reproduce the above copyright notice,
332 * this list of conditions and the following disclaimer in the documentation
333 * and/or other materials provided with the distribution.
334 *
335 * 3. The name "DOM4J" must not be used to endorse or promote products derived
336 * from this Software without prior written permission of MetaStuff, Ltd. For
337 * written permission, please contact dom4j-info@metastuff.com.
338 *
339 * 4. Products derived from this Software may not be called "DOM4J" nor may
340 * "DOM4J" appear in their names without prior written permission of MetaStuff,
341 * Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
342 *
343 * 5. Due credit should be given to the DOM4J Project - http://www.dom4j.org
344 *
345 * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND
346 * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
347 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
348 * ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE
349 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
350 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
351 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
352 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
353 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
354 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
355 * POSSIBILITY OF SUCH DAMAGE.
356 *
357 * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
358 */