List.java revision 2ad60cfc28e14ee8f0bb038720836a4696c478ad 
1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.util;
19
20
21/**
22 * List is a collection which maintains an ordering for its elements. Every
23 * element in the list has an index.
24 */
25public interface List<E> extends Collection<E> {
26    /**
27     * Inserts the specified object into this Vector at the specified location.
28     * The object is inserted before any previous element at the specified
29     * location. If the location is equal to the size of this List, the object
30     * is added at the end.
31     *
32     * @param location
33     *            the index at which to insert
34     * @param object
35     *            the object to add
36     *
37     * @exception UnsupportedOperationException
38     *                when adding to this List is not supported
39     * @exception ClassCastException
40     *                when the class of the object is inappropriate for this
41     *                List
42     * @exception IllegalArgumentException
43     *                when the object cannot be added to this List
44     * @exception IndexOutOfBoundsException
45     *                when <code>location < 0 || >= size()</code>
46     */
47    public void add(int location, E object);
48
49    /**
50     * Adds the specified object at the end of this List.
51     *
52     * @param object
53     *            the object to add
54     * @return true
55     *
56     * @exception UnsupportedOperationException
57     *                when adding to this List is not supported
58     * @exception ClassCastException
59     *                when the class of the object is inappropriate for this
60     *                List
61     * @exception IllegalArgumentException
62     *                when the object cannot be added to this List
63     */
64    public boolean add(E object);
65
66    /**
67     * Inserts the objects in the specified Collection at the specified location
68     * in this List. The objects are added in the order they are returned from
69     * the Collection iterator.
70     *
71     * @param location
72     *            the index at which to insert
73     * @param collection
74     *            the Collection of objects
75     * @return true if this List is modified, false otherwise
76     *
77     * @exception UnsupportedOperationException
78     *                when adding to this List is not supported
79     * @exception ClassCastException
80     *                when the class of an object is inappropriate for this List
81     * @exception IllegalArgumentException
82     *                when an object cannot be added to this List
83     * @exception IndexOutOfBoundsException
84     *                when <code>location < 0 || >= size()</code>
85     */
86    public boolean addAll(int location, Collection<? extends E> collection);
87
88    /**
89     * Adds the objects in the specified Collection to the end of this List. The
90     * objects are added in the order they are returned from the Collection
91     * iterator.
92     *
93     * @param collection
94     *            the Collection of objects
95     * @return true if this List is modified, false otherwise
96     *
97     * @exception UnsupportedOperationException
98     *                when adding to this List is not supported
99     * @exception ClassCastException
100     *                when the class of an object is inappropriate for this List
101     * @exception IllegalArgumentException
102     *                when an object cannot be added to this List
103     */
104    public boolean addAll(Collection<? extends E> collection);
105
106    /**
107     * Removes all elements from this List, leaving it empty.
108     *
109     * @exception UnsupportedOperationException
110     *                when removing from this List is not supported
111     *
112     * @see #isEmpty
113     * @see #size
114     */
115    public void clear();
116
117    /**
118     * Searches this List for the specified object.
119     *
120     * @param object
121     *            the object to search for
122     * @return true if object is an element of this List, false otherwise
123     */
124    public boolean contains(Object object);
125
126    /**
127     * Searches this List for all objects in the specified Collection.
128     *
129     * @param collection
130     *            the Collection of objects
131     * @return true if all objects in the specified Collection are elements of
132     *         this List, false otherwise
133     */
134    public boolean containsAll(Collection<?> collection);
135
136    /**
137     * Compares the argument to the receiver, and returns true if they represent
138     * the <em>same</em> object using a class specific comparison.
139     *
140     * @param object
141     *            Object the object to compare with this object.
142     * @return boolean <code>true</code> if the object is the same as this
143     *         object <code>false</code> if it is different from this object.
144     * @see #hashCode
145     */
146    public boolean equals(Object object);
147
148    /**
149     * Returns the element at the specified location in this List.
150     *
151     * @param location
152     *            the index of the element to return
153     * @return the element at the specified location
154     *
155     * @exception IndexOutOfBoundsException
156     *                when <code>location < 0 || >= size()</code>
157     */
158    public E get(int location);
159
160    /**
161     * Returns an integer hash code for the receiver. Objects which are equal
162     * answer the same value for this method.
163     *
164     * @return the receiver's hash
165     *
166     * @see #equals
167     */
168    public int hashCode();
169
170    /**
171     * Searches this List for the specified object and returns the index of the
172     * first occurrence.
173     *
174     * @param object
175     *            the object to search for
176     * @return the index of the first occurrence of the object
177     */
178    public int indexOf(Object object);
179
180    /**
181     * Returns if this List has no elements, a size of zero.
182     *
183     * @return true if this List has no elements, false otherwise
184     *
185     * @see #size
186     */
187    public boolean isEmpty();
188
189    /**
190     * Returns an Iterator on the elements of this List. The elements are
191     * iterated in the same order that they occur in the List.
192     *
193     * @return an Iterator on the elements of this List
194     *
195     * @see Iterator
196     */
197    public Iterator<E> iterator();
198
199    /**
200     * Searches this List for the specified object and returns the index of the
201     * last occurrence.
202     *
203     * @param object
204     *            the object to search for
205     * @return the index of the last occurrence of the object
206     */
207    public int lastIndexOf(Object object);
208
209    /**
210     * Returns a ListIterator on the elements of this List. The elements are
211     * iterated in the same order that they occur in the List.
212     *
213     * @return a ListIterator on the elements of this List
214     *
215     * @see ListIterator
216     */
217    public ListIterator<E> listIterator();
218
219    /**
220     * Returns a ListIterator on the elements of this List. The elements are
221     * iterated in the same order that they occur in the List. The iteration
222     * starts at the specified location.
223     *
224     * @param location
225     *            the index at which to start the iteration
226     * @return a ListIterator on the elements of this List
227     *
228     * @exception IndexOutOfBoundsException
229     *                when <code>location < 0 || >= size()</code>
230     *
231     * @see ListIterator
232     */
233    public ListIterator<E> listIterator(int location);
234
235    /**
236     * Removes the object at the specified location from this List.
237     *
238     * @param location
239     *            the index of the object to remove
240     * @return the removed object
241     *
242     * @exception UnsupportedOperationException
243     *                when removing from this List is not supported
244     * @exception IndexOutOfBoundsException
245     *                when <code>location < 0 || >= size()</code>
246     */
247    public E remove(int location);
248
249    /**
250     * Removes the first occurrence of the specified object from this List.
251     *
252     * @param object
253     *            the object to remove
254     * @return true if this List is modified, false otherwise
255     *
256     * @exception UnsupportedOperationException
257     *                when removing from this List is not supported
258     */
259    public boolean remove(Object object);
260
261    /**
262     * Removes all occurrences in this List of each object in the specified
263     * Collection.
264     *
265     * @param collection
266     *            the Collection of objects to remove
267     * @return true if this List is modified, false otherwise
268     *
269     * @exception UnsupportedOperationException
270     *                when removing from this List is not supported
271     */
272    public boolean removeAll(Collection<?> collection);
273
274    /**
275     * Removes all objects from this List that are not contained in the
276     * specified Collection.
277     *
278     * @param collection
279     *            the Collection of objects to retain
280     * @return true if this List is modified, false otherwise
281     *
282     * @exception UnsupportedOperationException
283     *                when removing from this List is not supported
284     */
285    public boolean retainAll(Collection<?> collection);
286
287    /**
288     * Replaces the element at the specified location in this List with the
289     * specified object.
290     *
291     * @param location
292     *            the index at which to put the specified object
293     * @param object
294     *            the object to add
295     * @return the previous element at the index
296     *
297     * @exception UnsupportedOperationException
298     *                when replacing elements in this List is not supported
299     * @exception ClassCastException
300     *                when the class of an object is inappropriate for this List
301     * @exception IllegalArgumentException
302     *                when an object cannot be added to this List
303     * @exception IndexOutOfBoundsException
304     *                when <code>location < 0 || >= size()</code>
305     */
306    public E set(int location, E object);
307
308    /**
309     * Returns the number of elements in this List.
310     *
311     * @return the number of elements in this List
312     */
313    public int size();
314
315    /**
316     * Returns a List of the specified portion of this List from the start index
317     * to one less than the end index. The returned List is backed by this list
318     * so changes to one are reflected by the other.
319     *
320     * @param start
321     *            the index at which to start the sublist
322     * @param end
323     *            the index one past the end of the sublist
324     * @return a List of a portion of this List
325     *
326     * @exception IndexOutOfBoundsException
327     *                when <code>start < 0, start > end</code> or
328     *                <code>end > size()</code>
329     */
330    public List<E> subList(int start, int end);
331
332    /**
333     * Returns an array containing all elements contained in this List.
334     *
335     * @return an array of the elements from this List
336     */
337    public Object[] toArray();
338
339    /**
340     * Returns an array containing all elements contained in this List. If the
341     * specified array is large enough to hold the elements, the specified array
342     * is used, otherwise an array of the same type is created. If the specified
343     * array is used and is larger than this List, the array element following
344     * the collection elements is set to null.
345     *
346     * @param array
347     *            the array
348     * @return an array of the elements from this List
349     *
350     * @exception ArrayStoreException
351     *                when the type of an element in this List cannot be stored
352     *                in the type of the specified array
353     */
354    public <T> T[] toArray(T[] array);
355}
356