Source code: org/jdom/Parent.java
1 /*--
2
3 $Id: Parent.java,v 1.12 2004/08/31 21:47:51 jhunter Exp $
4
5 Copyright (C) 2000-2004 Jason Hunter & Brett McLaughlin.
6 All rights reserved.
7
8 Redistribution and use in source and binary forms, with or without
9 modification, are permitted provided that the following conditions
10 are met:
11
12 1. Redistributions of source code must retain the above copyright
13 notice, this list of conditions, and the following disclaimer.
14
15 2. Redistributions in binary form must reproduce the above copyright
16 notice, this list of conditions, and the disclaimer that follows
17 these conditions in the documentation and/or other materials
18 provided with the distribution.
19
20 3. The name "JDOM" must not be used to endorse or promote products
21 derived from this software without prior written permission. For
22 written permission, please contact <request_AT_jdom_DOT_org>.
23
24 4. Products derived from this software may not be called "JDOM", nor
25 may "JDOM" appear in their name, without prior written permission
26 from the JDOM Project Management <request_AT_jdom_DOT_org>.
27
28 In addition, we request (but do not require) that you include in the
29 end-user documentation provided with the redistribution and/or in the
30 software itself an acknowledgement equivalent to the following:
31 "This product includes software developed by the
32 JDOM Project (http://www.jdom.org/)."
33 Alternatively, the acknowledgment may be graphical using the logos
34 available at http://www.jdom.org/images/logos.
35
36 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39 DISCLAIMED. IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
40 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47 SUCH DAMAGE.
48
49 This software consists of voluntary contributions made by many
50 individuals on behalf of the JDOM Project and was originally
51 created by Jason Hunter <jhunter_AT_jdom_DOT_org> and
52 Brett McLaughlin <brett_AT_jdom_DOT_org>. For more information
53 on the JDOM Project, please see <http://www.jdom.org/>.
54
55 */
56
57 package org.jdom;
58
59 import java.io.Serializable;
60 import java.util.*;
61 import org.jdom.filter.Filter;
62
63 /**
64 * Superclass for JDOM objects which are allowed to contain
65 * {@link Content} content.
66 *
67 * @see org.jdom.Content
68 * @see org.jdom.Document
69 * @see org.jdom.Element
70 *
71 * @author Bradley S. Huffman
72 * @author Jason Hunter
73 * @version $Revision: 1.12 $, $Date: 2004/08/31 21:47:51 $
74 */
75 public interface Parent extends Cloneable, Serializable {
76
77 /**
78 * Returns the number of children in this parent's content list.
79 * Children may be any {@link Content} type.
80 *
81 * @return number of children
82 */
83 int getContentSize();
84
85 /**
86 * Returns the index of the supplied child in the content list,
87 * or -1 if not a child of this parent.
88 *
89 * @param child child to search for
90 * @return index of child, or -1 if not found
91 */
92 int indexOf(Content child);
93
94 // /**
95 // * Starting at the given index (inclusive), returns the index of
96 // * the first child matching the supplied filter, or -1
97 // * if none is found.
98 // *
99 // * @return index of child, or -1 if none found
100 // */
101 // int indexOf(int index, Filter filter);
102
103 /**
104 * Returns a list containing detached clones of this parent's content list.
105 *
106 * @return list of cloned child content
107 */
108 List cloneContent();
109
110 /**
111 * Returns the child at the given index.
112 *
113 * @param index location of desired child
114 * @return child at the given index
115 * @throws IndexOutOfBoundsException if index is negative or beyond
116 * the current number of children
117 * @throws IllegalStateException if parent is a Document
118 * and the root element is not set
119 */
120 Content getContent(int index);
121
122 /**
123 * Returns the full content of this parent as a {@link java.util.List}
124 * which contains objects of type {@link Content}. The returned list is
125 * <b>"live"</b> and in document order. Any modifications
126 * to it affect the element's actual contents. Modifications are checked
127 * for conformance to XML 1.0 rules.
128 * <p>
129 * Sequential traversal through the List is best done with an Iterator
130 * since the underlying implement of {@link java.util.List#size} may
131 * require walking the entire list and indexed lookups may require
132 * starting at the beginning each time.
133 *
134 * @return a list of the content of the parent
135 * @throws IllegalStateException if parent is a Document
136 * and the root element is not set
137 */
138 List getContent();
139
140 /**
141 * Returns as a {@link java.util.List} the content of
142 * this parent that matches the supplied filter. The returned list is
143 * <b>"live"</b> and in document order. Any modifications to it affect
144 * the element's actual contents. Modifications are checked for
145 * conformance to XML 1.0 rules.
146 * <p>
147 * Sequential traversal through the List is best done with an Iterator
148 * since the underlying implement of {@link java.util.List#size} may
149 * require walking the entire list and indexed lookups may require
150 * starting at the beginning each time.
151 *
152 * @param filter filter to apply
153 * @return a list of the content of the parent matching the filter
154 * @throws IllegalStateException if parent is a Document
155 * and the root element is not set
156 */
157 List getContent(Filter filter);
158
159 /**
160 * Removes all content from this parent and returns the detached
161 * children.
162 *
163 * @return list of the old content detached from this parent
164 */
165 List removeContent();
166
167 /**
168 * Removes from this parent all child content matching the given filter
169 * and returns a list of the detached children.
170 *
171 * @param filter filter to apply
172 * @return list of the detached children matching the filter
173 */
174 List removeContent(Filter filter);
175
176 /**
177 * Removes a single child node from the content list.
178 *
179 * @param child child to remove
180 * @return whether the removal occurred
181 */
182 boolean removeContent(Content child);
183
184 /**
185 * Removes and returns the child at the given
186 * index, or returns null if there's no such child.
187 *
188 * @param index index of child to remove
189 * @return detached child at given index or null if no
190 * @throws IndexOutOfBoundsException if index is negative or beyond
191 * the current number of children
192 */
193 Content removeContent(int index);
194
195 /**
196 * Obtain a deep, unattached copy of this parent and it's children.
197 *
198 * @return a deep copy of this parent and it's children.
199 */
200 Object clone();
201
202 /**
203 * Returns an {@link java.util.Iterator} that walks over all descendants
204 * in document order.
205 *
206 * @return an iterator to walk descendants
207 */
208 Iterator getDescendants();
209
210 /**
211 * Returns an {@link java.util.Iterator} that walks over all descendants
212 * in document order applying the Filter to return only elements that
213 * match the filter rule. With filters you can match only Elements,
214 * only Comments, Elements or Comments, only Elements with a given name
215 * and/or prefix, and so on.
216 *
217 * @param filter filter to select which descendants to see
218 * @return an iterator to walk descendants that match a filter
219 */
220 Iterator getDescendants(Filter filter);
221
222 /**
223 * Return this parent's parent, or null if this parent is currently
224 * not attached to another parent. This is the same method as in Content but
225 * also added to Parent to allow more easy up-the-tree walking.
226 *
227 * @return this parent's parent or null if none
228 */
229 Parent getParent();
230
231 /**
232 * Return this parent's owning document or null if the branch containing
233 * this parent is currently not attached to a document.
234 *
235 * @return this child's owning document or null if none
236 */
237 Document getDocument();
238
239 }