/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package java.util;
/**
* List is a collection which maintains an ordering for its elements. Every
* element in the list has an index.
*/
public interface List<E> extends Collection<E> {
/**
* Inserts the specified object into this Vector at the specified location.
* The object is inserted before any previous element at the specified
* location. If the location is equal to the size of this List, the object
* is added at the end.
*
* @param location
* the index at which to insert
* @param object
* the object to add
*
* @exception UnsupportedOperationException
* when adding to this List is not supported
* @exception ClassCastException
* when the class of the object is inappropriate for this
* List
* @exception IllegalArgumentException
* when the object cannot be added to this List
* @exception IndexOutOfBoundsException
* when <code>location < 0 || >= size()</code>
*/
public void add(int location, E object);
/**
* Adds the specified object at the end of this List.
*
* @param object
* the object to add
* @return true
*
* @exception UnsupportedOperationException
* when adding to this List is not supported
* @exception ClassCastException
* when the class of the object is inappropriate for this
* List
* @exception IllegalArgumentException
* when the object cannot be added to this List
*/
public boolean add(E object);
/**
* Inserts the objects in the specified Collection at the specified location
* in this List. The objects are added in the order they are returned from
* the Collection iterator.
*
* @param location
* the index at which to insert
* @param collection
* the Collection of objects
* @return true if this List is modified, false otherwise
*
* @exception UnsupportedOperationException
* when adding to this List is not supported
* @exception ClassCastException
* when the class of an object is inappropriate for this List
* @exception IllegalArgumentException
* when an object cannot be added to this List
* @exception IndexOutOfBoundsException
* when <code>location < 0 || >= size()</code>
*/
public boolean addAll(int location, Collection<? extends E> collection);
/**
* Adds the objects in the specified Collection to the end of this List. The
* objects are added in the order they are returned from the Collection
* iterator.
*
* @param collection
* the Collection of objects
* @return true if this List is modified, false otherwise
*
* @exception UnsupportedOperationException
* when adding to this List is not supported
* @exception ClassCastException
* when the class of an object is inappropriate for this List
* @exception IllegalArgumentException
* when an object cannot be added to this List
*/
public boolean addAll(Collection<? extends E> collection);
/**
* Removes all elements from this List, leaving it empty.
*
* @exception UnsupportedOperationException
* when removing from this List is not supported
*
* @see #isEmpty
* @see #size
*/
public void clear();
/**
* Searches this List for the specified object.
*
* @param object
* the object to search for
* @return true if object is an element of this List, false otherwise
*/
public boolean contains(Object object);
/**
* Searches this List for all objects in the specified Collection.
*
* @param collection
* the Collection of objects
* @return true if all objects in the specified Collection are elements of
* this List, false otherwise
*/
public boolean containsAll(Collection<?> collection);
/**
* Compares the argument to the receiver, and answers true if they represent
* the <em>same</em> object using a class specific comparison.
*
* @param object
* Object the object to compare with this object.
* @return boolean <code>true</code> if the object is the same as this
* object <code>false</code> if it is different from this object.
* @see #hashCode
*/
public boolean equals(Object object);
/**
* Answers the element at the specified location in this List.
*
* @param location
* the index of the element to return
* @return the element at the specified location
*
* @exception IndexOutOfBoundsException
* when <code>location < 0 || >= size()</code>
*/
public E get(int location);
/**
* Answers an integer hash code for the receiver. Objects which are equal
* answer the same value for this method.
*
* @return the receiver's hash
*
* @see #equals
*/
public int hashCode();
/**
* Searches this List for the specified object and returns the index of the
* first occurrence.
*
* @param object
* the object to search for
* @return the index of the first occurrence of the object
*/
public int indexOf(Object object);
/**
* Answers if this List has no elements, a size of zero.
*
* @return true if this List has no elements, false otherwise
*
* @see #size
*/
public boolean isEmpty();
/**
* Answers an Iterator on the elements of this List. The elements are
* iterated in the same order that they occur in the List.
*
* @return an Iterator on the elements of this List
*
* @see Iterator
*/
public Iterator<E> iterator();
/**
* Searches this List for the specified object and returns the index of the
* last occurrence.
*
* @param object
* the object to search for
* @return the index of the last occurrence of the object
*/
public int lastIndexOf(Object object);
/**
* Answers a ListIterator on the elements of this List. The elements are
* iterated in the same order that they occur in the List.
*
* @return a ListIterator on the elements of this List
*
* @see ListIterator
*/
public ListIterator<E> listIterator();
/**
* Answers a ListIterator on the elements of this List. The elements are
* iterated in the same order that they occur in the List. The iteration
* starts at the specified location.
*
* @param location
* the index at which to start the iteration
* @return a ListIterator on the elements of this List
*
* @exception IndexOutOfBoundsException
* when <code>location < 0 || >= size()</code>
*
* @see ListIterator
*/
public ListIterator<E> listIterator(int location);
/**
* Removes the object at the specified location from this List.
*
* @param location
* the index of the object to remove
* @return the removed object
*
* @exception UnsupportedOperationException
* when removing from this List is not supported
* @exception IndexOutOfBoundsException
* when <code>location < 0 || >= size()</code>
*/
public E remove(int location);
/**
* Removes the first occurrence of the specified object from this List.
*
* @param object
* the object to remove
* @return true if this List is modified, false otherwise
*
* @exception UnsupportedOperationException
* when removing from this List is not supported
*/
public boolean remove(Object object);
/**
* Removes all occurrences in this List of each object in the specified
* Collection.
*
* @param collection
* the Collection of objects to remove
* @return true if this List is modified, false otherwise
*
* @exception UnsupportedOperationException
* when removing from this List is not supported
*/
public boolean removeAll(Collection<?> collection);
/**
* Removes all objects from this List that are not contained in the
* specified Collection.
*
* @param collection
* the Collection of objects to retain
* @return true if this List is modified, false otherwise
*
* @exception UnsupportedOperationException
* when removing from this List is not supported
*/
public boolean retainAll(Collection<?> collection);
/**
* Replaces the element at the specified location in this List with the
* specified object.
*
* @param location
* the index at which to put the specified object
* @param object
* the object to add
* @return the previous element at the index
*
* @exception UnsupportedOperationException
* when replacing elements in this List is not supported
* @exception ClassCastException
* when the class of an object is inappropriate for this List
* @exception IllegalArgumentException
* when an object cannot be added to this List
* @exception IndexOutOfBoundsException
* when <code>location < 0 || >= size()</code>
*/
public E set(int location, E object);
/**
* Answers the number of elements in this List.
*
* @return the number of elements in this List
*/
public int size();
/**
* Answers a List of the specified portion of this List from the start index
* to one less than the end index. The returned List is backed by this list
* so changes to one are reflected by the other.
*
* @param start
* the index at which to start the sublist
* @param end
* the index one past the end of the sublist
* @return a List of a portion of this List
*
* @exception IndexOutOfBoundsException
* when <code>start < 0, start > end</code> or
* <code>end > size()</code>
*/
public List<E> subList(int start, int end);
/**
* Answers an array containing all elements contained in this List.
*
* @return an array of the elements from this List
*/
public Object[] toArray();
/**
* Answers an array containing all elements contained in this List. If the
* specified array is large enough to hold the elements, the specified array
* is used, otherwise an array of the same type is created. If the specified
* array is used and is larger than this List, the array element following
* the collection elements is set to null.
*
* @param array
* the array
* @return an array of the elements from this List
*
* @exception ArrayStoreException
* when the type of an element in this List cannot be stored
* in the type of the specified array
*/
public <T> T[] toArray(T[] array);
}
|