|
0
|
1 /*--
|
|
|
2
|
|
|
3 $Id: Parent.java,v 1.13 2007/11/10 05:28:59 jhunter Exp $
|
|
|
4
|
|
|
5 Copyright (C) 2000-2007 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.13 $, $Date: 2007/11/10 05:28:59 $
|
|
|
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 }
|
