|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
Branch.java | - | - | - | - |
|
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 < 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 | * 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 | */ |
|