1 /* 2 * Copyright (c) 1997, 2010, Oracle and/or its affiliates. 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. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * 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 * @param <E> the type of elements in this collection 107 * 108 * @author Josh Bloch 109 * @author Neal Gafter 110 * @see Set 111 * @see List 112 * @see Map 113 * @see SortedSet 114 * @see SortedMap 115 * @see HashSet 116 * @see TreeSet 117 * @see ArrayList 118 * @see LinkedList 119 * @see Vector 120 * @see Collections 121 * @see Arrays 122 * @see AbstractCollection 123 * @since 1.2 124 */ 125 126 public interface Collection<E> extends Iterable<E> { 127 // Query Operations 128 129 /** 130 * Returns the number of elements in this collection. If this collection 131 * contains more than <tt>Integer.MAX_VALUE</tt> elements, returns 132 * <tt>Integer.MAX_VALUE</tt>. 133 * 134 * @return the number of elements in this collection 135 */ 136 int size(); 137 138 /** 139 * Returns <tt>true</tt> if this collection contains no elements. 140 * 141 * @return <tt>true</tt> if this collection contains no elements 142 */ 143 boolean isEmpty(); 144 145 /** 146 * Returns <tt>true</tt> if this collection contains the specified element. 147 * More formally, returns <tt>true</tt> if and only if this collection 148 * contains at least one element <tt>e</tt> such that 149 * <tt>(o==null ? e==null : o.equals(e))</tt>. 150 * 151 * @param o element whose presence in this collection is to be tested 152 * @return <tt>true</tt> if this collection contains the specified 153 * element 154 * @throws ClassCastException if the type of the specified element 155 * is incompatible with this collection (optional) 156 * @throws NullPointerException if the specified element is null and this 157 * collection does not permit null elements (optional) 158 */ 159 boolean contains(Object o); 160 161 /** 162 * Returns an iterator over the elements in this collection. There are no 163 * guarantees concerning the order in which the elements are returned 164 * (unless this collection is an instance of some class that provides a 165 * guarantee). 166 * 167 * @return an <tt>Iterator</tt> over the elements in this collection 168 */ 169 Iterator<E> iterator(); 170 171 /** 172 * Returns an array containing all of the elements in this collection. 173 * If this collection makes any guarantees as to what order its elements 174 * are returned by its iterator, this method must return the elements in 175 * the same order. 176 * 177 * <p>The returned array will be "safe" in that no references to it are 178 * maintained by this collection. (In other words, this method must 179 * allocate a new array even if this collection is backed by an array). 180 * The caller is thus free to modify the returned array. 181 * 182 * <p>This method acts as bridge between array-based and collection-based 183 * APIs. 184 * 185 * @return an array containing all of the elements in this collection 186 */ 187 Object[] toArray(); 188 189 /** 190 * Returns an array containing all of the elements in this collection; 191 * the runtime type of the returned array is that of the specified array. 192 * If the collection fits in the specified array, it is returned therein. 193 * Otherwise, a new array is allocated with the runtime type of the 194 * specified array and the size of this collection. 195 * 196 * <p>If this collection fits in the specified array with room to spare 197 * (i.e., the array has more elements than this collection), the element 198 * in the array immediately following the end of the collection is set to 199 * <tt>null</tt>. (This is useful in determining the length of this 200 * collection <i>only</i> if the caller knows that this collection does 201 * not contain any <tt>null</tt> elements.) 202 * 203 * <p>If this collection makes any guarantees as to what order its elements 204 * are returned by its iterator, this method must return the elements in 205 * the same order. 206 * 207 * <p>Like the {@link #toArray()} method, this method acts as bridge between 208 * array-based and collection-based APIs. Further, this method allows 209 * precise control over the runtime type of the output array, and may, 210 * under certain circumstances, be used to save allocation costs. 211 * 212 * <p>Suppose <tt>x</tt> is a collection known to contain only strings. 213 * The following code can be used to dump the collection into a newly 214 * allocated array of <tt>String</tt>: 215 * 216 * <pre> 217 * String[] y = x.toArray(new String[0]);</pre> 218 * 219 * Note that <tt>toArray(new Object[0])</tt> is identical in function to 220 * <tt>toArray()</tt>. 221 * 222 * @param a the array into which the elements of this collection are to be 223 * stored, if it is big enough; otherwise, a new array of the same 224 * runtime type is allocated for this purpose. 225 * @return an array containing all of the elements in this collection 226 * @throws ArrayStoreException if the runtime type of the specified array 227 * is not a supertype of the runtime type of every element in 228 * this collection 229 * @throws NullPointerException if the specified array is null 230 */ 231 <T> T[] toArray(T[] a); 232 233 // Modification Operations 234 235 /** 236 * Ensures that this collection contains the specified element (optional 237 * operation). Returns <tt>true</tt> if this collection changed as a 238 * result of the call. (Returns <tt>false</tt> if this collection does 239 * not permit duplicates and already contains the specified element.)<p> 240 * 241 * Collections that support this operation may place limitations on what 242 * elements may be added to this collection. In particular, some 243 * collections will refuse to add <tt>null</tt> elements, and others will 244 * impose restrictions on the type of elements that may be added. 245 * Collection classes should clearly specify in their documentation any 246 * restrictions on what elements may be added.<p> 247 * 248 * If a collection refuses to add a particular element for any reason 249 * other than that it already contains the element, it <i>must</i> throw 250 * an exception (rather than returning <tt>false</tt>). This preserves 251 * the invariant that a collection always contains the specified element 252 * after this call returns. 253 * 254 * @param e element whose presence in this collection is to be ensured 255 * @return <tt>true</tt> if this collection changed as a result of the 256 * call 257 * @throws UnsupportedOperationException if the <tt>add</tt> operation 258 * is not supported by this collection 259 * @throws ClassCastException if the class of the specified element 260 * prevents it from being added to this collection 261 * @throws NullPointerException if the specified element is null and this 262 * collection does not permit null elements 263 * @throws IllegalArgumentException if some property of the element 264 * prevents it from being added to this collection 265 * @throws IllegalStateException if the element cannot be added at this 266 * time due to insertion restrictions 267 */ 268 boolean add(E e); 269 270 /** 271 * Removes a single instance of the specified element from this 272 * collection, if it is present (optional operation). More formally, 273 * removes an element <tt>e</tt> such that 274 * <tt>(o==null ? e==null : o.equals(e))</tt>, if 275 * this collection contains one or more such elements. Returns 276 * <tt>true</tt> if this collection contained the specified element (or 277 * equivalently, if this collection changed as a result of the call). 278 * 279 * @param o element to be removed from this collection, if present 280 * @return <tt>true</tt> if an element was removed as a result of this call 281 * @throws ClassCastException if the type of the specified element 282 * is incompatible with this collection (optional) 283 * @throws NullPointerException if the specified element is null and this 284 * collection does not permit null elements (optional) 285 * @throws UnsupportedOperationException if the <tt>remove</tt> operation 286 * is not supported by this collection 287 */ 288 boolean remove(Object o); 289 290 291 // Bulk Operations 292 293 /** 294 * Returns <tt>true</tt> if this collection contains all of the elements 295 * in the specified collection. 296 * 297 * @param c collection to be checked for containment in this collection 298 * @return <tt>true</tt> if this collection contains all of the elements 299 * in the specified collection 300 * @throws ClassCastException if the types of one or more elements 301 * in the specified collection are incompatible with this 302 * collection (optional) 303 * @throws NullPointerException if the specified collection contains one 304 * or more null elements and this collection does not permit null 305 * elements (optional), or if the specified collection is null 306 * @see #contains(Object) 307 */ 308 boolean containsAll(Collection<?> c); 309 310 /** 311 * Adds all of the elements in the specified collection to this collection 312 * (optional operation). The behavior of this operation is undefined if 313 * the specified collection is modified while the operation is in progress. 314 * (This implies that the behavior of this call is undefined if the 315 * specified collection is this collection, and this collection is 316 * nonempty.) 317 * 318 * @param c collection containing elements to be added to this collection 319 * @return <tt>true</tt> if this collection changed as a result of the call 320 * @throws UnsupportedOperationException if the <tt>addAll</tt> operation 321 * is not supported by this collection 322 * @throws ClassCastException if the class of an element of the specified 323 * collection prevents it from being added to this collection 324 * @throws NullPointerException if the specified collection contains a 325 * null element and this collection does not permit null elements, 326 * or if the specified collection is null 327 * @throws IllegalArgumentException if some property of an element of the 328 * specified collection prevents it from being added to this 329 * collection 330 * @throws IllegalStateException if not all the elements can be added at 331 * this time due to insertion restrictions 332 * @see #add(Object) 333 */ 334 boolean addAll(Collection<? extends E> c); 335 336 /** 337 * Removes all of this collection's elements that are also contained in the 338 * specified collection (optional operation). After this call returns, 339 * this collection will contain no elements in common with the specified 340 * collection. 341 * 342 * @param c collection containing elements to be removed from this collection 343 * @return <tt>true</tt> if this collection changed as a result of the 344 * call 345 * @throws UnsupportedOperationException if the <tt>removeAll</tt> method 346 * is not supported by this collection 347 * @throws ClassCastException if the types of one or more elements 348 * in this collection are incompatible with the specified 349 * collection (optional) 350 * @throws NullPointerException if this collection contains one or more 351 * null elements and the specified collection does not support 352 * null elements (optional), or if the specified collection is null 353 * @see #remove(Object) 354 * @see #contains(Object) 355 */ 356 boolean removeAll(Collection<?> c); 357 358 /** 359 * Retains only the elements in this collection that are contained in the 360 * specified collection (optional operation). In other words, removes from 361 * this collection all of its elements that are not contained in the 362 * specified collection. 363 * 364 * @param c collection containing elements to be retained in this collection 365 * @return <tt>true</tt> if this collection changed as a result of the call 366 * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation 367 * is not supported by this collection 368 * @throws ClassCastException if the types of one or more elements 369 * in this collection are incompatible with the specified 370 * collection (optional) 371 * @throws NullPointerException if this collection contains one or more 372 * null elements and the specified collection does not permit null 373 * elements (optional), or if the specified collection is null 374 * @see #remove(Object) 375 * @see #contains(Object) 376 */ 377 boolean retainAll(Collection<?> c); 378 379 /** 380 * Removes all of the elements from this collection (optional operation). 381 * The collection will be empty after this method returns. 382 * 383 * @throws UnsupportedOperationException if the <tt>clear</tt> operation 384 * is not supported by this collection 385 */ 386 void clear(); 387 388 389 // Comparison and hashing 390 391 /** 392 * Compares the specified object with this collection for equality. <p> 393 * 394 * While the <tt>Collection</tt> interface adds no stipulations to the 395 * general contract for the <tt>Object.equals</tt>, programmers who 396 * implement the <tt>Collection</tt> interface "directly" (in other words, 397 * create a class that is a <tt>Collection</tt> but is not a <tt>Set</tt> 398 * or a <tt>List</tt>) must exercise care if they choose to override the 399 * <tt>Object.equals</tt>. It is not necessary to do so, and the simplest 400 * course of action is to rely on <tt>Object</tt>'s implementation, but 401 * the implementor may wish to implement a "value comparison" in place of 402 * the default "reference comparison." (The <tt>List</tt> and 403 * <tt>Set</tt> interfaces mandate such value comparisons.)<p> 404 * 405 * The general contract for the <tt>Object.equals</tt> method states that 406 * equals must be symmetric (in other words, <tt>a.equals(b)</tt> if and 407 * only if <tt>b.equals(a)</tt>). The contracts for <tt>List.equals</tt> 408 * and <tt>Set.equals</tt> state that lists are only equal to other lists, 409 * and sets to other sets. Thus, a custom <tt>equals</tt> method for a 410 * collection class that implements neither the <tt>List</tt> nor 411 * <tt>Set</tt> interface must return <tt>false</tt> when this collection 412 * is compared to any list or set. (By the same logic, it is not possible 413 * to write a class that correctly implements both the <tt>Set</tt> and 414 * <tt>List</tt> interfaces.) 415 * 416 * @param o object to be compared for equality with this collection 417 * @return <tt>true</tt> if the specified object is equal to this 418 * collection 419 * 420 * @see Object#equals(Object) 421 * @see Set#equals(Object) 422 * @see List#equals(Object) 423 */ 424 boolean equals(Object o); 425 426 /** 427 * Returns the hash code value for this collection. While the 428 * <tt>Collection</tt> interface adds no stipulations to the general 429 * contract for the <tt>Object.hashCode</tt> method, programmers should 430 * take note that any class that overrides the <tt>Object.equals</tt> 431 * method must also override the <tt>Object.hashCode</tt> method in order 432 * to satisfy the general contract for the <tt>Object.hashCode</tt> method. 433 * In particular, <tt>c1.equals(c2)</tt> implies that 434 * <tt>c1.hashCode()==c2.hashCode()</tt>. 435 * 436 * @return the hash code value for this collection 437 * 438 * @see Object#hashCode() 439 * @see Object#equals(Object) 440 */ 441 int hashCode(); 442 }