1 /* 2 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Sun designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Sun in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 22 * CA 95054 USA or visit www.sun.com if you need additional information or 23 * have any questions. 24 */ 25 26 package java.util; 27 28 /** 29 * The root interface in the <i>collection hierarchy</i>. A collection 30 * represents a group of objects, known as its <i>elements</i>. Some 31 * collections allow duplicate elements and others do not. Some are ordered 32 * and others unordered. The JDK does not provide any <i>direct</i> 33 * implementations of this interface: it provides implementations of more 34 * specific subinterfaces like <tt>Set</tt> and <tt>List</tt>. This interface 35 * is typically used to pass collections around and manipulate them where 36 * maximum generality is desired. 37 * 38 * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain 39 * duplicate elements) should implement this interface directly. 40 * 41 * <p>All general-purpose <tt>Collection</tt> implementation classes (which 42 * typically implement <tt>Collection</tt> indirectly through one of its 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. 84 * 85 * <p>Many methods in Collections Framework interfaces are defined in 86 * terms of the {@link Object#equals(Object) equals} method. For example, 87 * the specification for the {@link #contains(Object) contains(Object o)} 88 * method says: "returns <tt>true</tt> if and only if this collection 89 * contains at least one element <tt>e</tt> such that 90 * <tt>(o==null ? e==null : o.equals(e))</tt>." This specification should 91 * <i>not</i> be construed to imply that invoking <tt>Collection.contains</tt> 92 * with a non-null argument <tt>o</tt> will cause <tt>o.equals(e)</tt> to be 93 * invoked for any element <tt>e</tt>. Implementations are free to implement 94 * optimizations whereby the <tt>equals</tt> invocation is avoided, for 95 * example, by first comparing the hash codes of the two elements. (The 96 * {@link Object#hashCode()} specification guarantees that two objects with 97 * unequal hash codes cannot be equal.) More generally, implementations of 98 * the various Collections Framework interfaces are free to take advantage of 99 * the specified behavior of underlying {@link Object} methods wherever the 100 * implementor deems it appropriate. 101 * 102 * <p>This interface is a member of the 103 * <a href="{@docRoot}/../technotes/guides/collections/index.html"> 104 * Java Collections Framework</a>. 105 * 106 * @author Josh Bloch 107 * @author Neal Gafter 108 * @see Set 109 * @see List 110 * @see Map 111 * @see SortedSet 112 * @see SortedMap 113 * @see HashSet 114 * @see TreeSet 115 * @see ArrayList 116 * @see LinkedList 117 * @see Vector 118 * @see Collections 119 * @see Arrays 120 * @see AbstractCollection 121 * @since 1.2 122 */ 123 124 public interface Collection<E> extends Iterable<E> { 125 // Query Operations 126 127 /** 128 * Returns the number of elements in this collection. If this collection 129 * contains more than <tt>Integer.MAX_VALUE</tt> elements, returns 130 * <tt>Integer.MAX_VALUE</tt>. 131 * 132 * @return the number of elements in this collection 133 */ 134 int size(); 135 136 /** 137 * Returns <tt>true</tt> if this collection contains no elements. 138 * 139 * @return <tt>true</tt> if this collection contains no elements 140 */ 141 boolean isEmpty(); 142 143 /** 144 * Returns <tt>true</tt> if this collection contains the specified element. 145 * More formally, returns <tt>true</tt> if and only if this collection 146 * contains at least one element <tt>e</tt> such that 147 * <tt>(o==null ? e==null : o.equals(e))</tt>. 148 * 149 * @param o element whose presence in this collection is to be tested 150 * @return <tt>true</tt> if this collection contains the specified 151 * element 152 * @throws ClassCastException if the type of the specified element 153 * is incompatible with this collection (optional) 154 * @throws NullPointerException if the specified element is null and this 155 * collection does not permit null elements (optional) 156 */ 157 boolean contains(Object o); 158 159 /** 160 * Returns an iterator over the elements in this collection. There are no 161 * guarantees concerning the order in which the elements are returned 162 * (unless this collection is an instance of some class that provides a 163 * guarantee). 164 * 165 * @return an <tt>Iterator</tt> over the elements in this collection 166 */ 167 Iterator<E> iterator(); 168 169 /** 170 * Returns an array containing all of the elements in this collection. 171 * If this collection makes any guarantees as to what order its elements 172 * are returned by its iterator, this method must return the elements in 173 * the same order. 174 * 175 * <p>The returned array will be "safe" in that no references to it are 176 * maintained by this collection. (In other words, this method must 177 * allocate a new array even if this collection is backed by an array). 178 * The caller is thus free to modify the returned array. 179 * 180 * <p>This method acts as bridge between array-based and collection-based 181 * APIs. 182 * 183 * @return an array containing all of the elements in this collection 184 */ 185 Object[] toArray(); 186 187 /** 188 * Returns an array containing all of the elements in this collection; 189 * the runtime type of the returned array is that of the specified array. 190 * If the collection fits in the specified array, it is returned therein. 191 * Otherwise, a new array is allocated with the runtime type of the 192 * specified array and the size of this collection. 193 * 194 * <p>If this collection fits in the specified array with room to spare 195 * (i.e., the array has more elements than this collection), the element 196 * in the array immediately following the end of the collection is set to 197 * <tt>null</tt>. (This is useful in determining the length of this 198 * collection <i>only</i> if the caller knows that this collection does 199 * not contain any <tt>null</tt> elements.) 200 * 201 * <p>If this collection makes any guarantees as to what order its elements 202 * are returned by its iterator, this method must return the elements in 203 * the same order. 204 * 205 * <p>Like the {@link #toArray()} method, this method acts as bridge between 206 * array-based and collection-based APIs. Further, this method allows 207 * precise control over the runtime type of the output array, and may, 208 * under certain circumstances, be used to save allocation costs. 209 * 210 * <p>Suppose <tt>x</tt> is a collection known to contain only strings. 211 * The following code can be used to dump the collection into a newly 212 * allocated array of <tt>String</tt>: 213 * 214 * <pre> 215 * String[] y = x.toArray(new String[0]);</pre> 216 * 217 * Note that <tt>toArray(new Object[0])</tt> is identical in function to 218 * <tt>toArray()</tt>. 219 * 220 * @param a the array into which the elements of this collection are to be 221 * stored, if it is big enough; otherwise, a new array of the same 222 * runtime type is allocated for this purpose. 223 * @return an array containing all of the elements in this collection 224 * @throws ArrayStoreException if the runtime type of the specified array 225 * is not a supertype of the runtime type of every element in 226 * this collection 227 * @throws NullPointerException if the specified array is null 228 */ 229 <T> T[] toArray(T[] a); 230 231 // Modification Operations 232 233 /** 234 * Ensures that this collection contains the specified element (optional 235 * operation). Returns <tt>true</tt> if this collection changed as a 236 * result of the call. (Returns <tt>false</tt> if this collection does 237 * not permit duplicates and already contains the specified element.)<p> 238 * 239 * Collections that support this operation may place limitations on what 240 * elements may be added to this collection. In particular, some 241 * collections will refuse to add <tt>null</tt> elements, and others will 242 * impose restrictions on the type of elements that may be added. 243 * Collection classes should clearly specify in their documentation any 244 * restrictions on what elements may be added.<p> 245 * 246 * If a collection refuses to add a particular element for any reason 247 * other than that it already contains the element, it <i>must</i> throw 248 * an exception (rather than returning <tt>false</tt>). This preserves 249 * the invariant that a collection always contains the specified element 250 * after this call returns. 251 * 252 * @param e element whose presence in this collection is to be ensured 253 * @return <tt>true</tt> if this collection changed as a result of the 254 * call 255 * @throws UnsupportedOperationException if the <tt>add</tt> operation 256 * is not supported by this collection 257 * @throws ClassCastException if the class of the specified element 258 * prevents it from being added to this collection 259 * @throws NullPointerException if the specified element is null and this 260 * collection does not permit null elements 261 * @throws IllegalArgumentException if some property of the element 262 * prevents it from being added to this collection 263 * @throws IllegalStateException if the element cannot be added at this 264 * time due to insertion restrictions 265 */ 266 boolean add(E e); 267 268 /** 269 * Removes a single instance of the specified element from this 270 * collection, if it is present (optional operation). More formally, 271 * removes an element <tt>e</tt> such that 272 * <tt>(o==null ? e==null : o.equals(e))</tt>, if 273 * this collection contains one or more such elements. Returns 274 * <tt>true</tt> if this collection contained the specified element (or 275 * equivalently, if this collection changed as a result of the call). 276 * 277 * @param o element to be removed from this collection, if present 278 * @return <tt>true</tt> if an element was removed as a result of this call 279 * @throws ClassCastException if the type of the specified element 280 * is incompatible with this collection (optional) 281 * @throws NullPointerException if the specified element is null and this 282 * collection does not permit null elements (optional) 283 * @throws UnsupportedOperationException if the <tt>remove</tt> operation 284 * is not supported by this collection 285 */ 286 boolean remove(Object o); 287 288 289 // Bulk Operations 290 291 /** 292 * Returns <tt>true</tt> if this collection contains all of the elements 293 * in the specified collection. 294 * 295 * @param c collection to be checked for containment in this collection 296 * @return <tt>true</tt> if this collection contains all of the elements 297 * in the specified collection 298 * @throws ClassCastException if the types of one or more elements 299 * in the specified collection are incompatible with this 300 * collection (optional) 301 * @throws NullPointerException if the specified collection contains one 302 * or more null elements and this collection does not permit null 303 * elements (optional), or if the specified collection is null 304 * @see #contains(Object) 305 */ 306 boolean containsAll(Collection<?> c); 307 308 /** 309 * Adds all of the elements in the specified collection to this collection 310 * (optional operation). The behavior of this operation is undefined if 311 * the specified collection is modified while the operation is in progress. 312 * (This implies that the behavior of this call is undefined if the 313 * specified collection is this collection, and this collection is 314 * nonempty.) 315 * 316 * @param c collection containing elements to be added to this collection 317 * @return <tt>true</tt> if this collection changed as a result of the call 318 * @throws UnsupportedOperationException if the <tt>addAll</tt> operation 319 * is not supported by this collection 320 * @throws ClassCastException if the class of an element of the specified 321 * collection prevents it from being added to this collection 322 * @throws NullPointerException if the specified collection contains a 323 * null element and this collection does not permit null elements, 324 * or if the specified collection is null 325 * @throws IllegalArgumentException if some property of an element of the 326 * specified collection prevents it from being added to this 327 * collection 328 * @throws IllegalStateException if not all the elements can be added at 329 * this time due to insertion restrictions 330 * @see #add(Object) 331 */ 332 boolean addAll(Collection<? extends E> c); 333 334 /** 335 * Removes all of this collection's elements that are also contained in the 336 * specified collection (optional operation). After this call returns, 337 * this collection will contain no elements in common with the specified 338 * collection. 339 * 340 * @param c collection containing elements to be removed from this collection 341 * @return <tt>true</tt> if this collection changed as a result of the 342 * call 343 * @throws UnsupportedOperationException if the <tt>removeAll</tt> method 344 * is not supported by this collection 345 * @throws ClassCastException if the types of one or more elements 346 * in this collection are incompatible with the specified 347 * collection (optional) 348 * @throws NullPointerException if this collection contains one or more 349 * null elements and the specified collection does not support 350 * null elements (optional), or if the specified collection is null 351 * @see #remove(Object) 352 * @see #contains(Object) 353 */ 354 boolean removeAll(Collection<?> c); 355 356 /** 357 * Retains only the elements in this collection that are contained in the 358 * specified collection (optional operation). In other words, removes from 359 * this collection all of its elements that are not contained in the 360 * specified collection. 361 * 362 * @param c collection containing elements to be retained in this collection 363 * @return <tt>true</tt> if this collection changed as a result of the call 364 * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation 365 * is not supported by this collection 366 * @throws ClassCastException if the types of one or more elements 367 * in this collection are incompatible with the specified 368 * collection (optional) 369 * @throws NullPointerException if this collection contains one or more 370 * null elements and the specified collection does not permit null 371 * elements (optional), or if the specified collection is null 372 * @see #remove(Object) 373 * @see #contains(Object) 374 */ 375 boolean retainAll(Collection<?> c); 376 377 /** 378 * Removes all of the elements from this collection (optional operation). 379 * The collection will be empty after this method returns. 380 * 381 * @throws UnsupportedOperationException if the <tt>clear</tt> operation 382 * is not supported by this collection 383 */ 384 void clear(); 385 386 387 // Comparison and hashing 388 389 /** 390 * Compares the specified object with this collection for equality. <p> 391 * 392 * While the <tt>Collection</tt> interface adds no stipulations to the 393 * general contract for the <tt>Object.equals</tt>, programmers who 394 * implement the <tt>Collection</tt> interface "directly" (in other words, 395 * create a class that is a <tt>Collection</tt> but is not a <tt>Set</tt> 396 * or a <tt>List</tt>) must exercise care if they choose to override the 397 * <tt>Object.equals</tt>. It is not necessary to do so, and the simplest 398 * course of action is to rely on <tt>Object</tt>'s implementation, but 399 * the implementor may wish to implement a "value comparison" in place of 400 * the default "reference comparison." (The <tt>List</tt> and 401 * <tt>Set</tt> interfaces mandate such value comparisons.)<p> 402 * 403 * The general contract for the <tt>Object.equals</tt> method states that 404 * equals must be symmetric (in other words, <tt>a.equals(b)</tt> if and 405 * only if <tt>b.equals(a)</tt>). The contracts for <tt>List.equals</tt> 406 * and <tt>Set.equals</tt> state that lists are only equal to other lists, 407 * and sets to other sets. Thus, a custom <tt>equals</tt> method for a 408 * collection class that implements neither the <tt>List</tt> nor 409 * <tt>Set</tt> interface must return <tt>false</tt> when this collection 410 * is compared to any list or set. (By the same logic, it is not possible 411 * to write a class that correctly implements both the <tt>Set</tt> and 412 * <tt>List</tt> interfaces.) 413 * 414 * @param o object to be compared for equality with this collection 415 * @return <tt>true</tt> if the specified object is equal to this 416 * collection 417 * 418 * @see Object#equals(Object) 419 * @see Set#equals(Object) 420 * @see List#equals(Object) 421 */ 422 boolean equals(Object o); 423 424 /** 425 * Returns the hash code value for this collection. While the 426 * <tt>Collection</tt> interface adds no stipulations to the general 427 * contract for the <tt>Object.hashCode</tt> method, programmers should 428 * take note that any class that overrides the <tt>Object.equals</tt> 429 * method must also override the <tt>Object.hashCode</tt> method in order 430 * to satisfy the general contract for the <tt>Object.hashCode</tt> method. 431 * In particular, <tt>c1.equals(c2)</tt> implies that 432 * <tt>c1.hashCode()==c2.hashCode()</tt>. 433 * 434 * @return the hash code value for this collection 435 * 436 * @see Object#hashCode() 437 * @see Object#equals(Object) 438 */ 439 int hashCode(); 440 }