1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package java.util; 19 20 21 /** 22 * {@code Collection} is the root of the collection hierarchy. It defines operations on 23 * data collections and the behavior that they will have in all implementations 24 * of {@code Collection}s. 25 * 26 * All direct or indirect implementations of {@code Collection} should implement at 27 * least two constructors. One with no parameters which creates an empty 28 * collection and one with a parameter of type {@code Collection}. This second 29 * constructor can be used to create a collection of different type as the 30 * initial collection but with the same elements. Implementations of {@code Collection} 31 * cannot be forced to implement these two constructors but at least all 32 * implementations under {@code java.util} do. 33 * 34 * Methods that change the content of a collection throw an 35 * {@code UnsupportedOperationException} if the underlying collection does not 36 * support that operation, though it's not mandatory to throw such an {@code Exception} 37 * in cases where the requested operation would not change the collection. In 38 * these cases it's up to the implementation whether it throws an 39 * {@code UnsupportedOperationException} or not. 40 * 41 * Methods marked with (optional) can throw an 42 * {@code UnsupportedOperationException} if the underlying collection doesn't 43 * support that method. 44 */ 45 public interface Collection<E> extends Iterable<E> { 46 47 /** 48 * Attempts to add {@code object} to the contents of this 49 * {@code Collection} (optional). 50 * 51 * After this method finishes successfully it is guaranteed that the object 52 * is contained in the collection. 53 * 54 * If the collection was modified it returns {@code true}, {@code false} if 55 * no changes were made. 56 * 57 * An implementation of {@code Collection} may narrow the set of accepted 58 * objects, but it has to specify this in the documentation. If the object 59 * to be added does not meet this restriction, then an 60 * {@code IllegalArgumentException} is thrown. 61 * 62 * If a collection does not yet contain an object that is to be added and 63 * adding the object fails, this method <i>must</i> throw an appropriate 64 * unchecked Exception. Returning false is not permitted in this case 65 * because it would violate the postcondition that the element will be part 66 * of the collection after this method finishes. 67 * 68 * @param object 69 * the object to add. 70 * @return {@code true} if this {@code Collection} is 71 * modified, {@code false} otherwise. 72 * 73 * @throws UnsupportedOperationException 74 * if adding to this {@code Collection} is not supported. 75 * @throws ClassCastException 76 * if the class of the object is inappropriate for this 77 * collection. 78 * @throws IllegalArgumentException 79 * if the object cannot be added to this {@code Collection}. 80 * @throws NullPointerException 81 * if null elements cannot be added to the {@code Collection}. 82 */ add(E object)83 public boolean add(E object); 84 85 /** 86 * Attempts to add all of the objects contained in {@code Collection} 87 * to the contents of this {@code Collection} (optional). If the passed {@code Collection} 88 * is changed during the process of adding elements to this {@code Collection}, the 89 * behavior is not defined. 90 * 91 * @param collection 92 * the {@code Collection} of objects. 93 * @return {@code true} if this {@code Collection} is modified, {@code false} 94 * otherwise. 95 * @throws UnsupportedOperationException 96 * if adding to this {@code Collection} is not supported. 97 * @throws ClassCastException 98 * if the class of an object is inappropriate for this 99 * {@code Collection}. 100 * @throws IllegalArgumentException 101 * if an object cannot be added to this {@code Collection}. 102 * @throws NullPointerException 103 * if {@code collection} is {@code null}, or if it 104 * contains {@code null} elements and this {@code Collection} does 105 * not support such elements. 106 */ addAll(Collection<? extends E> collection)107 public boolean addAll(Collection<? extends E> collection); 108 109 /** 110 * Removes all elements from this {@code Collection}, leaving it empty (optional). 111 * 112 * @throws UnsupportedOperationException 113 * if removing from this {@code Collection} is not supported. 114 * 115 * @see #isEmpty 116 * @see #size 117 */ clear()118 public void clear(); 119 120 /** 121 * Tests whether this {@code Collection} contains the specified object. Returns 122 * {@code true} if and only if at least one element {@code elem} in this 123 * {@code Collection} meets following requirement: 124 * {@code (object==null ? elem==null : object.equals(elem))}. 125 * 126 * @param object 127 * the object to search for. 128 * @return {@code true} if object is an element of this {@code Collection}, 129 * {@code false} otherwise. 130 * @throws ClassCastException 131 * if the object to look for isn't of the correct 132 * type. 133 * @throws NullPointerException 134 * if the object to look for is {@code null} and this 135 * {@code Collection} doesn't support {@code null} elements. 136 */ contains(Object object)137 public boolean contains(Object object); 138 139 /** 140 * Tests whether this {@code Collection} contains all objects contained in the 141 * specified {@code Collection}. If an element {@code elem} is contained several 142 * times in the specified {@code Collection}, the method returns {@code true} even 143 * if {@code elem} is contained only once in this {@code Collection}. 144 * 145 * @param collection 146 * the collection of objects. 147 * @return {@code true} if all objects in the specified {@code Collection} are 148 * elements of this {@code Collection}, {@code false} otherwise. 149 * @throws ClassCastException 150 * if one or more elements of {@code collection} isn't of the 151 * correct type. 152 * @throws NullPointerException 153 * if {@code collection} contains at least one {@code null} 154 * element and this {@code Collection} doesn't support {@code null} 155 * elements. 156 * @throws NullPointerException 157 * if {@code collection} is {@code null}. 158 */ containsAll(Collection<?> collection)159 public boolean containsAll(Collection<?> collection); 160 161 /** 162 * Compares the argument to the receiver, and returns true if they represent 163 * the <em>same</em> object using a class specific comparison. 164 * 165 * @param object 166 * the object to compare with this object. 167 * @return {@code true} if the object is the same as this object and 168 * {@code false} if it is different from this object. 169 * @see #hashCode 170 */ equals(Object object)171 public boolean equals(Object object); 172 173 /** 174 * Returns an integer hash code for the receiver. Objects which are equal 175 * return the same value for this method. 176 * 177 * @return the receiver's hash. 178 * 179 * @see #equals 180 */ hashCode()181 public int hashCode(); 182 183 /** 184 * Returns if this {@code Collection} contains no elements. 185 * 186 * @return {@code true} if this {@code Collection} has no elements, {@code false} 187 * otherwise. 188 * 189 * @see #size 190 */ isEmpty()191 public boolean isEmpty(); 192 193 /** 194 * Returns an instance of {@link Iterator} that may be used to access the 195 * objects contained by this {@code Collection}. The order in which the elements are 196 * returned by the iterator is not defined. Only if the instance of the 197 * {@code Collection} has a defined order the elements are returned in that order. 198 * 199 * @return an iterator for accessing the {@code Collection} contents. 200 */ iterator()201 public Iterator<E> iterator(); 202 203 /** 204 * Removes one instance of the specified object from this {@code Collection} if one 205 * is contained (optional). The element {@code elem} that is removed 206 * complies with {@code (object==null ? elem==null : object.equals(elem)}. 207 * 208 * @param object 209 * the object to remove. 210 * @return {@code true} if this {@code Collection} is modified, {@code false} 211 * otherwise. 212 * @throws UnsupportedOperationException 213 * if removing from this {@code Collection} is not supported. 214 * @throws ClassCastException 215 * if the object passed is not of the correct type. 216 * @throws NullPointerException 217 * if {@code object} is {@code null} and this {@code Collection} 218 * doesn't support {@code null} elements. 219 */ remove(Object object)220 public boolean remove(Object object); 221 222 /** 223 * Removes all occurrences in this {@code Collection} of each object in the 224 * specified {@code Collection} (optional). After this method returns none of the 225 * elements in the passed {@code Collection} can be found in this {@code Collection} 226 * anymore. 227 * 228 * @param collection 229 * the collection of objects to remove. 230 * @return {@code true} if this {@code Collection} is modified, {@code false} 231 * otherwise. 232 * 233 * @throws UnsupportedOperationException 234 * if removing from this {@code Collection} is not supported. 235 * @throws ClassCastException 236 * if one or more elements of {@code collection} 237 * isn't of the correct type. 238 * @throws NullPointerException 239 * if {@code collection} contains at least one 240 * {@code null} element and this {@code Collection} doesn't support 241 * {@code null} elements. 242 * @throws NullPointerException 243 * if {@code collection} is {@code null}. 244 */ removeAll(Collection<?> collection)245 public boolean removeAll(Collection<?> collection); 246 247 /** 248 * Removes all objects from this {@code Collection} that are not also found in the 249 * {@code Collection} passed (optional). After this method returns this {@code Collection} 250 * will only contain elements that also can be found in the {@code Collection} 251 * passed to this method. 252 * 253 * @param collection 254 * the collection of objects to retain. 255 * @return {@code true} if this {@code Collection} is modified, {@code false} 256 * otherwise. 257 * @throws UnsupportedOperationException 258 * if removing from this {@code Collection} is not supported. 259 * @throws ClassCastException 260 * if one or more elements of {@code collection} 261 * isn't of the correct type. 262 * @throws NullPointerException 263 * if {@code collection} contains at least one 264 * {@code null} element and this {@code Collection} doesn't support 265 * {@code null} elements. 266 * @throws NullPointerException 267 * if {@code collection} is {@code null}. 268 */ retainAll(Collection<?> collection)269 public boolean retainAll(Collection<?> collection); 270 271 /** 272 * Returns a count of how many objects this {@code Collection} contains. 273 * 274 * @return how many objects this {@code Collection} contains, or Integer.MAX_VALUE 275 * if there are more than Integer.MAX_VALUE elements in this 276 * {@code Collection}. 277 */ size()278 public int size(); 279 280 /** 281 * Returns a new array containing all elements contained in this {@code Collection}. 282 * 283 * If the implementation has ordered elements it will return the element 284 * array in the same order as an iterator would return them. 285 * 286 * The array returned does not reflect any changes of the {@code Collection}. A new 287 * array is created even if the underlying data structure is already an 288 * array. 289 * 290 * @return an array of the elements from this {@code Collection}. 291 */ toArray()292 public Object[] toArray(); 293 294 /** 295 * Returns an array containing all elements contained in this {@code Collection}. If 296 * the specified array is large enough to hold the elements, the specified 297 * array is used, otherwise an array of the same type is created. If the 298 * specified array is used and is larger than this {@code Collection}, the array 299 * element following the {@code Collection} elements is set to null. 300 * 301 * If the implementation has ordered elements it will return the element 302 * array in the same order as an iterator would return them. 303 * 304 * {@code toArray(new Object[0])} behaves exactly the same way as 305 * {@code toArray()} does. 306 * 307 * @param array 308 * the array. 309 * @return an array of the elements from this {@code Collection}. 310 * 311 * @throws ArrayStoreException 312 * if the type of an element in this {@code Collection} cannot be 313 * stored in the type of the specified array. 314 */ toArray(T[] array)315 public <T> T[] toArray(T[] array); 316 } 317