| /* Collection.java -- Interface that represents a collection of objects | |
| Copyright (C) 1998, 2001, 2005 Free Software Foundation, Inc. | |
| This file is part of GNU Classpath. | |
| GNU Classpath is free software; you can redistribute it and/or modify | |
| it under the terms of the GNU General Public License as published by | |
| the Free Software Foundation; either version 2, or (at your option) | |
| any later version. | |
| GNU Classpath is distributed in the hope that it will be useful, but | |
| WITHOUT ANY WARRANTY; without even the implied warranty of | |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
| General Public License for more details. | |
| You should have received a copy of the GNU General Public License | |
| along with GNU Classpath; see the file COPYING. If not, write to the | |
| Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA | |
| 02110-1301 USA. | |
| Linking this library statically or dynamically with other modules is | |
| making a combined work based on this library. Thus, the terms and | |
| conditions of the GNU General Public License cover the whole | |
| combination. | |
| As a special exception, the copyright holders of this library give you | |
| permission to link this library with independent modules to produce an | |
| executable, regardless of the license terms of these independent | |
| modules, and to copy and distribute the resulting executable under | |
| terms of your choice, provided that you also meet, for each linked | |
| independent module, the terms and conditions of the license of that | |
| module. An independent module is a module which is not derived from | |
| or based on this library. If you modify this library, you may extend | |
| this exception to your version of the library, but you are not | |
| obligated to do so. If you do not wish to do so, delete this | |
| exception statement from your version. */ | |
| package java.util; | |
| /** | |
| * Interface that represents a collection of objects. This interface is the | |
| * root of the collection hierarchy, and does not provide any guarantees about | |
| * the order of its elements or whether or not duplicate elements are | |
| * permitted. | |
| * <p> | |
| * All methods of this interface that are defined to modify the collection are | |
| * defined as <dfn>optional</dfn>. An optional operation may throw an | |
| * UnsupportedOperationException if the data backing this collection does not | |
| * support such a modification. This may mean that the data structure is | |
| * immutable, or that it is read-only but may change ("unmodifiable"), or | |
| * that it is modifiable but of fixed size (such as an array), or any number | |
| * of other combinations. | |
| * <p> | |
| * A class that wishes to implement this interface should consider subclassing | |
| * AbstractCollection, which provides basic implementations of most of the | |
| * methods of this interface. Classes that are prepared to make guarantees | |
| * about ordering or about absence of duplicate elements should consider | |
| * implementing List or Set respectively, both of which are subinterfaces of | |
| * Collection. | |
| * <p> | |
| * A general-purpose implementation of the Collection interface should in most | |
| * cases provide at least two constructors: One which takes no arguments and | |
| * creates an empty collection, and one which takes a Collection as an argument | |
| * and returns a collection containing the same elements (that is, creates a | |
| * copy of the argument using its own implementation). | |
| * | |
| * @author Original author unknown | |
| * @author Eric Blake (ebb9@email.byu.edu) | |
| * @see List | |
| * @see Set | |
| * @see Map | |
| * @see SortedSet | |
| * @see SortedMap | |
| * @see HashSet | |
| * @see TreeSet | |
| * @see ArrayList | |
| * @see LinkedList | |
| * @see Vector | |
| * @see Collections | |
| * @see Arrays | |
| * @see AbstractCollection | |
| * @since 1.2 | |
| * @status updated to 1.5 (minus generics) | |
| */ | |
| public interface Collection extends Iterable | |
| { | |
| /** | |
| * Add an element to this collection. | |
| * | |
| * @param o the object to add. | |
| * @return true if the collection was modified as a result of this action. | |
| * @throws UnsupportedOperationException if this collection does not | |
| * support the add operation. | |
| * @throws ClassCastException if o cannot be added to this collection due | |
| * to its type. | |
| * @throws NullPointerException if o is null and this collection doesn't | |
| * support the addition of null values. | |
| * @throws IllegalArgumentException if o cannot be added to this | |
| * collection for some other reason. | |
| */ | |
| boolean add(Object o); | |
| /** | |
| * Add the contents of a given collection to this collection. | |
| * | |
| * @param c the collection to add. | |
| * @return true if the collection was modified as a result of this action. | |
| * @throws UnsupportedOperationException if this collection does not | |
| * support the addAll operation. | |
| * @throws ClassCastException if some element of c cannot be added to this | |
| * collection due to its type. | |
| * @throws NullPointerException if some element of c is null and this | |
| * collection does not support the addition of null values. | |
| * @throws NullPointerException if c itself is null. | |
| * @throws IllegalArgumentException if some element of c cannot be added | |
| * to this collection for some other reason. | |
| */ | |
| boolean addAll(Collection c); | |
| /** | |
| * Clear the collection, such that a subsequent call to isEmpty() would | |
| * return true. | |
| * | |
| * @throws UnsupportedOperationException if this collection does not | |
| * support the clear operation. | |
| */ | |
| void clear(); | |
| /** | |
| * Test whether this collection contains a given object as one of its | |
| * elements. | |
| * | |
| * @param o the element to look for. | |
| * @return true if this collection contains at least one element e such that | |
| * <code>o == null ? e == null : o.equals(e)</code>. | |
| * @throws ClassCastException if the type of o is not a valid type for this | |
| * collection. | |
| * @throws NullPointerException if o is null and this collection doesn't | |
| * support null values. | |
| */ | |
| boolean contains(Object o); | |
| /** | |
| * Test whether this collection contains every element in a given collection. | |
| * | |
| * @param c the collection to test for. | |
| * @return true if for every element o in c, contains(o) would return true. | |
| * @throws ClassCastException if the type of any element in c is not a valid | |
| * type for this collection. | |
| * @throws NullPointerException if some element of c is null and this | |
| * collection does not support null values. | |
| * @throws NullPointerException if c itself is null. | |
| */ | |
| boolean containsAll(Collection c); | |
| /** | |
| * Test whether this collection is equal to some object. The Collection | |
| * interface does not explicitly require any behaviour from this method, and | |
| * it may be left to the default implementation provided by Object. The Set | |
| * and List interfaces do, however, require specific behaviour from this | |
| * method. | |
| * <p> | |
| * If an implementation of Collection, which is not also an implementation of | |
| * Set or List, should choose to implement this method, it should take care | |
| * to obey the contract of the equals method of Object. In particular, care | |
| * should be taken to return false when o is a Set or a List, in order to | |
| * preserve the symmetry of the relation. | |
| * | |
| * @param o the object to compare to this collection. | |
| * @return true if the o is equal to this collection. | |
| */ | |
| boolean equals(Object o); | |
| /** | |
| * Obtain a hash code for this collection. The Collection interface does not | |
| * explicitly require any behaviour from this method, and it may be left to | |
| * the default implementation provided by Object. The Set and List interfaces | |
| * do, however, require specific behaviour from this method. | |
| * <p> | |
| * If an implementation of Collection, which is not also an implementation of | |
| * Set or List, should choose to implement this method, it should take care | |
| * to obey the contract of the hashCode method of Object. Note that this | |
| * method renders it impossible to correctly implement both Set and List, as | |
| * the required implementations are mutually exclusive. | |
| * | |
| * @return a hash code for this collection. | |
| */ | |
| int hashCode(); | |
| /** | |
| * Test whether this collection is empty, that is, if size() == 0. | |
| * | |
| * @return true if this collection contains no elements. | |
| */ | |
| boolean isEmpty(); | |
| /** | |
| * Obtain an Iterator over this collection. | |
| * | |
| * @return an Iterator over the elements of this collection, in any order. | |
| */ | |
| Iterator iterator(); | |
| /** | |
| * Remove a single occurrence of an object from this collection. That is, | |
| * remove an element e, if one exists, such that <code>o == null ? e == null | |
| * : o.equals(e)</code>. | |
| * | |
| * @param o the object to remove. | |
| * @return true if the collection changed as a result of this call, that is, | |
| * if the collection contained at least one occurrence of o. | |
| * @throws UnsupportedOperationException if this collection does not | |
| * support the remove operation. | |
| * @throws ClassCastException if the type of o is not a valid type | |
| * for this collection. | |
| * @throws NullPointerException if o is null and the collection doesn't | |
| * support null values. | |
| */ | |
| boolean remove(Object o); | |
| /** | |
| * Remove all elements of a given collection from this collection. That is, | |
| * remove every element e such that c.contains(e). | |
| * | |
| * @param c The collection of objects to be removed. | |
| * @return true if this collection was modified as a result of this call. | |
| * @throws UnsupportedOperationException if this collection does not | |
| * support the removeAll operation. | |
| * @throws ClassCastException if the type of any element in c is not a valid | |
| * type for this collection. | |
| * @throws NullPointerException if some element of c is null and this | |
| * collection does not support removing null values. | |
| * @throws NullPointerException if c itself is null. | |
| */ | |
| boolean removeAll(Collection c); | |
| /** | |
| * Remove all elements of this collection that are not contained in a given | |
| * collection. That is, remove every element e such that !c.contains(e). | |
| * | |
| * @param c The collection of objects to be retained. | |
| * @return true if this collection was modified as a result of this call. | |
| * @throws UnsupportedOperationException if this collection does not | |
| * support the retainAll operation. | |
| * @throws ClassCastException if the type of any element in c is not a valid | |
| * type for this collection. | |
| * @throws NullPointerException if some element of c is null and this | |
| * collection does not support retaining null values. | |
| * @throws NullPointerException if c itself is null. | |
| */ | |
| boolean retainAll(Collection c); | |
| /** | |
| * Get the number of elements in this collection. | |
| * | |
| * @return the number of elements in the collection. | |
| */ | |
| int size(); | |
| /** | |
| * Copy the current contents of this collection into an array. | |
| * | |
| * @return an array of type Object[] and length equal to the size of this | |
| * collection, containing the elements currently in this collection, in | |
| * any order. | |
| */ | |
| Object[] toArray(); | |
| /** | |
| * Copy the current contents of this collection into an array. If the array | |
| * passed as an argument has length less than the size of this collection, an | |
| * array of the same run-time type as a, and length equal to the size of this | |
| * collection, is allocated using Reflection. Otherwise, a itself is used. | |
| * The elements of this collection are copied into it, and if there is space | |
| * in the array, the following element is set to null. The resultant array is | |
| * returned. | |
| * Note: The fact that the following element is set to null is only useful | |
| * if it is known that this collection does not contain any null elements. | |
| * | |
| * @param a the array to copy this collection into. | |
| * @return an array containing the elements currently in this collection, in | |
| * any order. | |
| * @throws ArrayStoreException if the type of any element of the | |
| * collection is not a subtype of the element type of a. | |
| */ | |
| Object[] toArray(Object[] a); | |
| } |