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 18package 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 constuctors. 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 * @since Android 1.0 46 */ 47public interface Collection<E> extends Iterable<E> { 48 49 /** 50 * Attempts to add {@code object} to the contents of this 51 * {@code Collection} (optional). 52 * 53 * After this method finishes successfully it is guaranteed that the object 54 * is contained in the collection. 55 * 56 * If the collection was modified it returns {@code true}, {@code false} if 57 * no changes were made. 58 * 59 * An implementation of {@code Collection} may narrow the set of accepted 60 * objects, but it has to specify this in the documentation. If the object 61 * to be added does not meet this restriction, then an 62 * {@code IllegalArgumentException} is thrown. 63 * 64 * If a collection does not yet contain an object that is to be added and 65 * adding the object fails, this method <i>must</i> throw an appropriate 66 * unchecked Exception. Returning false is not permitted in this case 67 * because it would violate the postcondition that the element will be part 68 * of the collection after this method finishes. 69 * 70 * @param object 71 * the object to add. 72 * @return {@code true} if this {@code Collection} is 73 * modified, {@code false} otherwise. 74 * 75 * @exception UnsupportedOperationException 76 * when adding to this {@code Collection} is not supported. 77 * @exception ClassCastException 78 * when the class of the object is inappropriate for this 79 * collection. 80 * @exception IllegalArgumentException 81 * when the object cannot be added to this {@code Collection}. 82 * @exception NullPointerException 83 * when null elements cannot be added to the {@code Collection}. 84 * @since Android 1.0 85 */ 86 public boolean add(E object); 87 88 /** 89 * Attempts to add all of the objects contained in {@code Collection} 90 * to the contents of this {@code Collection} (optional). If the passed {@code Collection} 91 * is changed during the process of adding elements to this {@code Collection}, the 92 * behavior is not defined. 93 * 94 * @param collection 95 * the {@code Collection} of objects. 96 * @return {@code true} if this {@code Collection} is modified, {@code false} 97 * otherwise. 98 * @exception UnsupportedOperationException 99 * when adding to this {@code Collection} is not supported. 100 * @exception ClassCastException 101 * when the class of an object is inappropriate for this 102 * {@code Collection}. 103 * @exception IllegalArgumentException 104 * when an object cannot be added to this {@code Collection}. 105 * @exception NullPointerException 106 * when {@code collection} is {@code null}, or if it 107 * contains {@code null} elements and this {@code Collection} does 108 * not support such elements. 109 * @since Android 1.0 110 */ 111 public boolean addAll(Collection<? extends E> collection); 112 113 /** 114 * Removes all elements from this {@code Collection}, leaving it empty (optional). 115 * 116 * @exception UnsupportedOperationException 117 * when removing from this {@code Collection} is not supported. 118 * 119 * @see #isEmpty 120 * @see #size 121 * @since Android 1.0 122 */ 123 public void clear(); 124 125 /** 126 * Tests whether this {@code Collection} contains the specified object. Returns 127 * {@code true} if and only if at least one element {@code elem} in this 128 * {@code Collection} meets following requirement: 129 * {@code (object==null ? elem==null : object.equals(elem))}. 130 * 131 * @param object 132 * the object to search for. 133 * @return {@code true} if object is an element of this {@code Collection}, 134 * {@code false} otherwise. 135 * @exception ClassCastException 136 * if the object to look for isn't of the correct 137 * type. 138 * @exception NullPointerException 139 * if the object to look for is {@code null} and this 140 * {@code Collection} doesn't support {@code null} elements. 141 * @since Android 1.0 142 */ 143 public boolean contains(Object object); 144 145 /** 146 * Tests whether this {@code Collection} contains all objects contained in the 147 * specified {@code Collection}. If an elemenet {@code elem} is contained several 148 * times in the specified {@code Collection}, the method returns {@code true} even 149 * if {@code elem} is contained only once in this {@code Collection}. 150 * 151 * @param collection 152 * the collection of objects. 153 * @return {@code true} if all objects in the specified {@code Collection} are 154 * elements of this {@code Collection}, {@code false} otherwise. 155 * @exception ClassCastException 156 * if one or more elements of {@code collection} isn't of the 157 * correct type. 158 * @exception NullPointerException 159 * if {@code collection} contains at least one {@code null} 160 * element and this {@code Collection} doesn't support {@code null} 161 * elements. 162 * @exception NullPointerException 163 * if {@code collection} is {@code null}. 164 * @since Android 1.0 165 */ 166 public boolean containsAll(Collection<?> collection); 167 168 /** 169 * Compares the argument to the receiver, and returns true if they represent 170 * the <em>same</em> object using a class specific comparison. 171 * 172 * @param object 173 * the object to compare with this object. 174 * @return {@code true} if the object is the same as this object and 175 * {@code false} if it is different from this object. 176 * @see #hashCode 177 * @since Android 1.0 178 */ 179 public boolean equals(Object object); 180 181 /** 182 * Returns an integer hash code for the receiver. Objects which are equal 183 * return the same value for this method. 184 * 185 * @return the receiver's hash. 186 * 187 * @see #equals 188 * @since Android 1.0 189 */ 190 public int hashCode(); 191 192 /** 193 * Returns if this {@code Collection} contains no elements. 194 * 195 * @return {@code true} if this {@code Collection} has no elements, {@code false} 196 * otherwise. 197 * 198 * @see #size 199 * @since Android 1.0 200 */ 201 public boolean isEmpty(); 202 203 /** 204 * Returns an instance of {@link Iterator} that may be used to access the 205 * objects contained by this {@code Collection}. The order in which the elements are 206 * returned by the iterator is not defined. Only if the instance of the 207 * {@code Collection} has a defined order the elements are returned in that order. 208 * 209 * @return an iterator for accessing the {@code Collection} contents. 210 * @since Android 1.0 211 */ 212 public Iterator<E> iterator(); 213 214 /** 215 * Removes one instance of the specified object from this {@code Collection} if one 216 * is contained (optional). The element {@code elem} that is removed 217 * complies with {@code (object==null ? elem==null : object.equals(elem)}. 218 * 219 * @param object 220 * the object to remove. 221 * @return {@code true} if this {@code Collection} is modified, {@code false} 222 * otherwise. 223 * @exception UnsupportedOperationException 224 * when removing from this {@code Collection} is not supported. 225 * @exception ClassCastException 226 * when the object passed is not of the correct type. 227 * @exception NullPointerException 228 * if {@code object} is {@code null} and this {@code Collection} 229 * doesn't support {@code null} elements. 230 * @since Android 1.0 231 */ 232 public boolean remove(Object object); 233 234 /** 235 * Removes all occurrences in this {@code Collection} of each object in the 236 * specified {@code Collection} (optional). After this method returns none of the 237 * elements in the passed {@code Collection} can be found in this {@code Collection} 238 * anymore. 239 * 240 * @param collection 241 * the collection of objects to remove. 242 * @return {@code true} if this {@code Collection} is modified, {@code false} 243 * otherwise. 244 * 245 * @exception UnsupportedOperationException 246 * when removing from this {@code Collection} is not supported. 247 * @exception ClassCastException 248 * if one or more elements of {@code collection} 249 * isn't of the correct type. 250 * @exception NullPointerException 251 * if {@code collection} contains at least one 252 * {@code null} element and this {@code Collection} doesn't support 253 * {@code null} elements. 254 * @exception NullPointerException 255 * if {@code collection} is {@code null}. 256 * @since Android 1.0 257 */ 258 public boolean removeAll(Collection<?> collection); 259 260 /** 261 * Removes all objects from this {@code Collection} that are not also found in the 262 * {@code Collection} passed (optional). After this method returns this {@code Collection} 263 * will only contain elements that also can be found in the {@code Collection} 264 * passed to this method. 265 * 266 * @param collection 267 * the collection of objects to retain. 268 * @return {@code true} if this {@code Collection} is modified, {@code false} 269 * otherwise. 270 * @exception UnsupportedOperationException 271 * when removing from this {@code Collection} is not supported. 272 * @exception ClassCastException 273 * if one or more elements of {@code collection} 274 * isn't of the correct type. 275 * @exception NullPointerException 276 * if {@code collection} contains at least one 277 * {@code null} element and this {@code Collection} doesn't support 278 * {@code null} elements. 279 * @exception NullPointerException 280 * if {@code collection} is {@code null}. 281 * @since Android 1.0 282 */ 283 public boolean retainAll(Collection<?> collection); 284 285 /** 286 * Returns a count of how many objects this {@code Collection} contains. 287 * 288 * @return how many objects this {@code Collection} contains, or Integer.MAX_VALUE 289 * if there are more than Integer.MAX_VALUE elements in this 290 * {@code Collection}. 291 * @since Android 1.0 292 */ 293 public int size(); 294 295 /** 296 * Returns a new array containing all elements contained in this {@code Collection}. 297 * 298 * If the implementation has ordered elements it will return the element 299 * array in the same order as an iterator would return them. 300 * 301 * The array returned does not reflect any changes of the {@code Collection}. A new 302 * array is created even if the underlying data structure is already an 303 * array. 304 * 305 * @return an array of the elements from this {@code Collection}. 306 * @since Android 1.0 307 */ 308 public Object[] toArray(); 309 310 /** 311 * Returns an array containing all elements contained in this {@code Collection}. If 312 * the specified array is large enough to hold the elements, the specified 313 * array is used, otherwise an array of the same type is created. If the 314 * specified array is used and is larger than this {@code Collection}, the array 315 * element following the {@code Collection} elements is set to null. 316 * 317 * If the implementation has ordered elements it will return the element 318 * array in the same order as an iterator would return them. 319 * 320 * {@code toArray(new Object[0])} behaves exactly the same way as 321 * {@code toArray()} does. 322 * 323 * @param array 324 * the array. 325 * @return an array of the elements from this {@code Collection}. 326 * 327 * @exception ArrayStoreException 328 * when the type of an element in this {@code Collection} cannot be 329 * stored in the type of the specified array. 330 * @since Android 1.0 331 */ 332 public <T> T[] toArray(T[] array); 333} 334