libjava/java/util/Collection.java

   1 /* Collection.java -- Interface that represents a collection of objects
   2    Copyright (C) 1998, 2001 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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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.4
  85  */
  86 public interface Collection
  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 IllegalArgumentException if o cannot be added to this
  98    *   collection for some other reason.
  99    */
 100   boolean add(Object o);
 101
 102   /**
 103    * Add the contents of a given collection to this collection.
 104    *
 105    * @param c the collection to add.
 106    * @return true if the collection was modified as a result of this action.
 107    * @throws UnsupportedOperationException if this collection does not
 108    *   support the addAll operation.
 109    * @throws ClassCastException if some element of c cannot be added to this
 110    *   collection due to its type.
 111    * @throws IllegalArgumentException if some element of c cannot be added
 112    *   to this collection for some other reason.
 113    */
 114   boolean addAll(Collection c);
 115
 116   /**
 117    * Clear the collection, such that a subsequent call to isEmpty() would
 118    * return true.
 119    *
 120    * @throws UnsupportedOperationException if this collection does not
 121    *   support the clear operation.
 122    */
 123   void clear();
 124
 125   /**
 126    * Test whether this collection contains a given object as one of its
 127    * elements.
 128    *
 129    * @param o the element to look for.
 130    * @return true if this collection contains at least one element e such that
 131    *   <code>o == null ? e == null : o.equals(e)</code>.
 132    */
 133   boolean contains(Object o);
 134
 135   /**
 136    * Test whether this collection contains every element in a given collection.
 137    *
 138    * @param c the collection to test for.
 139    * @return true if for every element o in c, contains(o) would return true.
 140    */
 141   boolean containsAll(Collection c);
 142
 143   /**
 144    * Test whether this collection is equal to some object. The Collection
 145    * interface does not explicitly require any behaviour from this method, and
 146    * it may be left to the default implementation provided by Object. The Set
 147    * and List interfaces do, however, require specific behaviour from this
 148    * method.
 149    * <p>
 150    * If an implementation of Collection, which is not also an implementation of
 151    * Set or List, should choose to implement this method, it should take care
 152    * to obey the contract of the equals method of Object. In particular, care
 153    * should be taken to return false when o is a Set or a List, in order to
 154    * preserve the symmetry of the relation.
 155    *
 156    * @param o the object to compare to this collection.
 157    * @return true if the o is equal to this collection.
 158    */
 159   boolean equals(Object o);
 160
 161   /**
 162    * Obtain a hash code for this collection. The Collection interface does not
 163    * explicitly require any behaviour from this method, and it may be left to
 164    * the default implementation provided by Object. The Set and List interfaces
 165    * do, however, require specific behaviour from this method.
 166    * <p>
 167    * If an implementation of Collection, which is not also an implementation of
 168    * Set or List, should choose to implement this method, it should take care
 169    * to obey the contract of the hashCode method of Object. Note that this
 170    * method renders it impossible to correctly implement both Set and List, as
 171    * the required implementations are mutually exclusive.
 172    *
 173    * @return a hash code for this collection.
 174    */
 175   int hashCode();
 176
 177   /**
 178    * Test whether this collection is empty, that is, if size() == 0.
 179    *
 180    * @return true if this collection contains no elements.
 181    */
 182   boolean isEmpty();
 183
 184   /**
 185    * Obtain an Iterator over this collection.
 186    *
 187    * @return an Iterator over the elements of this collection, in any order.
 188    */
 189   Iterator iterator();
 190
 191   /**
 192    * Remove a single occurrence of an object from this collection. That is,
 193    * remove an element e, if one exists, such that <code>o == null ? e == null
 194    *   : o.equals(e)</code>.
 195    *
 196    * @param o the object to remove.
 197    * @return true if the collection changed as a result of this call, that is,
 198    *   if the collection contained at least one occurrence of o.
 199    * @throws UnsupportedOperationException if this collection does not
 200    *   support the remove operation.
 201    */
 202   boolean remove(Object o);
 203
 204   /**
 205    * Remove all elements of a given collection from this collection. That is,
 206    * remove every element e such that c.contains(e).
 207    *
 208    * @return true if this collection was modified as a result of this call.
 209    * @throws UnsupportedOperationException if this collection does not
 210    *   support the removeAll operation.
 211    */
 212   boolean removeAll(Collection c);
 213
 214   /**
 215    * Remove all elements of this collection that are not contained in a given
 216    * collection. That is, remove every element e such that !c.contains(e).
 217    *
 218    * @return true if this collection was modified as a result of this call.
 219    * @throws UnsupportedOperationException if this collection does not
 220    *   support the retainAll operation.
 221    */
 222   boolean retainAll(Collection c);
 223
 224   /**
 225    * Get the number of elements in this collection.
 226    *
 227    * @return the number of elements in the collection.
 228    */
 229   int size();
 230
 231   /**
 232    * Copy the current contents of this collection into an array.
 233    *
 234    * @return an array of type Object[] and length equal to the size of this
 235    *   collection, containing the elements currently in this collection, in
 236    *   any order.
 237    */
 238   Object[] toArray();
 239
 240   /**
 241    * Copy the current contents of this collection into an array. If the array
 242    * passed as an argument has length less than the size of this collection, an
 243    * array of the same run-time type as a, and length equal to the size of this
 244    * collection, is allocated using Reflection. Otherwise, a itself is used.
 245    * The elements of this collection are copied into it, and if there is space
 246    * in the array, the following element is set to null. The resultant array is
 247    * returned.
 248    * Note: The fact that the following element is set to null is only useful
 249    * if it is known that this collection does not contain any null elements.
 250    *
 251    * @param a the array to copy this collection into.
 252    * @return an array containing the elements currently in this collection, in
 253    *   any order.
 254    * @throws ArrayStoreException if the type of any element of the
 255    *   collection is not a subtype of the element type of a.
 256    */
 257   Object[] toArray(Object[] a);
 258 }