src/share/classes/java/util/Collection.java

Print this page
rev 3977 : 6546713: link the word (optional) in exception specifications to the text which provides explanation and context.


  43  * subinterfaces) should provide two "standard" constructors: a void (no
  44  * arguments) constructor, which creates an empty collection, and a
  45  * constructor with a single argument of type <tt>Collection</tt>, which
  46  * creates a new collection with the same elements as its argument.  In
  47  * effect, the latter constructor allows the user to copy any collection,
  48  * producing an equivalent collection of the desired implementation type.
  49  * There is no way to enforce this convention (as interfaces cannot contain
  50  * constructors) but all of the general-purpose <tt>Collection</tt>
  51  * implementations in the Java platform libraries comply.
  52  *
  53  * <p>The "destructive" methods contained in this interface, that is, the
  54  * methods that modify the collection on which they operate, are specified to
  55  * throw <tt>UnsupportedOperationException</tt> if this collection does not
  56  * support the operation.  If this is the case, these methods may, but are not
  57  * required to, throw an <tt>UnsupportedOperationException</tt> if the
  58  * invocation would have no effect on the collection.  For example, invoking
  59  * the {@link #addAll(Collection)} method on an unmodifiable collection may,
  60  * but is not required to, throw the exception if the collection to be added
  61  * is empty.
  62  *
  63  * <p>Some collection implementations have restrictions on the elements that

  64  * they may contain.  For example, some implementations prohibit null elements,
  65  * and some have restrictions on the types of their elements.  Attempting to
  66  * add an ineligible element throws an unchecked exception, typically
  67  * <tt>NullPointerException</tt> or <tt>ClassCastException</tt>.  Attempting
  68  * to query the presence of an ineligible element may throw an exception,
  69  * or it may simply return false; some implementations will exhibit the former
  70  * behavior and some will exhibit the latter.  More generally, attempting an
  71  * operation on an ineligible element whose completion would not result in
  72  * the insertion of an ineligible element into the collection may throw an
  73  * exception or it may succeed, at the option of the implementation.
  74  * Such exceptions are marked as "optional" in the specification for this
  75  * interface.
  76  *
  77  * <p>It is up to each collection to determine its own synchronization
  78  * policy.  In the absence of a stronger guarantee by the
  79  * implementation, undefined behavior may result from the invocation
  80  * of any method on a collection that is being mutated by another
  81  * thread; this includes direct invocations, passing the collection to
  82  * a method that might perform invocations, and using an existing
  83  * iterator to examine the collection.


 135      */
 136     int size();
 137 
 138     /**
 139      * Returns <tt>true</tt> if this collection contains no elements.
 140      *
 141      * @return <tt>true</tt> if this collection contains no elements
 142      */
 143     boolean isEmpty();
 144 
 145     /**
 146      * Returns <tt>true</tt> if this collection contains the specified element.
 147      * More formally, returns <tt>true</tt> if and only if this collection
 148      * contains at least one element <tt>e</tt> such that
 149      * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
 150      *
 151      * @param o element whose presence in this collection is to be tested
 152      * @return <tt>true</tt> if this collection contains the specified
 153      *         element
 154      * @throws ClassCastException if the type of the specified element
 155      *         is incompatible with this collection (optional)

 156      * @throws NullPointerException if the specified element is null and this
 157      *         collection does not permit null elements (optional)

 158      */
 159     boolean contains(Object o);
 160 
 161     /**
 162      * Returns an iterator over the elements in this collection.  There are no
 163      * guarantees concerning the order in which the elements are returned
 164      * (unless this collection is an instance of some class that provides a
 165      * guarantee).
 166      *
 167      * @return an <tt>Iterator</tt> over the elements in this collection
 168      */
 169     Iterator<E> iterator();
 170 
 171     /**
 172      * Returns an array containing all of the elements in this collection.
 173      * If this collection makes any guarantees as to what order its elements
 174      * are returned by its iterator, this method must return the elements in
 175      * the same order.
 176      *
 177      * <p>The returned array will be "safe" in that no references to it are


 262      *         collection does not permit null elements
 263      * @throws IllegalArgumentException if some property of the element
 264      *         prevents it from being added to this collection
 265      * @throws IllegalStateException if the element cannot be added at this
 266      *         time due to insertion restrictions
 267      */
 268     boolean add(E e);
 269 
 270     /**
 271      * Removes a single instance of the specified element from this
 272      * collection, if it is present (optional operation).  More formally,
 273      * removes an element <tt>e</tt> such that
 274      * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>, if
 275      * this collection contains one or more such elements.  Returns
 276      * <tt>true</tt> if this collection contained the specified element (or
 277      * equivalently, if this collection changed as a result of the call).
 278      *
 279      * @param o element to be removed from this collection, if present
 280      * @return <tt>true</tt> if an element was removed as a result of this call
 281      * @throws ClassCastException if the type of the specified element
 282      *         is incompatible with this collection (optional)

 283      * @throws NullPointerException if the specified element is null and this
 284      *         collection does not permit null elements (optional)

 285      * @throws UnsupportedOperationException if the <tt>remove</tt> operation
 286      *         is not supported by this collection
 287      */
 288     boolean remove(Object o);
 289 
 290 
 291     // Bulk Operations
 292 
 293     /**
 294      * Returns <tt>true</tt> if this collection contains all of the elements
 295      * in the specified collection.
 296      *
 297      * @param  c collection to be checked for containment in this collection
 298      * @return <tt>true</tt> if this collection contains all of the elements
 299      *         in the specified collection
 300      * @throws ClassCastException if the types of one or more elements
 301      *         in the specified collection are incompatible with this
 302      *         collection (optional)

 303      * @throws NullPointerException if the specified collection contains one
 304      *         or more null elements and this collection does not permit null
 305      *         elements (optional), or if the specified collection is null


 306      * @see    #contains(Object)
 307      */
 308     boolean containsAll(Collection<?> c);
 309 
 310     /**
 311      * Adds all of the elements in the specified collection to this collection
 312      * (optional operation).  The behavior of this operation is undefined if
 313      * the specified collection is modified while the operation is in progress.
 314      * (This implies that the behavior of this call is undefined if the
 315      * specified collection is this collection, and this collection is
 316      * nonempty.)
 317      *
 318      * @param c collection containing elements to be added to this collection
 319      * @return <tt>true</tt> if this collection changed as a result of the call
 320      * @throws UnsupportedOperationException if the <tt>addAll</tt> operation
 321      *         is not supported by this collection
 322      * @throws ClassCastException if the class of an element of the specified
 323      *         collection prevents it from being added to this collection
 324      * @throws NullPointerException if the specified collection contains a
 325      *         null element and this collection does not permit null elements,


 329      *         collection
 330      * @throws IllegalStateException if not all the elements can be added at
 331      *         this time due to insertion restrictions
 332      * @see #add(Object)
 333      */
 334     boolean addAll(Collection<? extends E> c);
 335 
 336     /**
 337      * Removes all of this collection's elements that are also contained in the
 338      * specified collection (optional operation).  After this call returns,
 339      * this collection will contain no elements in common with the specified
 340      * collection.
 341      *
 342      * @param c collection containing elements to be removed from this collection
 343      * @return <tt>true</tt> if this collection changed as a result of the
 344      *         call
 345      * @throws UnsupportedOperationException if the <tt>removeAll</tt> method
 346      *         is not supported by this collection
 347      * @throws ClassCastException if the types of one or more elements
 348      *         in this collection are incompatible with the specified
 349      *         collection (optional)

 350      * @throws NullPointerException if this collection contains one or more
 351      *         null elements and the specified collection does not support
 352      *         null elements (optional), or if the specified collection is null


 353      * @see #remove(Object)
 354      * @see #contains(Object)
 355      */
 356     boolean removeAll(Collection<?> c);
 357 
 358     /**
 359      * Retains only the elements in this collection that are contained in the
 360      * specified collection (optional operation).  In other words, removes from
 361      * this collection all of its elements that are not contained in the
 362      * specified collection.
 363      *
 364      * @param c collection containing elements to be retained in this collection
 365      * @return <tt>true</tt> if this collection changed as a result of the call
 366      * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation
 367      *         is not supported by this collection
 368      * @throws ClassCastException if the types of one or more elements
 369      *         in this collection are incompatible with the specified
 370      *         collection (optional)

 371      * @throws NullPointerException if this collection contains one or more
 372      *         null elements and the specified collection does not permit null
 373      *         elements (optional), or if the specified collection is null


 374      * @see #remove(Object)
 375      * @see #contains(Object)
 376      */
 377     boolean retainAll(Collection<?> c);
 378 
 379     /**
 380      * Removes all of the elements from this collection (optional operation).
 381      * The collection will be empty after this method returns.
 382      *
 383      * @throws UnsupportedOperationException if the <tt>clear</tt> operation
 384      *         is not supported by this collection
 385      */
 386     void clear();
 387 
 388 
 389     // Comparison and hashing
 390 
 391     /**
 392      * Compares the specified object with this collection for equality. <p>
 393      *




  43  * subinterfaces) should provide two "standard" constructors: a void (no
  44  * arguments) constructor, which creates an empty collection, and a
  45  * constructor with a single argument of type <tt>Collection</tt>, which
  46  * creates a new collection with the same elements as its argument.  In
  47  * effect, the latter constructor allows the user to copy any collection,
  48  * producing an equivalent collection of the desired implementation type.
  49  * There is no way to enforce this convention (as interfaces cannot contain
  50  * constructors) but all of the general-purpose <tt>Collection</tt>
  51  * implementations in the Java platform libraries comply.
  52  *
  53  * <p>The "destructive" methods contained in this interface, that is, the
  54  * methods that modify the collection on which they operate, are specified to
  55  * throw <tt>UnsupportedOperationException</tt> if this collection does not
  56  * support the operation.  If this is the case, these methods may, but are not
  57  * required to, throw an <tt>UnsupportedOperationException</tt> if the
  58  * invocation would have no effect on the collection.  For example, invoking
  59  * the {@link #addAll(Collection)} method on an unmodifiable collection may,
  60  * but is not required to, throw the exception if the collection to be added
  61  * is empty.
  62  *
  63  * <p><a name="optional-restrictions"/>
  64  * Some collection implementations have restrictions on the elements that
  65  * they may contain.  For example, some implementations prohibit null elements,
  66  * and some have restrictions on the types of their elements.  Attempting to
  67  * add an ineligible element throws an unchecked exception, typically
  68  * <tt>NullPointerException</tt> or <tt>ClassCastException</tt>.  Attempting
  69  * to query the presence of an ineligible element may throw an exception,
  70  * or it may simply return false; some implementations will exhibit the former
  71  * behavior and some will exhibit the latter.  More generally, attempting an
  72  * operation on an ineligible element whose completion would not result in
  73  * the insertion of an ineligible element into the collection may throw an
  74  * exception or it may succeed, at the option of the implementation.
  75  * Such exceptions are marked as "optional" in the specification for this
  76  * interface.
  77  *
  78  * <p>It is up to each collection to determine its own synchronization
  79  * policy.  In the absence of a stronger guarantee by the
  80  * implementation, undefined behavior may result from the invocation
  81  * of any method on a collection that is being mutated by another
  82  * thread; this includes direct invocations, passing the collection to
  83  * a method that might perform invocations, and using an existing
  84  * iterator to examine the collection.


 136      */
 137     int size();
 138 
 139     /**
 140      * Returns <tt>true</tt> if this collection contains no elements.
 141      *
 142      * @return <tt>true</tt> if this collection contains no elements
 143      */
 144     boolean isEmpty();
 145 
 146     /**
 147      * Returns <tt>true</tt> if this collection contains the specified element.
 148      * More formally, returns <tt>true</tt> if and only if this collection
 149      * contains at least one element <tt>e</tt> such that
 150      * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
 151      *
 152      * @param o element whose presence in this collection is to be tested
 153      * @return <tt>true</tt> if this collection contains the specified
 154      *         element
 155      * @throws ClassCastException if the type of the specified element
 156      *         is incompatible with this collection
 157      *         (<a href="#optional-restrictions">optional</a>)
 158      * @throws NullPointerException if the specified element is null and this
 159      *         collection does not permit null elements
 160      *         (<a href="#optional-restrictions">optional</a>)
 161      */
 162     boolean contains(Object o);
 163 
 164     /**
 165      * Returns an iterator over the elements in this collection.  There are no
 166      * guarantees concerning the order in which the elements are returned
 167      * (unless this collection is an instance of some class that provides a
 168      * guarantee).
 169      *
 170      * @return an <tt>Iterator</tt> over the elements in this collection
 171      */
 172     Iterator<E> iterator();
 173 
 174     /**
 175      * Returns an array containing all of the elements in this collection.
 176      * If this collection makes any guarantees as to what order its elements
 177      * are returned by its iterator, this method must return the elements in
 178      * the same order.
 179      *
 180      * <p>The returned array will be "safe" in that no references to it are


 265      *         collection does not permit null elements
 266      * @throws IllegalArgumentException if some property of the element
 267      *         prevents it from being added to this collection
 268      * @throws IllegalStateException if the element cannot be added at this
 269      *         time due to insertion restrictions
 270      */
 271     boolean add(E e);
 272 
 273     /**
 274      * Removes a single instance of the specified element from this
 275      * collection, if it is present (optional operation).  More formally,
 276      * removes an element <tt>e</tt> such that
 277      * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>, if
 278      * this collection contains one or more such elements.  Returns
 279      * <tt>true</tt> if this collection contained the specified element (or
 280      * equivalently, if this collection changed as a result of the call).
 281      *
 282      * @param o element to be removed from this collection, if present
 283      * @return <tt>true</tt> if an element was removed as a result of this call
 284      * @throws ClassCastException if the type of the specified element
 285      *         is incompatible with this collection
 286      *         (<a href="#optional-restrictions">optional</a>)
 287      * @throws NullPointerException if the specified element is null and this
 288      *         collection does not permit null elements
 289      *         (<a href="#optional-restrictions">optional</a>)
 290      * @throws UnsupportedOperationException if the <tt>remove</tt> operation
 291      *         is not supported by this collection
 292      */
 293     boolean remove(Object o);
 294 
 295 
 296     // Bulk Operations
 297 
 298     /**
 299      * Returns <tt>true</tt> if this collection contains all of the elements
 300      * in the specified collection.
 301      *
 302      * @param  c collection to be checked for containment in this collection
 303      * @return <tt>true</tt> if this collection contains all of the elements
 304      *         in the specified collection
 305      * @throws ClassCastException if the types of one or more elements
 306      *         in the specified collection are incompatible with this
 307      *         collection
 308      *         (<a href="#optional-restrictions">optional</a>)
 309      * @throws NullPointerException if the specified collection contains one
 310      *         or more null elements and this collection does not permit null
 311      *         elements
 312      *         (<a href="#optional-restrictions">optional</a>),
 313      *         or if the specified collection is null.
 314      * @see    #contains(Object)
 315      */
 316     boolean containsAll(Collection<?> c);
 317 
 318     /**
 319      * Adds all of the elements in the specified collection to this collection
 320      * (optional operation).  The behavior of this operation is undefined if
 321      * the specified collection is modified while the operation is in progress.
 322      * (This implies that the behavior of this call is undefined if the
 323      * specified collection is this collection, and this collection is
 324      * nonempty.)
 325      *
 326      * @param c collection containing elements to be added to this collection
 327      * @return <tt>true</tt> if this collection changed as a result of the call
 328      * @throws UnsupportedOperationException if the <tt>addAll</tt> operation
 329      *         is not supported by this collection
 330      * @throws ClassCastException if the class of an element of the specified
 331      *         collection prevents it from being added to this collection
 332      * @throws NullPointerException if the specified collection contains a
 333      *         null element and this collection does not permit null elements,


 337      *         collection
 338      * @throws IllegalStateException if not all the elements can be added at
 339      *         this time due to insertion restrictions
 340      * @see #add(Object)
 341      */
 342     boolean addAll(Collection<? extends E> c);
 343 
 344     /**
 345      * Removes all of this collection's elements that are also contained in the
 346      * specified collection (optional operation).  After this call returns,
 347      * this collection will contain no elements in common with the specified
 348      * collection.
 349      *
 350      * @param c collection containing elements to be removed from this collection
 351      * @return <tt>true</tt> if this collection changed as a result of the
 352      *         call
 353      * @throws UnsupportedOperationException if the <tt>removeAll</tt> method
 354      *         is not supported by this collection
 355      * @throws ClassCastException if the types of one or more elements
 356      *         in this collection are incompatible with the specified
 357      *         collection
 358      *         (<a href="#optional-restrictions">optional</a>)
 359      * @throws NullPointerException if this collection contains one or more
 360      *         null elements and the specified collection does not support
 361      *         null elements
 362      *         (<a href="#optional-restrictions">optional</a>),
 363      *         or if the specified collection is null
 364      * @see #remove(Object)
 365      * @see #contains(Object)
 366      */
 367     boolean removeAll(Collection<?> c);
 368 
 369     /**
 370      * Retains only the elements in this collection that are contained in the
 371      * specified collection (optional operation).  In other words, removes from
 372      * this collection all of its elements that are not contained in the
 373      * specified collection.
 374      *
 375      * @param c collection containing elements to be retained in this collection
 376      * @return <tt>true</tt> if this collection changed as a result of the call
 377      * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation
 378      *         is not supported by this collection
 379      * @throws ClassCastException if the types of one or more elements
 380      *         in this collection are incompatible with the specified
 381      *         collection
 382      *         (<a href="#optional-restrictions">optional</a>)
 383      * @throws NullPointerException if this collection contains one or more
 384      *         null elements and the specified collection does not permit null
 385      *         elements
 386      *         (<a href="#optional-restrictions">optional</a>),
 387      *         or if the specified collection is null
 388      * @see #remove(Object)
 389      * @see #contains(Object)
 390      */
 391     boolean retainAll(Collection<?> c);
 392 
 393     /**
 394      * Removes all of the elements from this collection (optional operation).
 395      * The collection will be empty after this method returns.
 396      *
 397      * @throws UnsupportedOperationException if the <tt>clear</tt> operation
 398      *         is not supported by this collection
 399      */
 400     void clear();
 401 
 402 
 403     // Comparison and hashing
 404 
 405     /**
 406      * Compares the specified object with this collection for equality. <p>
 407      *