Parent


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 }
240
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags