KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > list > GrowthList


1 /*
2  * Copyright 2005-2006 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.collections.list;
17
18 import java.util.ArrayList JavaDoc;
19 import java.util.Collection JavaDoc;
20 import java.util.Collections JavaDoc;
21 import java.util.List JavaDoc;
22
23 /**
24  * Decorates another <code>List</code> to make it seamlessly grow when
25  * indices larger than the list size are used on add and set,
26  * avoiding most IndexOutOfBoundsExceptions.
27  * <p>
28  * This class avoids errors by growing when a set or add method would
29  * normally throw an IndexOutOfBoundsException.
30  * Note that IndexOutOfBoundsException IS returned for invalid negative indices.
31  * <p>
32  * Trying to set or add to an index larger than the size will cause the list
33  * to grow (using <code>null</code> elements). Clearly, care must be taken
34  * not to use excessively large indices, as the internal list will grow to
35  * match.
36  * <p>
37  * Trying to use any method other than add or set with an invalid index will
38  * call the underlying list and probably result in an IndexOutOfBoundsException.
39  * <p>
40  * Take care when using this list with <code>null</code> values, as
41  * <code>null</code> is the value added when growing the list.
42  * <p>
43  * All sub-lists will access the underlying list directly, and will throw
44  * IndexOutOfBoundsExceptions.
45  * <p>
46  * This class differs from {@link LazyList} because here growth occurs on
47  * set and add, where <code>LazyList</code> grows on get. However, they
48  * can be used together by decorating twice.
49  *
50  * @see LazyList
51  * @since Commons Collections 3.2
52  * @version $Revision: 155406 $ $Date: 2006-05-12 23:57:03 +0100 (Fri, 12 May 2006) $
53  *
54  * @author Stephen Colebourne
55  * @author Paul Legato
56  */
57 public class GrowthList extends AbstractSerializableListDecorator {
58
59     /** Serialization version */
60     private static final long serialVersionUID = -3620001881672L;
61
62     /**
63      * Factory method to create a growth list.
64      *
65      * @param list the list to decorate, must not be null
66      * @throws IllegalArgumentException if list is null
67      */
68     public static List JavaDoc decorate(List JavaDoc list) {
69         return new GrowthList(list);
70     }
71
72     //-----------------------------------------------------------------------
73 /**
74      * Constructor that uses an ArrayList internally.
75      */
76     public GrowthList() {
77         super(new ArrayList JavaDoc());
78     }
79
80     /**
81      * Constructor that uses an ArrayList internally.
82      *
83      * @param initialSize the initial size of the ArrayList
84      * @throws IllegalArgumentException if initial size is invalid
85      */
86     public GrowthList(int initialSize) {
87         super(new ArrayList JavaDoc(initialSize));
88     }
89
90     /**
91      * Constructor that wraps (not copies).
92      *
93      * @param list the list to decorate, must not be null
94      * @throws IllegalArgumentException if list is null
95      */
96     protected GrowthList(List JavaDoc list) {
97         super(list);
98     }
99
100     //-----------------------------------------------------------------------
101 /**
102      * Decorate the add method to perform the growth behaviour.
103      * <p>
104      * If the requested index is greater than the current size, the list will
105      * grow to the new size. Indices between the old size and the requested
106      * size will be filled with <code>null</code>.
107      * <p>
108      * If the index is less than the current size, the value will be added to
109      * the underlying list directly.
110      * If the index is less than zero, the underlying list is called, which
111      * will probably throw an IndexOutOfBoundsException.
112      *
113      * @param index the index to add at
114      * @param element the object to add at the specified index
115      * @throws UnsupportedOperationException if the underlying list doesn't implement set
116      * @throws ClassCastException if the underlying list rejects the element
117      * @throws IllegalArgumentException if the underlying list rejects the element
118      */
119     public void add(int index, Object JavaDoc element) {
120         int size = getList().size();
121         if (index > size) {
122             getList().addAll(Collections.nCopies(index - size, null));
123         }
124         getList().add(index, element);
125     }
126
127     //-----------------------------------------------------------------------
128 /**
129      * Decorate the addAll method to perform the growth behaviour.
130      * <p>
131      * If the requested index is greater than the current size, the list will
132      * grow to the new size. Indices between the old size and the requested
133      * size will be filled with <code>null</code>.
134      * <p>
135      * If the index is less than the current size, the values will be added to
136      * the underlying list directly.
137      * If the index is less than zero, the underlying list is called, which
138      * will probably throw an IndexOutOfBoundsException.
139      *
140      * @param index the index to add at
141      * @param coll the collection to add at the specified index
142      * @return true if the list changed
143      * @throws UnsupportedOperationException if the underlying list doesn't implement set
144      * @throws ClassCastException if the underlying list rejects the element
145      * @throws IllegalArgumentException if the underlying list rejects the element
146      */
147     public boolean addAll(int index, Collection JavaDoc coll) {
148         int size = getList().size();
149         boolean result = false;
150         if (index > size) {
151             getList().addAll(Collections.nCopies(index - size, null));
152             result = true;
153         }
154         return (getList().addAll(index, coll) | result);
155     }
156
157     //-----------------------------------------------------------------------
158 /**
159      * Decorate the set method to perform the growth behaviour.
160      * <p>
161      * If the requested index is greater than the current size, the list will
162      * grow to the new size. Indices between the old size and the requested
163      * size will be filled with <code>null</code>.
164      * <p>
165      * If the index is less than the current size, the value will be set onto
166      * the underlying list directly.
167      * If the index is less than zero, the underlying list is called, which
168      * will probably throw an IndexOutOfBoundsException.
169      *
170      * @param index the index to set
171      * @param element the object to set at the specified index
172      * @return the object previously at that index
173      * @throws UnsupportedOperationException if the underlying list doesn't implement set
174      * @throws ClassCastException if the underlying list rejects the element
175      * @throws IllegalArgumentException if the underlying list rejects the element
176      */
177     public Object JavaDoc set(int index, Object JavaDoc element) {
178         int size = getList().size();
179         if (index >= size) {
180             getList().addAll(Collections.nCopies((index - size) + 1, null));
181         }
182         return getList().set(index, element);
183     }
184
185 }
186
Popular Tags