* All methods of this interface that are defined to modify the collection are * defined as optional. 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. *
* 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. *
* 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
* 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.
*
* 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 o == null ? e == null : o.equals(e).
*/
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.
*/
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.
* o == null ? e == null
* : o.equals(e).
*
* @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.
*/
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).
*
* @return true if this collection was modified as a result of this call.
* @throws UnsupportedOperationException if this collection does not
* support the removeAll operation.
*/
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).
*
* @return true if this collection was modified as a result of this call.
* @throws UnsupportedOperationException if this collection does not
* support the retainAll operation.
*/
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);
}