libjava/classpath/java/util/Collection.java

   1 /* Collection.java -- Interface that represents a collection of objects
   2    Copyright (C) 1998, 2001, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.util;
  40
  41 /**
  42  * Interface that represents a collection of objects. This interface is the
  43  * root of the collection hierarchy, and does not provide any guarantees about
  44  * the order of its elements or whether or not duplicate elements are
  45  * permitted.
  46  * <p>
  47  * All methods of this interface that are defined to modify the collection are
  48  * defined as <dfn>optional</dfn>. An optional operation may throw an
  49  * UnsupportedOperationException if the data backing this collection does not
  50  * support such a modification. This may mean that the data structure is
  51  * immutable, or that it is read-only but may change ("unmodifiable"), or
  52  * that it is modifiable but of fixed size (such as an array), or any number
  53  * of other combinations.
  54  * <p>
  55  * A class that wishes to implement this interface should consider subclassing
  56  * AbstractCollection, which provides basic implementations of most of the
  57  * methods of this interface. Classes that are prepared to make guarantees
  58  * about ordering or about absence of duplicate elements should consider
  59  * implementing List or Set respectively, both of which are subinterfaces of
  60  * Collection.
  61  * <p>
  62  * A general-purpose implementation of the Collection interface should in most
  63  * cases provide at least two constructors: One which takes no arguments and
  64  * creates an empty collection, and one which takes a Collection as an argument
  65  * and returns a collection containing the same elements (that is, creates a
  66  * copy of the argument using its own implementation).
  67  *
  68  * @author Original author unknown
  69  * @author Eric Blake (ebb9@email.byu.edu)
  70  * @see List
  71  * @see Set
  72  * @see Map
  73  * @see SortedSet
  74  * @see SortedMap
  75  * @see HashSet
  76  * @see TreeSet
  77  * @see ArrayList
  78  * @see LinkedList
  79  * @see Vector
  80  * @see Collections
  81  * @see Arrays
  82  * @see AbstractCollection
  83  * @since 1.2
  84  * @status updated to 1.5 (minus generics)
  85  */
  86 public interface Collection extends Iterable
  87 {
  88   /**
  89    * Add an element to this collection.
  90    *
  91    * @param o the object to add.
  92    * @return true if the collection was modified as a result of this action.
  93    * @throws UnsupportedOperationException if this collection does not
  94    *   support the add operation.
  95    * @throws ClassCastException if o cannot be added to this collection due
  96    *   to its type.
  97    * @throws NullPointerException if o is null and this collection doesn't
  98    *   support the addition of null values.
  99    * @throws IllegalArgumentException if o cannot be added to this
 100    *   collection for some other reason.
 101    */
 102   boolean add(Object o);
 103
 104   /**
 105    * Add the contents of a given collection to this collection.
 106    *
 107    * @param c the collection to add.
 108    * @return true if the collection was modified as a result of this action.
 109    * @throws UnsupportedOperationException if this collection does not
 110    *   support the addAll operation.
 111    * @throws ClassCastException if some element of c cannot be added to this
 112    *   collection due to its type.
 113    * @throws NullPointerException if some element of c is null and this
 114    *   collection does not support the addition of null values.
 115    * @throws NullPointerException if c itself is null.
 116    * @throws IllegalArgumentException if some element of c cannot be added
 117    *   to this collection for some other reason.
 118    */
 119   boolean addAll(Collection c);
 120
 121   /**
 122    * Clear the collection, such that a subsequent call to isEmpty() would
 123    * return true.
 124    *
 125    * @throws UnsupportedOperationException if this collection does not
 126    *   support the clear operation.
 127    */
 128   void clear();
 129
 130   /**
 131    * Test whether this collection contains a given object as one of its
 132    * elements.
 133    *
 134    * @param o the element to look for.
 135    * @return true if this collection contains at least one element e such that
 136    *   <code>o == null ? e == null : o.equals(e)</code>.
 137    * @throws ClassCastException if the type of o is not a valid type for this
 138    *   collection.
 139    * @throws NullPointerException if o is null and this collection doesn't
 140    *   support null values.
 141    */
 142   boolean contains(Object o);
 143
 144   /**
 145    * Test whether this collection contains every element in a given collection.
 146    *
 147    * @param c the collection to test for.
 148    * @return true if for every element o in c, contains(o) would return true.
 149    * @throws ClassCastException if the type of any element in c is not a valid
 150    *   type for this collection.
 151    * @throws NullPointerException if some element of c is null and this
 152    *   collection does not support null values.
 153    * @throws NullPointerException if c itself is null.
 154    */
 155   boolean containsAll(Collection c);
 156
 157   /**
 158    * Test whether this collection is equal to some object. The Collection
 159    * interface does not explicitly require any behaviour from this method, and
 160    * it may be left to the default implementation provided by Object. The Set
 161    * and List interfaces do, however, require specific behaviour from this
 162    * method.
 163    * <p>
 164    * If an implementation of Collection, which is not also an implementation of
 165    * Set or List, should choose to implement this method, it should take care
 166    * to obey the contract of the equals method of Object. In particular, care
 167    * should be taken to return false when o is a Set or a List, in order to
 168    * preserve the symmetry of the relation.
 169    *
 170    * @param o the object to compare to this collection.
 171    * @return true if the o is equal to this collection.
 172    */
 173   boolean equals(Object o);
 174
 175   /**
 176    * Obtain a hash code for this collection. The Collection interface does not
 177    * explicitly require any behaviour from this method, and it may be left to
 178    * the default implementation provided by Object. The Set and List interfaces
 179    * do, however, require specific behaviour from this method.
 180    * <p>
 181    * If an implementation of Collection, which is not also an implementation of
 182    * Set or List, should choose to implement this method, it should take care
 183    * to obey the contract of the hashCode method of Object. Note that this
 184    * method renders it impossible to correctly implement both Set and List, as
 185    * the required implementations are mutually exclusive.
 186    *
 187    * @return a hash code for this collection.
 188    */
 189   int hashCode();
 190
 191   /**
 192    * Test whether this collection is empty, that is, if size() == 0.
 193    *
 194    * @return true if this collection contains no elements.
 195    */
 196   boolean isEmpty();
 197
 198   /**
 199    * Obtain an Iterator over this collection.
 200    *
 201    * @return an Iterator over the elements of this collection, in any order.
 202    */
 203   Iterator iterator();
 204
 205   /**
 206    * Remove a single occurrence of an object from this collection. That is,
 207    * remove an element e, if one exists, such that <code>o == null ? e == null
 208    *   : o.equals(e)</code>.
 209    *
 210    * @param o the object to remove.
 211    * @return true if the collection changed as a result of this call, that is,
 212    *   if the collection contained at least one occurrence of o.
 213    * @throws UnsupportedOperationException if this collection does not
 214    *   support the remove operation.
 215    * @throws ClassCastException if the type of o is not a valid type
 216    *   for this collection.
 217    * @throws NullPointerException if o is null and the collection doesn't
 218    *   support null values.
 219    */
 220   boolean remove(Object o);
 221
 222   /**
 223    * Remove all elements of a given collection from this collection. That is,
 224    * remove every element e such that c.contains(e).
 225    *
 226    * @param c The collection of objects to be removed.
 227    * @return true if this collection was modified as a result of this call.
 228    * @throws UnsupportedOperationException if this collection does not
 229    *   support the removeAll operation.
 230    * @throws ClassCastException if the type of any element in c is not a valid
 231    *   type for this collection.
 232    * @throws NullPointerException if some element of c is null and this
 233    *   collection does not support removing null values.
 234    * @throws NullPointerException if c itself is null.
 235    */
 236   boolean removeAll(Collection c);
 237
 238   /**
 239    * Remove all elements of this collection that are not contained in a given
 240    * collection. That is, remove every element e such that !c.contains(e).
 241    *
 242    * @param c The collection of objects to be retained.
 243    * @return true if this collection was modified as a result of this call.
 244    * @throws UnsupportedOperationException if this collection does not
 245    *   support the retainAll operation.
 246    * @throws ClassCastException if the type of any element in c is not a valid
 247    *   type for this collection.
 248    * @throws NullPointerException if some element of c is null and this
 249    *   collection does not support retaining null values.
 250    * @throws NullPointerException if c itself is null.
 251    */
 252   boolean retainAll(Collection c);
 253
 254   /**
 255    * Get the number of elements in this collection.
 256    *
 257    * @return the number of elements in the collection.
 258    */
 259   int size();
 260
 261   /**
 262    * Copy the current contents of this collection into an array.
 263    *
 264    * @return an array of type Object[] and length equal to the size of this
 265    *   collection, containing the elements currently in this collection, in
 266    *   any order.
 267    */
 268   Object[] toArray();
 269
 270   /**
 271    * Copy the current contents of this collection into an array. If the array
 272    * passed as an argument has length less than the size of this collection, an
 273    * array of the same run-time type as a, and length equal to the size of this
 274    * collection, is allocated using Reflection. Otherwise, a itself is used.
 275    * The elements of this collection are copied into it, and if there is space
 276    * in the array, the following element is set to null. The resultant array is
 277    * returned.
 278    * Note: The fact that the following element is set to null is only useful
 279    * if it is known that this collection does not contain any null elements.
 280    *
 281    * @param a the array to copy this collection into.
 282    * @return an array containing the elements currently in this collection, in
 283    *   any order.
 284    * @throws ArrayStoreException if the type of any element of the
 285    *   collection is not a subtype of the element type of a.
 286    */
 287   Object[] toArray(Object[] a);
 288 }