Source for java.util.Collection

   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.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 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: }