001    /* Collection.java -- Interface that represents a collection of objects
002       Copyright (C) 1998, 2001, 2004, 2005 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.util;
040    
041    /**
042     * Interface that represents a collection of objects. This interface is the
043     * root of the collection hierarchy, and does not provide any guarantees about
044     * the order of its elements or whether or not duplicate elements are
045     * permitted.
046     * <p>
047     * All methods of this interface that are defined to modify the collection are
048     * defined as <dfn>optional</dfn>. An optional operation may throw an
049     * UnsupportedOperationException if the data backing this collection does not
050     * support such a modification. This may mean that the data structure is
051     * immutable, or that it is read-only but may change ("unmodifiable"), or
052     * that it is modifiable but of fixed size (such as an array), or any number
053     * of other combinations.
054     * <p>
055     * A class that wishes to implement this interface should consider subclassing
056     * AbstractCollection, which provides basic implementations of most of the
057     * methods of this interface. Classes that are prepared to make guarantees
058     * about ordering or about absence of duplicate elements should consider
059     * implementing List or Set respectively, both of which are subinterfaces of
060     * Collection.
061     * <p>
062     * A general-purpose implementation of the Collection interface should in most
063     * cases provide at least two constructors: One which takes no arguments and
064     * creates an empty collection, and one which takes a Collection as an argument
065     * and returns a collection containing the same elements (that is, creates a
066     * copy of the argument using its own implementation).
067     *
068     * @author Original author unknown
069     * @author Eric Blake (ebb9@email.byu.edu)
070     * @author Tom Tromey (tromey@redhat.com)
071     * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
072     * @see List
073     * @see Set
074     * @see Map
075     * @see SortedSet
076     * @see SortedMap
077     * @see HashSet
078     * @see TreeSet
079     * @see ArrayList
080     * @see LinkedList
081     * @see Vector
082     * @see Collections
083     * @see Arrays
084     * @see AbstractCollection
085     * @since 1.2
086     * @status updated to 1.4
087     */
088    public interface Collection<E> extends Iterable<E>
089    {
090      /**
091       * Add an element to this collection.
092       *
093       * @param o the object to add.
094       * @return true if the collection was modified as a result of this action.
095       * @throws UnsupportedOperationException if this collection does not
096       *   support the add operation.
097       * @throws ClassCastException if o cannot be added to this collection due
098       *   to its type.
099       * @throws NullPointerException if o is null and this collection doesn't
100       *   support the addition of null values.
101       * @throws IllegalArgumentException if o cannot be added to this
102       *   collection for some other reason.
103       */
104      boolean add(E o);
105    
106      /**
107       * Add the contents of a given collection to this collection.
108       *
109       * @param c the collection to add.
110       * @return true if the collection was modified as a result of this action.
111       * @throws UnsupportedOperationException if this collection does not
112       *   support the addAll operation.
113       * @throws ClassCastException if some element of c cannot be added to this
114       *   collection due to its type.
115       * @throws NullPointerException if some element of c is null and this
116       *   collection does not support the addition of null values.
117       * @throws NullPointerException if c itself is null.
118       * @throws IllegalArgumentException if some element of c cannot be added
119       *   to this collection for some other reason.
120       */
121      boolean addAll(Collection<? extends E> c);
122    
123      /**
124       * Clear the collection, such that a subsequent call to isEmpty() would
125       * return true.
126       *
127       * @throws UnsupportedOperationException if this collection does not
128       *   support the clear operation.
129       */
130      void clear();
131    
132      /**
133       * Test whether this collection contains a given object as one of its
134       * elements.
135       *
136       * @param o the element to look for.
137       * @return true if this collection contains at least one element e such that
138       *   <code>o == null ? e == null : o.equals(e)</code>.
139       * @throws ClassCastException if the type of o is not a valid type for this
140       *   collection.
141       * @throws NullPointerException if o is null and this collection doesn't
142       *   support null values.
143       */
144      boolean contains(Object o);
145    
146      /**
147       * Test whether this collection contains every element in a given collection.
148       *
149       * @param c the collection to test for.
150       * @return true if for every element o in c, contains(o) would return true.
151       * @throws ClassCastException if the type of any element in c is not a valid
152       *   type for this collection.
153       * @throws NullPointerException if some element of c is null and this
154       *   collection does not support null values.
155       * @throws NullPointerException if c itself is null.
156       */
157      boolean containsAll(Collection<?> c);
158    
159      /**
160       * Test whether this collection is equal to some object. The Collection
161       * interface does not explicitly require any behaviour from this method, and
162       * it may be left to the default implementation provided by Object. The Set
163       * and List interfaces do, however, require specific behaviour from this
164       * method.
165       * <p>
166       * If an implementation of Collection, which is not also an implementation of
167       * Set or List, should choose to implement this method, it should take care
168       * to obey the contract of the equals method of Object. In particular, care
169       * should be taken to return false when o is a Set or a List, in order to
170       * preserve the symmetry of the relation.
171       *
172       * @param o the object to compare to this collection.
173       * @return true if the o is equal to this collection.
174       */
175      boolean equals(Object o);
176    
177      /**
178       * Obtain a hash code for this collection. The Collection interface does not
179       * explicitly require any behaviour from this method, and it may be left to
180       * the default implementation provided by Object. The Set and List interfaces
181       * do, however, require specific behaviour from this method.
182       * <p>
183       * If an implementation of Collection, which is not also an implementation of
184       * Set or List, should choose to implement this method, it should take care
185       * to obey the contract of the hashCode method of Object. Note that this
186       * method renders it impossible to correctly implement both Set and List, as
187       * the required implementations are mutually exclusive.
188       *
189       * @return a hash code for this collection.
190       */
191      int hashCode();
192    
193      /**
194       * Test whether this collection is empty, that is, if size() == 0.
195       *
196       * @return true if this collection contains no elements.
197       */
198      boolean isEmpty();
199    
200      /**
201       * Obtain an Iterator over this collection.
202       *
203       * @return an Iterator over the elements of this collection, in any order.
204       */
205      Iterator<E> iterator();
206    
207      /**
208       * Remove a single occurrence of an object from this collection. That is,
209       * remove an element e, if one exists, such that <code>o == null ? e == null
210       *   : o.equals(e)</code>.
211       *
212       * @param o the object to remove.
213       * @return true if the collection changed as a result of this call, that is,
214       *   if the collection contained at least one occurrence of o.
215       * @throws UnsupportedOperationException if this collection does not
216       *   support the remove operation.
217       * @throws ClassCastException if the type of o is not a valid type
218       *   for this collection.
219       * @throws NullPointerException if o is null and the collection doesn't
220       *   support null values.
221       */
222      boolean remove(Object o);
223    
224      /**
225       * Remove all elements of a given collection from this collection. That is,
226       * remove every element e such that c.contains(e).
227       *
228       * @param c The collection of objects to be removed.
229       * @return true if this collection was modified as a result of this call.
230       * @throws UnsupportedOperationException if this collection does not
231       *   support the removeAll operation.
232       * @throws ClassCastException if the type of any element in c is not a valid
233       *   type for this collection.
234       * @throws NullPointerException if some element of c is null and this
235       *   collection does not support removing null values.
236       * @throws NullPointerException if c itself is null.
237       */
238      boolean removeAll(Collection<?> c);
239    
240      /**
241       * Remove all elements of this collection that are not contained in a given
242       * collection. That is, remove every element e such that !c.contains(e).
243       *
244       * @param c The collection of objects to be retained.
245       * @return true if this collection was modified as a result of this call.
246       * @throws UnsupportedOperationException if this collection does not
247       *   support the retainAll operation.
248       * @throws ClassCastException if the type of any element in c is not a valid
249       *   type for this collection.
250       * @throws NullPointerException if some element of c is null and this
251       *   collection does not support retaining null values.
252       * @throws NullPointerException if c itself is null.
253       */
254      boolean retainAll(Collection<?> c);
255    
256      /**
257       * Get the number of elements in this collection.
258       *
259       * @return the number of elements in the collection.
260       */
261      int size();
262    
263      /**
264       * Copy the current contents of this collection into an array.
265       *
266       * @return an array of type Object[] and length equal to the size of this
267       *   collection, containing the elements currently in this collection, in
268       *   any order.
269       */
270      Object[] toArray();
271    
272      /**
273       * Copy the current contents of this collection into an array. If the array
274       * passed as an argument has length less than the size of this collection, an
275       * array of the same run-time type as a, and length equal to the size of this
276       * collection, is allocated using Reflection. Otherwise, a itself is used.
277       * The elements of this collection are copied into it, and if there is space
278       * in the array, the following element is set to null. The resultant array is
279       * returned.
280       * Note: The fact that the following element is set to null is only useful
281       * if it is known that this collection does not contain any null elements.
282       *
283       * @param a the array to copy this collection into.
284       * @return an array containing the elements currently in this collection, in
285       *   any order.
286       * @throws ArrayStoreException if the type of any element of the
287       *   collection is not a subtype of the element type of a.
288       */
289      <T> T[] toArray(T[] a);
290    }