1. /*

  2.  * @(#)Collection.java	1.31 00/02/02

  3.  *

  4.  * Copyright 1997-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.util;

  12. 

  13. /**

  14.  * The root interface in the <i>collection hierarchy</i>.  A collection

  15.  * represents a group of objects, known as its <i>elements</i>.  Some

  16.  * collections allow duplicate elements and others do not.  Some are ordered

  17.  * and others unordered.  The SDK does not provide any <i>direct</i>

  18.  * implementations of this interface: it provides implementations of more

  19.  * specific subinterfaces like <tt>Set</tt> and <tt>List</tt>.  This interface

  20.  * is typically used to pass collections around and manipulate them where

  21.  * maximum generality is desired.<p>

  22.  *

  23.  * <i>Bags</i> or <i>multisets</i> (unordered collections that may contain

  24.  * duplicate elements) should implement this interface directly.<p>

  25.  *

  26.  * All general-purpose <tt>Collection</tt> implementation classes (which

  27.  * typically implement <tt>Collection</tt> indirectly through one of its

  28.  * subinterfaces) should provide two "standard" constructors: a void (no

  29.  * arguments) constructor, which creates an empty collection, and a

  30.  * constructor with a single argument of type <tt>Collection</tt>, which

  31.  * creates a new collection with the same elements as its argument.  In

  32.  * effect, the latter constructor allows the user to copy any collection,

  33.  * producing an equivalent collection of the desired implementation type.

  34.  * There is no way to enforce this convention (as interfaces cannot contain

  35.  * constructors) but all of the general-purpose <tt>Collection</tt>

  36.  * implementations in the SDK comply.<p>

  37.  *

  38.  * @author  Josh Bloch

  39.  * @version 1.31, 02/02/00

  40.  * @see	    Set

  41.  * @see	    List

  42.  * @see	    Map

  43.  * @see	    SortedSet

  44.  * @see	    SortedMap

  45.  * @see	    HashSet

  46.  * @see	    TreeSet

  47.  * @see	    ArrayList

  48.  * @see	    LinkedList

  49.  * @see	    Vector

  50.  * @see     Collections

  51.  * @see	    Arrays

  52.  * @see	    AbstractCollection

  53.  * @since   1.2

  54.  */

  55. 

  56. public interface Collection {

  57.     // Query Operations

  58. 

  59.     /**

  60.      * Returns the number of elements in this collection.  If this collection

  61.      * contains more than <tt>Integer.MAX_VALUE</tt> elements, returns

  62.      * <tt>Integer.MAX_VALUE</tt>.

  63.      * 

  64.      * @return the number of elements in this collection

  65.      */

  66.     int size();

  67. 

  68.     /**

  69.      * Returns <tt>true</tt> if this collection contains no elements.

  70.      *

  71.      * @return <tt>true</tt> if this collection contains no elements

  72.      */

  73.     boolean isEmpty();

  74. 

  75.     /**

  76.      * Returns <tt>true</tt> if this collection contains the specified

  77.      * element.  More formally, returns <tt>true</tt> if and only if this

  78.      * collection contains at least one element <tt>e</tt> such that

  79.      * <tt>(o==null ? e==null : o.equals(e))</tt>.

  80.      *

  81.      * @param o element whose presence in this collection is to be tested.

  82.      * @return <tt>true</tt> if this collection contains the specified

  83.      *         element

  84.      */

  85.     boolean contains(Object o);

  86. 

  87.     /**

  88.      * Returns an iterator over the elements in this collection.  There are no

  89.      * guarantees concerning the order in which the elements are returned

  90.      * (unless this collection is an instance of some class that provides a

  91.      * guarantee).

  92.      * 

  93.      * @return an <tt>Iterator</tt> over the elements in this collection

  94.      */

  95.     Iterator iterator();

  96. 

  97.     /**

  98.      * Returns an array containing all of the elements in this collection.  If

  99.      * the collection makes any guarantees as to what order its elements are

  100.      * returned by its iterator, this method must return the elements in the

  101.      * same order.<p>

  102.      *

  103.      * The returned array will be "safe" in that no references to it are

  104.      * maintained by this collection.  (In other words, this method must

  105.      * allocate a new array even if this collection is backed by an array).

  106.      * The caller is thus free to modify the returned array.<p>

  107.      *

  108.      * This method acts as bridge between array-based and collection-based

  109.      * APIs.

  110.      *

  111.      * @return an array containing all of the elements in this collection

  112.      */

  113.     Object[] toArray();

  114. 

  115.     /**

  116.      * Returns an array containing all of the elements in this collection

  117.      * whose runtime type is that of the specified array.  If the collection

  118.      * fits in the specified array, it is returned therein.  Otherwise, a new

  119.      * array is allocated with the runtime type of the specified array and the

  120.      * size of this collection.<p>

  121.      *

  122.      * If this collection fits in the specified array with room to spare

  123.      * (i.e., the array has more elements than this collection), the element

  124.      * in the array immediately following the end of the collection is set to

  125.      * <tt>null</tt>.  This is useful in determining the length of this

  126.      * collection <i>only</i> if the caller knows that this collection does

  127.      * not contain any <tt>null</tt> elements.)<p>

  128.      *

  129.      * If this collection makes any guarantees as to what order its elements

  130.      * are returned by its iterator, this method must return the elements in

  131.      * the same order.<p>

  132.      *

  133.      * Like the <tt>toArray</tt> method, this method acts as bridge between

  134.      * array-based and collection-based APIs.  Further, this method allows

  135.      * precise control over the runtime type of the output array, and may,

  136.      * under certain circumstances, be used to save allocation costs<p>

  137.      *

  138.      * Suppose <tt>l</tt> is a <tt>List</tt> known to contain only strings.

  139.      * The following code can be used to dump the list into a newly allocated

  140.      * array of <tt>String</tt>:

  141.      *

  142.      * <pre>

  143.      *     String[] x = (String[]) v.toArray(new String[0]);

  144.      * </pre><p>

  145.      *

  146.      * Note that <tt>toArray(new Object[0])</tt> is identical in function to

  147.      * <tt>toArray()</tt>.

  148.      *

  149.      * @param a the array into which the elements of this collection are to be

  150.      *        stored, if it is big enough; otherwise, a new array of the same

  151.      *        runtime type is allocated for this purpose.

  152.      * @return an array containing the elements of this collection

  153.      * 

  154.      * @throws ArrayStoreException the runtime type of the specified array is

  155.      *         not a supertype of the runtime type of every element in this

  156.      *         collection.

  157.      */

  158.     

  159.     Object[] toArray(Object a[]);

  160. 

  161.     // Modification Operations

  162. 

  163.     /**

  164.      * Ensures that this collection contains the specified element (optional

  165.      * operation).  Returns <tt>true</tt> if this collection changed as a

  166.      * result of the call.  (Returns <tt>false</tt> if this collection does

  167.      * not permit duplicates and already contains the specified element.)<p>

  168.      *

  169.      * Collections that support this operation may place limitations on what

  170.      * elements may be added to this collection.  In particular, some

  171.      * collections will refuse to add <tt>null</tt> elements, and others will

  172.      * impose restrictions on the type of elements that may be added.

  173.      * Collection classes should clearly specify in their documentation any

  174.      * restrictions on what elements may be added.<p>

  175.      *

  176.      * If a collection refuses to add a particular element for any reason

  177.      * other than that it already contains the element, it <i>must</i> throw

  178.      * an exception (rather than returning <tt>false</tt>).  This preserves

  179.      * the invariant that a collection always contains the specified element

  180.      * after this call returns.

  181.      *

  182.      * @param o element whose presence in this collection is to be ensured.

  183.      * @return <tt>true</tt> if this collection changed as a result of the

  184.      *         call

  185.      * 

  186.      * @throws UnsupportedOperationException add is not supported by this

  187.      *         collection.

  188.      * @throws ClassCastException class of the specified element prevents it

  189.      *         from being added to this collection.

  190.      * @throws IllegalArgumentException some aspect of this element prevents

  191.      *          it from being added to this collection.

  192.      */

  193.     boolean add(Object o);

  194. 

  195.     /**

  196.      * Removes a single instance of the specified element from this

  197.      * collection, if it is present (optional operation).  More formally,

  198.      * removes an element <tt>e</tt> such that <tt>(o==null ?  e==null :

  199.      * o.equals(e))</tt>, if this collection contains one or more such

  200.      * elements.  Returns true if this collection contained the specified

  201.      * element (or equivalently, if this collection changed as a result of the

  202.      * call).

  203.      *

  204.      * @param o element to be removed from this collection, if present.

  205.      * @return <tt>true</tt> if this collection changed as a result of the

  206.      *         call

  207.      * 

  208.      * @throws UnsupportedOperationException remove is not supported by this

  209.      *         collection.

  210.      */

  211.     boolean remove(Object o);

  212. 

  213. 

  214.     // Bulk Operations

  215. 

  216.     /**

  217.      * Returns <tt>true</tt> if this collection contains all of the elements

  218.      * in the specified collection.

  219.      *

  220.      * @param c collection to be checked for containment in this collection.

  221.      * @return <tt>true</tt> if this collection contains all of the elements

  222.      *	       in the specified collection

  223.      * @see #contains(Object)

  224.      */

  225.     boolean containsAll(Collection c);

  226. 

  227.     /**

  228.      * Adds all of the elements in the specified collection to this collection

  229.      * (optional operation).  The behavior of this operation is undefined if

  230.      * the specified collection is modified while the operation is in progress.

  231.      * (This implies that the behavior of this call is undefined if the

  232.      * specified collection is this collection, and this collection is

  233.      * nonempty.)

  234.      *

  235.      * @param c elements to be inserted into this collection.

  236.      * @return <tt>true</tt> if this collection changed as a result of the

  237.      *         call

  238.      * 

  239.      * @throws UnsupportedOperationException if this collection does not

  240.      *         support the <tt>addAll</tt> method.

  241.      * @throws ClassCastException if the class of an element of the specified

  242.      * 	       collection prevents it from being added to this collection.

  243.      * @throws IllegalArgumentException some aspect of an element of the

  244.      *	       specified collection prevents it from being added to this

  245.      *	       collection.

  246.      * 

  247.      * @see #add(Object)

  248.      */

  249.     boolean addAll(Collection c);

  250. 

  251.     /**

  252.      * 

  253.      * Removes all this collection's elements that are also contained in the

  254.      * specified collection (optional operation).  After this call returns,

  255.      * this collection will contain no elements in common with the specified

  256.      * collection.

  257.      *

  258.      * @param c elements to be removed from this collection.

  259.      * @return <tt>true</tt> if this collection changed as a result of the

  260.      *         call

  261.      * 

  262.      * @throws UnsupportedOperationException if the <tt>removeAll</tt> method

  263.      * 	       is not supported by this collection.

  264.      * 

  265.      * @see #remove(Object)

  266.      * @see #contains(Object)

  267.      */

  268.     boolean removeAll(Collection c);

  269. 

  270.     /**

  271.      * Retains only the elements in this collection that are contained in the

  272.      * specified collection (optional operation).  In other words, removes from

  273.      * this collection all of its elements that are not contained in the

  274.      * specified collection.

  275.      *

  276.      * @param c elements to be retained in this collection.

  277.      * @return <tt>true</tt> if this collection changed as a result of the

  278.      *         call

  279.      * 

  280.      * @throws UnsupportedOperationException if the <tt>retainAll</tt> method

  281.      * 	       is not supported by this Collection.

  282.      * 

  283.      * @see #remove(Object)

  284.      * @see #contains(Object)

  285.      */

  286.     boolean retainAll(Collection c);

  287. 

  288.     /**

  289.      * Removes all of the elements from this collection (optional operation).

  290.      * This collection will be empty after this method returns unless it

  291.      * throws an exception.

  292.      *

  293.      * @throws UnsupportedOperationException if the <tt>clear</tt> method is

  294.      *         not supported by this collection.

  295.      */

  296.     void clear();

  297. 

  298. 

  299.     // Comparison and hashing

  300. 

  301.     /**

  302.      * Compares the specified object with this collection for equality. <p>

  303.      *

  304.      * While the <tt>Collection</tt> interface adds no stipulations to the

  305.      * general contract for the <tt>Object.equals</tt>, programmers who

  306.      * implement the <tt>Collection</tt> interface "directly" (in other words,

  307.      * create a class that is a <tt>Collection</tt> but is not a <tt>Set</tt>

  308.      * or a <tt>List</tt>) must exercise care if they choose to override the

  309.      * <tt>Object.equals</tt>.  It is not necessary to do so, and the simplest

  310.      * course of action is to rely on <tt>Object</tt>'s implementation, but

  311.      * the implementer may wish to implement a "value comparison" in place of

  312.      * the default "reference comparison."  (The <tt>List</tt> and

  313.      * <tt>Set</tt> interfaces mandate such value comparisons.)<p>

  314.      *

  315.      * The general contract for the <tt>Object.equals</tt> method states that

  316.      * equals must be symmetric (in other words, <tt>a.equals(b)</tt> if and

  317.      * only if <tt>b.equals(a)</tt>).  The contracts for <tt>List.equals</tt>

  318.      * and <tt>Set.equals</tt> state that lists are only equal to other lists,

  319.      * and sets to other sets.  Thus, a custom <tt>equals</tt> method for a

  320.      * collection class that implements neither the <tt>List</tt> nor

  321.      * <tt>Set</tt> interface must return <tt>false</tt> when this collection

  322.      * is compared to any list or set.  (By the same logic, it is not possible

  323.      * to write a class that correctly implements both the <tt>Set</tt> and

  324.      * <tt>List</tt> interfaces.)

  325.      *

  326.      * @param o Object to be compared for equality with this collection.

  327.      * @return <tt>true</tt> if the specified object is equal to this

  328.      * collection

  329.      * 

  330.      * @see Object#equals(Object)

  331.      * @see Set#equals(Object)

  332.      * @see List#equals(Object)

  333.      */

  334.     boolean equals(Object o);

  335. 

  336.     /**

  337.      * 

  338.      * Returns the hash code value for this collection.  While the

  339.      * <tt>Collection</tt> interface adds no stipulations to the general

  340.      * contract for the <tt>Object.hashCode</tt> method, programmers should

  341.      * take note that any class that overrides the <tt>Object.equals</tt>

  342.      * method must also override the <tt>Object.hashCode</tt> method in order

  343.      * to satisfy the general contract for the <tt>Object.hashCode</tt>method.

  344.      * In particular, <tt>c1.equals(c2)</tt> implies that

  345.      * <tt>c1.hashCode()==c2.hashCode()</tt>.

  346.      *

  347.      * @return the hash code value for this collection

  348.      * 

  349.      * @see Object#hashCode()

  350.      * @see Object#equals(Object)

  351.      */

  352.     int hashCode();

  353. }