KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > dom4j > Branch


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 JavaDoc;
11 import java.util.List JavaDoc;
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 &lt; 0 || index &gt;=
35      * {@link Branch#nodeCount()}).
36      */

37     Node node(int index) throws IndexOutOfBoundsException JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc processingInstructions(String JavaDoc 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 JavaDoc target);
150
151     /**
152      * Sets all the processing instructions for this branch
153      *
154      * @param listOfPIs
155      * DOCUMENT ME!
156      */

157     void setProcessingInstructions(List JavaDoc 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 JavaDoc 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 JavaDoc qualifiedName, String JavaDoc 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 JavaDoc 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  */

352
Popular Tags