AbstractSequentialList.java: Synchronize with Classpath.

        * java/util/AbstractSequentialList.java: Synchronize with Classpath.
        * java/util/Collection.java: Likewise.
        * java/util/Comparator.java: Likewise.
        * java/util/Dictionary.java: Likewise.
        * java/util/Iterator.java: Likewise.
        * java/util/ListIterator.java: Likewise.
        * java/util/Map.java: Likewise.
        * java/util/Set.java: Likewise.

From-SVN: r39708

1 files changed, 226 insertions, 27 deletions

diff --git a/libjava/java/util/Collection.java b/libjava/java/util/Collection.java
index 46da71b..b7dbb69 100644
--- a/libjava/java/util/Collection.java
+++ b/libjava/java/util/Collection.java
@@ -1,37 +1,236 @@
-/* Copyright (C) 2000  Free Software Foundation
+/* Collection.java -- Interface that represents a collection of objects
+   Copyright (C) 1998 Free Software Foundation, Inc.
 
-   This file is part of libgcj.
+This file is part of GNU Classpath.
 
-This software is copyrighted work licensed under the terms of the
-Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
-details.  */
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+As a special exception, if you link this library with other files to
+produce an executable, this library does not by itself cause the
+resulting executable to be covered by the GNU General Public License.
+This exception does not however invalidate any other reasons why the
+executable file might be covered by the GNU General Public License. */
+
+
+// TO DO:
+// ~ Maybe some more @see clauses would be helpful.
 
 package java.util;
 
 /**
- * @author Warren Levy <warrenl@cygnus.com>
- * @date March 16, 2000.
- */
-/* Written using on-line Java Platform 1.2 API Specification.
- * Status:  Believed complete and correct.
+ * Interface that represents a collection of objects. This interface is the
+ * root of the collection hierarchy, and does not provide any guarantees about
+ * the order of its elements or whether or not duplicate elements are
+ * permitted.
+ * <p>
+ * All methods of this interface that are defined to modify the collection are
+ * defined as <dfn>optional</dfn>. 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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).
+ *
+ * @see java.util.List
+ * @see java.util.Set
+ * @see java.util.AbstractCollection
  */
-
-// JDK1.2
 public interface Collection
 {
-  public int size();
-  public boolean isEmpty();
-  public boolean contains(Object o);
-  public Iterator iterator();
-  public Object[] toArray();
-  public Object[] toArray(Object[] a);
-  public boolean add(Object o);
-  public boolean remove(Object o);
-  public boolean containsAll(Collection c);
-  public boolean addAll(Collection c);
-  public boolean removeAll(Collection c);
-  public boolean retainAll(Collection c);
-  public void clear();
-  public boolean equals(Object o);
-  public int hashCode();
+  /**
+   * Add an element to this collection.
+   *
+   * @param o the object to add.
+   * @returns true if the collection was modified as a result of this action.
+   * @exception UnsupportedOperationException if this collection does not
+   *   support the add operation.
+   * @exception ClassCastException if o cannot be added to this collection due
+   *   to its type.
+   * @exception IllegalArgumentException if o cannot be added to this
+   *   collection for some other reason.
+   */
+  boolean add(Object o);
+
+  /**
+   * Add the contents of a given collection to this collection.
+   *
+   * @param c the collection to add.
+   * @returns true if the collection was modified as a result of this action.
+   * @exception UnsupportedOperationException if this collection does not
+   *   support the addAll operation.
+   * @exception ClassCastException if some element of c cannot be added to this
+   *   collection due to its type.
+   * @exception IllegalArgumentException if some element of c cannot be added
+   *   to this collection for some other reason.
+   */
+  boolean addAll(Collection c);
+
+  /**
+   * Clear the collection, such that a subsequent call to isEmpty() would
+   * return true.
+   *
+   * @exception UnsupportedOperationException if this collection does not
+   *   support the clear operation.
+   */
+  void clear();
+
+  /**
+   * Test whether this collection contains a given object as one of its
+   * elements.
+   *
+   * @param o the element to look for.
+   * @returns true if this collection contains at least one element e such that
+   *   <code>o == null ? e == null : o.equals(e)</code>.
+   */
+  boolean contains(Object o);
+
+  /**
+   * Test whether this collection contains every element in a given collection.
+   *
+   * @param c the collection to test for.
+   * @returns 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.
+   * <p>
+   * 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.
+   * @returns 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.
+   * <p>
+   * 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.
+   *
+   * @returns a hash code for this collection.
+   */
+  int hashCode();
+
+  /**
+   * Test whether this collection is empty, that is, if size() == 0.
+   *
+   * @returns true if this collection contains no elements.
+   */
+  boolean isEmpty();
+
+  /**
+   * Obtain an Iterator over this collection.
+   *
+   * @returns 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 <code>o == null ? e == null
+   *   : o.equals(e)</code>.
+   *
+   * @param o the object to remove.
+   * @returns true if the collection changed as a result of this call, that is,
+   *   if the collection contained at least one occurrence of o.
+   * @exception 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).
+   *
+   * @returns true if this collection was modified as a result of this call.
+   * @exception 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).
+   *
+   * @returns true if this collection was modified as a result of this call.
+   * @exception UnsupportedOperationException if this collection does not
+   *   support the retainAll operation.
+   */
+  boolean retainAll(Collection c);
+
+  /**
+   * Get the number of elements in this collection.
+   *
+   * @returns the number of elements in the collection.
+   */
+  int size();
+
+  /**
+   * Copy the current contents of this collection into an array.
+   *
+   * @returns 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.
+   * @returns an array containing the elements currently in this collection, in
+   *   any order.
+   * @exception ArrayStoreException if the type of any element of the
+   *   collection is not a subtype of the element type of a.
+   */
+  Object[] toArray(Object[] a);
 }