|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
Branch.java | - | - | - | - |
|
1 | /* | |
2 | * Copyright 2001-2004 (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 | * $Id: Branch.java,v 1.30 2004/06/25 12:34:46 maartenc Exp $ | |
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 | * Redistribution and use of this software and associated documentation | |
260 | * ("Software"), with or without modification, are permitted provided | |
261 | * that the following conditions are met: | |
262 | * | |
263 | * 1. Redistributions of source code must retain copyright | |
264 | * statements and notices. Redistributions must also contain a | |
265 | * copy of this document. | |
266 | * | |
267 | * 2. Redistributions in binary form must reproduce the | |
268 | * above copyright notice, this list of conditions and the | |
269 | * following disclaimer in the documentation and/or other | |
270 | * materials provided with the distribution. | |
271 | * | |
272 | * 3. The name "DOM4J" must not be used to endorse or promote | |
273 | * products derived from this Software without prior written | |
274 | * permission of MetaStuff, Ltd. For written permission, | |
275 | * please contact dom4j-info@metastuff.com. | |
276 | * | |
277 | * 4. Products derived from this Software may not be called "DOM4J" | |
278 | * nor may "DOM4J" appear in their names without prior written | |
279 | * permission of MetaStuff, Ltd. DOM4J is a registered | |
280 | * trademark of MetaStuff, Ltd. | |
281 | * | |
282 | * 5. Due credit should be given to the DOM4J Project - | |
283 | * http://www.dom4j.org | |
284 | * | |
285 | * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS | |
286 | * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT | |
287 | * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND | |
288 | * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL | |
289 | * METASTUFF, LTD. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, | |
290 | * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES | |
291 | * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR | |
292 | * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
293 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, | |
294 | * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
295 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED | |
296 | * OF THE POSSIBILITY OF SUCH DAMAGE. | |
297 | * | |
298 | * Copyright 2001-2004 (C) MetaStuff, Ltd. All Rights Reserved. | |
299 | * | |
300 | * $Id: Branch.java,v 1.30 2004/06/25 12:34:46 maartenc Exp $ | |
301 | */ |
|