001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.util;
019:
020: /**
021: * List is a collection which maintains an ordering for its elements. Every
022: * element in the list has an index.
023: */
024: public interface List<E> extends Collection<E> {
025:
026: /**
027: * Inserts the specified object into this Vector at the specified location.
028: * The object is inserted before any previous element at the specified
029: * location. If the location is equal to the size of this List, the object
030: * is added at the end.
031: *
032: * @param location
033: * the index at which to insert
034: * @param object
035: * the object to add
036: *
037: * @exception UnsupportedOperationException
038: * when adding to this List is not supported
039: * @exception ClassCastException
040: * when the class of the object is inappropriate for this
041: * List
042: * @exception IllegalArgumentException
043: * when the object cannot be added to this List
044: * @exception IndexOutOfBoundsException
045: * when <code>location < 0 || >= size()</code>
046: */
047: public void add(int location, E object);
048:
049: /**
050: * Adds the specified object at the end of this List.
051: *
052: * @param object
053: * the object to add
054: * @return true
055: *
056: * @exception UnsupportedOperationException
057: * when adding to this List is not supported
058: * @exception ClassCastException
059: * when the class of the object is inappropriate for this
060: * List
061: * @exception IllegalArgumentException
062: * when the object cannot be added to this List
063: */
064: public boolean add(E object);
065:
066: /**
067: * Inserts the objects in the specified Collection at the specified location
068: * in this List. The objects are added in the order they are returned from
069: * the Collection iterator.
070: *
071: * @param location
072: * the index at which to insert
073: * @param collection
074: * the Collection of objects
075: * @return true if this List is modified, false otherwise
076: *
077: * @exception UnsupportedOperationException
078: * when adding to this List is not supported
079: * @exception ClassCastException
080: * when the class of an object is inappropriate for this List
081: * @exception IllegalArgumentException
082: * when an object cannot be added to this List
083: * @exception IndexOutOfBoundsException
084: * when <code>location < 0 || >= size()</code>
085: */
086: public boolean addAll(int location,
087: Collection<? extends E> collection);
088:
089: /**
090: * Adds the objects in the specified Collection to the end of this List. The
091: * objects are added in the order they are returned from the Collection
092: * iterator.
093: *
094: * @param collection
095: * the Collection of objects
096: * @return true if this List is modified, false otherwise
097: *
098: * @exception UnsupportedOperationException
099: * when adding to this List is not supported
100: * @exception ClassCastException
101: * when the class of an object is inappropriate for this List
102: * @exception IllegalArgumentException
103: * when an object cannot be added to this List
104: */
105: public boolean addAll(Collection<? extends E> collection);
106:
107: /**
108: * Removes all elements from this List, leaving it empty.
109: *
110: * @exception UnsupportedOperationException
111: * when removing from this List is not supported
112: *
113: * @see #isEmpty
114: * @see #size
115: */
116: public void clear();
117:
118: /**
119: * Searches this List for the specified object.
120: *
121: * @param object
122: * the object to search for
123: * @return true if object is an element of this List, false otherwise
124: */
125: public boolean contains(Object object);
126:
127: /**
128: * Searches this List for all objects in the specified Collection.
129: *
130: * @param collection
131: * the Collection of objects
132: * @return true if all objects in the specified Collection are elements of
133: * this List, false otherwise
134: */
135: public boolean containsAll(Collection<?> collection);
136:
137: /**
138: * Compares the argument to the receiver, and answers true if they represent
139: * the <em>same</em> object using a class specific comparison.
140: *
141: * @param object
142: * Object the object to compare with this object.
143: * @return boolean <code>true</code> if the object is the same as this
144: * object <code>false</code> if it is different from this object.
145: * @see #hashCode
146: */
147: public boolean equals(Object object);
148:
149: /**
150: * Answers the element at the specified location in this List.
151: *
152: * @param location
153: * the index of the element to return
154: * @return the element at the specified location
155: *
156: * @exception IndexOutOfBoundsException
157: * when <code>location < 0 || >= size()</code>
158: */
159: public E get(int location);
160:
161: /**
162: * Answers an integer hash code for the receiver. Objects which are equal
163: * answer the same value for this method.
164: *
165: * @return the receiver's hash
166: *
167: * @see #equals
168: */
169: public int hashCode();
170:
171: /**
172: * Searches this List for the specified object and returns the index of the
173: * first occurrence.
174: *
175: * @param object
176: * the object to search for
177: * @return the index of the first occurrence of the object
178: */
179: public int indexOf(Object object);
180:
181: /**
182: * Answers if this List has no elements, a size of zero.
183: *
184: * @return true if this List has no elements, false otherwise
185: *
186: * @see #size
187: */
188: public boolean isEmpty();
189:
190: /**
191: * Answers an Iterator on the elements of this List. The elements are
192: * iterated in the same order that they occur in the List.
193: *
194: * @return an Iterator on the elements of this List
195: *
196: * @see Iterator
197: */
198: public Iterator<E> iterator();
199:
200: /**
201: * Searches this List for the specified object and returns the index of the
202: * last occurrence.
203: *
204: * @param object
205: * the object to search for
206: * @return the index of the last occurrence of the object
207: */
208: public int lastIndexOf(Object object);
209:
210: /**
211: * Answers a ListIterator on the elements of this List. The elements are
212: * iterated in the same order that they occur in the List.
213: *
214: * @return a ListIterator on the elements of this List
215: *
216: * @see ListIterator
217: */
218: public ListIterator<E> listIterator();
219:
220: /**
221: * Answers a ListIterator on the elements of this List. The elements are
222: * iterated in the same order that they occur in the List. The iteration
223: * starts at the specified location.
224: *
225: * @param location
226: * the index at which to start the iteration
227: * @return a ListIterator on the elements of this List
228: *
229: * @exception IndexOutOfBoundsException
230: * when <code>location < 0 || >= size()</code>
231: *
232: * @see ListIterator
233: */
234: public ListIterator<E> listIterator(int location);
235:
236: /**
237: * Removes the object at the specified location from this List.
238: *
239: * @param location
240: * the index of the object to remove
241: * @return the removed object
242: *
243: * @exception UnsupportedOperationException
244: * when removing from this List is not supported
245: * @exception IndexOutOfBoundsException
246: * when <code>location < 0 || >= size()</code>
247: */
248: public E remove(int location);
249:
250: /**
251: * Removes the first occurrence of the specified object from this List.
252: *
253: * @param object
254: * the object to remove
255: * @return true if this List is modified, false otherwise
256: *
257: * @exception UnsupportedOperationException
258: * when removing from this List is not supported
259: */
260: public boolean remove(Object object);
261:
262: /**
263: * Removes all occurrences in this List of each object in the specified
264: * Collection.
265: *
266: * @param collection
267: * the Collection of objects to remove
268: * @return true if this List is modified, false otherwise
269: *
270: * @exception UnsupportedOperationException
271: * when removing from this List is not supported
272: */
273: public boolean removeAll(Collection<?> collection);
274:
275: /**
276: * Removes all objects from this List that are not contained in the
277: * specified Collection.
278: *
279: * @param collection
280: * the Collection of objects to retain
281: * @return true if this List is modified, false otherwise
282: *
283: * @exception UnsupportedOperationException
284: * when removing from this List is not supported
285: */
286: public boolean retainAll(Collection<?> collection);
287:
288: /**
289: * Replaces the element at the specified location in this List with the
290: * specified object.
291: *
292: * @param location
293: * the index at which to put the specified object
294: * @param object
295: * the object to add
296: * @return the previous element at the index
297: *
298: * @exception UnsupportedOperationException
299: * when replacing elements in this List is not supported
300: * @exception ClassCastException
301: * when the class of an object is inappropriate for this List
302: * @exception IllegalArgumentException
303: * when an object cannot be added to this List
304: * @exception IndexOutOfBoundsException
305: * when <code>location < 0 || >= size()</code>
306: */
307: public E set(int location, E object);
308:
309: /**
310: * Answers the number of elements in this List.
311: *
312: * @return the number of elements in this List
313: */
314: public int size();
315:
316: /**
317: * Answers a List of the specified portion of this List from the start index
318: * to one less than the end index. The returned List is backed by this list
319: * so changes to one are reflected by the other.
320: *
321: * @param start
322: * the index at which to start the sublist
323: * @param end
324: * the index one past the end of the sublist
325: * @return a List of a portion of this List
326: *
327: * @exception IndexOutOfBoundsException
328: * when <code>start < 0, start > end</code> or
329: * <code>end > size()</code>
330: */
331: public List<E> subList(int start, int end);
332:
333: /**
334: * Answers an array containing all elements contained in this List.
335: *
336: * @return an array of the elements from this List
337: */
338: public Object[] toArray();
339:
340: /**
341: * Answers an array containing all elements contained in this List. If the
342: * specified array is large enough to hold the elements, the specified array
343: * is used, otherwise an array of the same type is created. If the specified
344: * array is used and is larger than this List, the array element following
345: * the collection elements is set to null.
346: *
347: * @param array
348: * the array
349: * @return an array of the elements from this List
350: *
351: * @exception ArrayStoreException
352: * when the type of an element in this List cannot be stored
353: * in the type of the specified array
354: */
355: public <T> T[] toArray(T[] array);
356: }
|