001: /*
002: * @(#)Collection.java 1.38 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program 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 version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.util;
029:
030: /**
031: * The root interface in the <i>collection hierarchy</i>. A collection
032: * represents a group of objects, known as its <i>elements</i>. Some
033: * collections allow duplicate elements and others do not. Some are ordered
034: * and others unordered. The SDK does not provide any <i>direct</i>
035: * implementations of this interface: it provides implementations of more
036: * specific subinterfaces like <tt>Set</tt> and <tt>List</tt>. This interface
037: * is typically used to pass collections around and manipulate them where
038: * maximum generality is desired.
039: *
040: * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
041: * duplicate elements) should implement this interface directly.
042: *
043: * <p>All general-purpose <tt>Collection</tt> implementation classes (which
044: * typically implement <tt>Collection</tt> indirectly through one of its
045: * subinterfaces) should provide two "standard" constructors: a void (no
046: * arguments) constructor, which creates an empty collection, and a
047: * constructor with a single argument of type <tt>Collection</tt>, which
048: * creates a new collection with the same elements as its argument. In
049: * effect, the latter constructor allows the user to copy any collection,
050: * producing an equivalent collection of the desired implementation type.
051: * There is no way to enforce this convention (as interfaces cannot contain
052: * constructors) but all of the general-purpose <tt>Collection</tt>
053: * implementations in the Java platform libraries comply.
054: *
055: * <p>The "destructive" methods contained in this interface, that is, the
056: * methods that modify the collection on which they operate, are specified to
057: * throw <tt>UnsupportedOperationException</tt> if this collection does not
058: * support the operation. If this is the case, these methods may, but are not
059: * required to, throw an <tt>UnsupportedOperationException</tt> if the
060: * invocation would have no effect on the collection. For example, invoking
061: * the {@link #addAll(Collection)} method on an unmodifiable collection may,
062: * but is not required to, throw the exception if the collection to be added
063: * is empty.
064: *
065: * <p>Some collection implementations have restrictions on the elements that
066: * they may contain. For example, some implementations prohibit null elements,
067: * and some have restrictions on the types of their elements. Attempting to
068: * add an ineligible element throws an unchecked exception, typically
069: * <tt>NullPointerException</tt> or <tt>ClassCastException</tt>. Attempting
070: * to query the presence of an ineligible element may throw an exception,
071: * or it may simply return false; some implementations will exhibit the former
072: * behavior and some will exhibit the latter. More generally, attempting an
073: * operation on an ineligible element whose completion would not result in
074: * the insertion of an ineligible element into the collection may throw an
075: * exception or it may succeed, at the option of the implementation.
076: * Such exceptions are marked as "optional" in the specification for this
077: * interface.
078: *
079: * <p>This interface is a member of the
080: * <a href="{@docRoot}/../guide/collections/index.html">
081: * Java Collections Framework</a>.
082: *
083: * @author Josh Bloch
084: * @version 1.31, 02/02/00
085: * @see Set
086: * @see List
087: * @see Map
088: * @see SortedSet
089: * @see SortedMap
090: * @see HashSet
091: * @see TreeSet
092: * @see ArrayList
093: * @see LinkedList
094: * @see Vector
095: * @see Collections
096: * @see Arrays
097: * @see AbstractCollection
098: * @since 1.2
099: */
100:
101: public interface Collection {
102: // Query Operations
103:
104: /**
105: * Returns the number of elements in this collection. If this collection
106: * contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
107: * <tt>Integer.MAX_VALUE</tt>.
108: *
109: * @return the number of elements in this collection
110: */
111: int size();
112:
113: /**
114: * Returns <tt>true</tt> if this collection contains no elements.
115: *
116: * @return <tt>true</tt> if this collection contains no elements
117: */
118: boolean isEmpty();
119:
120: /**
121: * Returns <tt>true</tt> if this collection contains the specified
122: * element. More formally, returns <tt>true</tt> if and only if this
123: * collection contains at least one element <tt>e</tt> such that
124: * <tt>(o==null ? e==null : o.equals(e))</tt>.
125: *
126: * @param o element whose presence in this collection is to be tested.
127: * @return <tt>true</tt> if this collection contains the specified
128: * element
129: * @throws ClassCastException if the type of the specified element
130: * is incompatible with this collection (optional).
131: * @throws NullPointerException if the specified element is null and this
132: * collection does not support null elements (optional).
133: */
134: boolean contains(Object o);
135:
136: /**
137: * Returns an iterator over the elements in this collection. There are no
138: * guarantees concerning the order in which the elements are returned
139: * (unless this collection is an instance of some class that provides a
140: * guarantee).
141: *
142: * @return an <tt>Iterator</tt> over the elements in this collection
143: */
144: Iterator iterator();
145:
146: /**
147: * Returns an array containing all of the elements in this collection. If
148: * the collection makes any guarantees as to what order its elements are
149: * returned by its iterator, this method must return the elements in the
150: * same order.<p>
151: *
152: * The returned array will be "safe" in that no references to it are
153: * maintained by this collection. (In other words, this method must
154: * allocate a new array even if this collection is backed by an array).
155: * The caller is thus free to modify the returned array.<p>
156: *
157: * This method acts as bridge between array-based and collection-based
158: * APIs.
159: *
160: * @return an array containing all of the elements in this collection
161: */
162: Object[] toArray();
163:
164: /**
165: * Returns an array containing all of the elements in this collection;
166: * the runtime type of the returned array is that of the specified array.
167: * If the collection fits in the specified array, it is returned therein.
168: * Otherwise, a new array is allocated with the runtime type of the
169: * specified array and the size of this collection.<p>
170: *
171: * If this collection fits in the specified array with room to spare
172: * (i.e., the array has more elements than this collection), the element
173: * in the array immediately following the end of the collection is set to
174: * <tt>null</tt>. This is useful in determining the length of this
175: * collection <i>only</i> if the caller knows that this collection does
176: * not contain any <tt>null</tt> elements.)<p>
177: *
178: * If this collection makes any guarantees as to what order its elements
179: * are returned by its iterator, this method must return the elements in
180: * the same order.<p>
181: *
182: * Like the <tt>toArray</tt> method, this method acts as bridge between
183: * array-based and collection-based APIs. Further, this method allows
184: * precise control over the runtime type of the output array, and may,
185: * under certain circumstances, be used to save allocation costs<p>
186: *
187: * Suppose <tt>l</tt> is a <tt>List</tt> known to contain only strings.
188: * The following code can be used to dump the list into a newly allocated
189: * array of <tt>String</tt>:
190: *
191: * <pre>
192: * String[] x = (String[]) v.toArray(new String[0]);
193: * </pre><p>
194: *
195: * Note that <tt>toArray(new Object[0])</tt> is identical in function to
196: * <tt>toArray()</tt>.
197: *
198: * @param a the array into which the elements of this collection are to be
199: * stored, if it is big enough; otherwise, a new array of the same
200: * runtime type is allocated for this purpose.
201: * @return an array containing the elements of this collection
202: *
203: * @throws ArrayStoreException the runtime type of the specified array is
204: * not a supertype of the runtime type of every element in this
205: * collection.
206: * @throws NullPointerException if the specified array is <tt>null</tt>.
207: */
208:
209: Object[] toArray(Object a[]);
210:
211: // Modification Operations
212:
213: /**
214: * Ensures that this collection contains the specified element (optional
215: * operation). Returns <tt>true</tt> if this collection changed as a
216: * result of the call. (Returns <tt>false</tt> if this collection does
217: * not permit duplicates and already contains the specified element.)<p>
218: *
219: * Collections that support this operation may place limitations on what
220: * elements may be added to this collection. In particular, some
221: * collections will refuse to add <tt>null</tt> elements, and others will
222: * impose restrictions on the type of elements that may be added.
223: * Collection classes should clearly specify in their documentation any
224: * restrictions on what elements may be added.<p>
225: *
226: * If a collection refuses to add a particular element for any reason
227: * other than that it already contains the element, it <i>must</i> throw
228: * an exception (rather than returning <tt>false</tt>). This preserves
229: * the invariant that a collection always contains the specified element
230: * after this call returns.
231: *
232: * @param o element whose presence in this collection is to be ensured.
233: * @return <tt>true</tt> if this collection changed as a result of the
234: * call
235: *
236: * @throws UnsupportedOperationException <tt>add</tt> is not supported by
237: * this collection.
238: * @throws ClassCastException class of the specified element prevents it
239: * from being added to this collection.
240: * @throws NullPointerException if the specified element is null and this
241: * collection does not support null elements.
242: * @throws IllegalArgumentException some aspect of this element prevents
243: * it from being added to this collection.
244: */
245: boolean add(Object o);
246:
247: /**
248: * Removes a single instance of the specified element from this
249: * collection, if it is present (optional operation). More formally,
250: * removes an element <tt>e</tt> such that <tt>(o==null ? e==null :
251: * o.equals(e))</tt>, if this collection contains one or more such
252: * elements. Returns true if this collection contained the specified
253: * element (or equivalently, if this collection changed as a result of the
254: * call).
255: *
256: * @param o element to be removed from this collection, if present.
257: * @return <tt>true</tt> if this collection changed as a result of the
258: * call
259: *
260: * @throws ClassCastException if the type of the specified element
261: * is incompatible with this collection (optional).
262: * @throws NullPointerException if the specified element is null and this
263: * collection does not support null elements (optional).
264: * @throws UnsupportedOperationException remove is not supported by this
265: * collection.
266: */
267: boolean remove(Object o);
268:
269: // Bulk Operations
270:
271: /**
272: * Returns <tt>true</tt> if this collection contains all of the elements
273: * in the specified collection.
274: *
275: * @param c collection to be checked for containment in this collection.
276: * @return <tt>true</tt> if this collection contains all of the elements
277: * in the specified collection
278: * @throws ClassCastException if the types of one or more elements
279: * in the specified collection are incompatible with this
280: * collection (optional).
281: * @throws NullPointerException if the specified collection contains one
282: * or more null elements and this collection does not support null
283: * elements (optional).
284: * @throws NullPointerException if the specified collection is
285: * <tt>null</tt>.
286: * @see #contains(Object)
287: */
288: boolean containsAll(Collection c);
289:
290: /**
291: * Adds all of the elements in the specified collection to this collection
292: * (optional operation). The behavior of this operation is undefined if
293: * the specified collection is modified while the operation is in progress.
294: * (This implies that the behavior of this call is undefined if the
295: * specified collection is this collection, and this collection is
296: * nonempty.)
297: *
298: * @param c elements to be inserted into this collection.
299: * @return <tt>true</tt> if this collection changed as a result of the
300: * call
301: *
302: * @throws UnsupportedOperationException if this collection does not
303: * support the <tt>addAll</tt> method.
304: * @throws ClassCastException if the class of an element of the specified
305: * collection prevents it from being added to this collection.
306: * @throws NullPointerException if the specified collection contains one
307: * or more null elements and this collection does not support null
308: * elements, or if the specified collection is <tt>null</tt>.
309: * @throws IllegalArgumentException some aspect of an element of the
310: * specified collection prevents it from being added to this
311: * collection.
312: * @see #add(Object)
313: */
314: boolean addAll(Collection c);
315:
316: /**
317: *
318: * Removes all this collection's elements that are also contained in the
319: * specified collection (optional operation). After this call returns,
320: * this collection will contain no elements in common with the specified
321: * collection.
322: *
323: * @param c elements to be removed from this collection.
324: * @return <tt>true</tt> if this collection changed as a result of the
325: * call
326: *
327: * @throws UnsupportedOperationException if the <tt>removeAll</tt> method
328: * is not supported by this collection.
329: * @throws ClassCastException if the types of one or more elements
330: * in this collection are incompatible with the specified
331: * collection (optional).
332: * @throws NullPointerException if this collection contains one or more
333: * null elements and the specified collection does not support
334: * null elements (optional).
335: * @throws NullPointerException if the specified collection is
336: * <tt>null</tt>.
337: * @see #remove(Object)
338: * @see #contains(Object)
339: */
340: boolean removeAll(Collection c);
341:
342: /**
343: * Retains only the elements in this collection that are contained in the
344: * specified collection (optional operation). In other words, removes from
345: * this collection all of its elements that are not contained in the
346: * specified collection.
347: *
348: * @param c elements to be retained in this collection.
349: * @return <tt>true</tt> if this collection changed as a result of the
350: * call
351: *
352: * @throws UnsupportedOperationException if the <tt>retainAll</tt> method
353: * is not supported by this Collection.
354: * @throws ClassCastException if the types of one or more elements
355: * in this collection are incompatible with the specified
356: * collection (optional).
357: * @throws NullPointerException if this collection contains one or more
358: * null elements and the specified collection does not support null
359: * elements (optional).
360: * @throws NullPointerException if the specified collection is
361: * <tt>null</tt>.
362: * @see #remove(Object)
363: * @see #contains(Object)
364: */
365: boolean retainAll(Collection c);
366:
367: /**
368: * Removes all of the elements from this collection (optional operation).
369: * This collection will be empty after this method returns unless it
370: * throws an exception.
371: *
372: * @throws UnsupportedOperationException if the <tt>clear</tt> method is
373: * not supported by this collection.
374: */
375: void clear();
376:
377: // Comparison and hashing
378:
379: /**
380: * Compares the specified object with this collection for equality. <p>
381: *
382: * While the <tt>Collection</tt> interface adds no stipulations to the
383: * general contract for the <tt>Object.equals</tt>, programmers who
384: * implement the <tt>Collection</tt> interface "directly" (in other words,
385: * create a class that is a <tt>Collection</tt> but is not a <tt>Set</tt>
386: * or a <tt>List</tt>) must exercise care if they choose to override the
387: * <tt>Object.equals</tt>. It is not necessary to do so, and the simplest
388: * course of action is to rely on <tt>Object</tt>'s implementation, but
389: * the implementer may wish to implement a "value comparison" in place of
390: * the default "reference comparison." (The <tt>List</tt> and
391: * <tt>Set</tt> interfaces mandate such value comparisons.)<p>
392: *
393: * The general contract for the <tt>Object.equals</tt> method states that
394: * equals must be symmetric (in other words, <tt>a.equals(b)</tt> if and
395: * only if <tt>b.equals(a)</tt>). The contracts for <tt>List.equals</tt>
396: * and <tt>Set.equals</tt> state that lists are only equal to other lists,
397: * and sets to other sets. Thus, a custom <tt>equals</tt> method for a
398: * collection class that implements neither the <tt>List</tt> nor
399: * <tt>Set</tt> interface must return <tt>false</tt> when this collection
400: * is compared to any list or set. (By the same logic, it is not possible
401: * to write a class that correctly implements both the <tt>Set</tt> and
402: * <tt>List</tt> interfaces.)
403: *
404: * @param o Object to be compared for equality with this collection.
405: * @return <tt>true</tt> if the specified object is equal to this
406: * collection
407: *
408: * @see Object#equals(Object)
409: * @see Set#equals(Object)
410: * @see List#equals(Object)
411: */
412: boolean equals(Object o);
413:
414: /**
415: * Returns the hash code value for this collection. While the
416: * <tt>Collection</tt> interface adds no stipulations to the general
417: * contract for the <tt>Object.hashCode</tt> method, programmers should
418: * take note that any class that overrides the <tt>Object.equals</tt>
419: * method must also override the <tt>Object.hashCode</tt> method in order
420: * to satisfy the general contract for the <tt>Object.hashCode</tt>method.
421: * In particular, <tt>c1.equals(c2)</tt> implies that
422: * <tt>c1.hashCode()==c2.hashCode()</tt>.
423: *
424: * @return the hash code value for this collection
425: *
426: * @see Object#hashCode()
427: * @see Object#equals(Object)
428: */
429: int hashCode();
430: }
|