001: /*--
002:
003: $Id: Parent.java,v 1.12 2004/08/31 21:47:51 jhunter Exp $
004:
005: Copyright (C) 2000-2004 Jason Hunter & Brett McLaughlin.
006: All rights reserved.
007:
008: Redistribution and use in source and binary forms, with or without
009: modification, are permitted provided that the following conditions
010: are met:
011:
012: 1. Redistributions of source code must retain the above copyright
013: notice, this list of conditions, and the following disclaimer.
014:
015: 2. Redistributions in binary form must reproduce the above copyright
016: notice, this list of conditions, and the disclaimer that follows
017: these conditions in the documentation and/or other materials
018: provided with the distribution.
019:
020: 3. The name "JDOM" must not be used to endorse or promote products
021: derived from this software without prior written permission. For
022: written permission, please contact <request_AT_jdom_DOT_org>.
023:
024: 4. Products derived from this software may not be called "JDOM", nor
025: may "JDOM" appear in their name, without prior written permission
026: from the JDOM Project Management <request_AT_jdom_DOT_org>.
027:
028: In addition, we request (but do not require) that you include in the
029: end-user documentation provided with the redistribution and/or in the
030: software itself an acknowledgement equivalent to the following:
031: "This product includes software developed by the
032: JDOM Project (http://www.jdom.org/)."
033: Alternatively, the acknowledgment may be graphical using the logos
034: available at http://www.jdom.org/images/logos.
035:
036: THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
037: WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
038: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
039: DISCLAIMED. IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
040: CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
041: SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
042: LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
043: USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
044: ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
045: OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
046: OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
047: SUCH DAMAGE.
048:
049: This software consists of voluntary contributions made by many
050: individuals on behalf of the JDOM Project and was originally
051: created by Jason Hunter <jhunter_AT_jdom_DOT_org> and
052: Brett McLaughlin <brett_AT_jdom_DOT_org>. For more information
053: on the JDOM Project, please see <http://www.jdom.org/>.
054:
055: */
056:
057: package org.jdom;
058:
059: import java.io.Serializable;
060: import java.util.*;
061: import org.jdom.filter.Filter;
062:
063: /**
064: * Superclass for JDOM objects which are allowed to contain
065: * {@link Content} content.
066: *
067: * @see org.jdom.Content
068: * @see org.jdom.Document
069: * @see org.jdom.Element
070: *
071: * @author Bradley S. Huffman
072: * @author Jason Hunter
073: * @version $Revision: 1.12 $, $Date: 2004/08/31 21:47:51 $
074: */
075: public interface Parent extends Cloneable, Serializable {
076:
077: /**
078: * Returns the number of children in this parent's content list.
079: * Children may be any {@link Content} type.
080: *
081: * @return number of children
082: */
083: int getContentSize();
084:
085: /**
086: * Returns the index of the supplied child in the content list,
087: * or -1 if not a child of this parent.
088: *
089: * @param child child to search for
090: * @return index of child, or -1 if not found
091: */
092: int indexOf(Content child);
093:
094: // /**
095: // * Starting at the given index (inclusive), returns the index of
096: // * the first child matching the supplied filter, or -1
097: // * if none is found.
098: // *
099: // * @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: }
|