sample/java.util.Collection.txt

   1 *java.util.Collection* *Collection* The root interface in the collection hierarc
   2
   3 public interface interface Collection
   4
   5   implements |java.lang.Iterable|
   6
   7 |java.util.Collection_Description|
   8 |java.util.Collection_Fields|
   9 |java.util.Collection_Constructors|
  10 |java.util.Collection_Methods|
  11
  12 ================================================================================
  13
  14 *java.util.Collection_Methods*
  15 |java.util.Collection.add(E)|Ensures that this collection contains the specifie
  16 |java.util.Collection.addAll(Collection)|Adds all of the elements in the specif
  17 |java.util.Collection.clear()|Removes all of the elements from this collection
  18 |java.util.Collection.contains(Object)|Returns true if this collection contains
  19 |java.util.Collection.containsAll(Collection)|Returns true if this collection c
  20 |java.util.Collection.equals(Object)|Compares the specified object with this co
  21 |java.util.Collection.hashCode()|Returns the hash code value for this collectio
  22 |java.util.Collection.isEmpty()|Returns true if this collection contains no ele
  23 |java.util.Collection.iterator()|Returns an iterator over the elements in this
  24 |java.util.Collection.remove(Object)|Removes a single instance of the specified
  25 |java.util.Collection.removeAll(Collection)|Removes all this collection's eleme
  26 |java.util.Collection.retainAll(Collection)|Retains only the elements in this c
  27 |java.util.Collection.size()|Returns the number of elements in this collection.
  28 |java.util.Collection.toArray()|Returns an array containing all of the elements
  29 |java.util.Collection.toArray(T[])|Returns an array containing all of the eleme
  30
  31 *java.util.Collection_Description*
  32
  33 The root interface in the collection hierarchy. A collection represents a group
  34 of objects, known as its elements. Some collections allow duplicate elements
  35 and others do not. Some are ordered and others unordered. The JDK does not
  36 provide any direct implementations of this interface: it provides
  37 implementations of more specific subinterfaces like Set and List. This
  38 interface is typically used to pass collections around and manipulate them
  39 where maximum generality is desired.
  40
  41 Bags or multisets (unordered collections that may contain duplicate elements)
  42 should implement this interface directly.
  43
  44 All general-purpose Collection implementation classes (which typically
  45 implement Collection indirectly through one of its subinterfaces) should
  46 provide two "standard" constructors: a void (no arguments) constructor, which
  47 creates an empty collection, and a constructor with a single argument of type
  48 Collection, which creates a new collection with the same elements as its
  49 argument. In effect, the latter constructor allows the user to copy any
  50 collection, producing an equivalent collection of the desired implementation
  51 type. There is no way to enforce this convention (as interfaces cannot contain
  52 constructors) but all of the general-purpose Collection implementations in the
  53 Java platform libraries comply.
  54
  55 The "destructive" methods contained in this interface, that is, the methods
  56 that modify the collection on which they operate, are specified to throw
  57 UnsupportedOperationException if this collection does not support the
  58 operation. If this is the case, these methods may, but are not required to,
  59 throw an UnsupportedOperationException if the invocation would have no effect
  60 on the collection. For example, invoking the (|java.util.Collection|) method on
  61 an unmodifiable collection may, but is not required to, throw the exception if
  62 the collection to be added is empty.
  63
  64 Some collection implementations have restrictions on the elements that they may
  65 contain. For example, some implementations prohibit null elements, and some
  66 have restrictions on the types of their elements. Attempting to add an
  67 ineligible element throws an unchecked exception, typically
  68 NullPointerException or ClassCastException. Attempting to query the presence of
  69 an ineligible element may throw an exception, or it may simply return false;
  70 some implementations will exhibit the former behavior and some will exhibit the
  71 latter. More generally, attempting an operation on an ineligible element whose
  72 completion would not result in the insertion of an ineligible element into the
  73 collection may throw an exception or it may succeed, at the option of the
  74 implementation. Such exceptions are marked as "optional" in the specification
  75 for this interface.
  76
  77 This interface is a member of the <a href="/../guide/collections/index.html">
  78 Java Collections Framework.
  79
  80 Many methods in Collections Framework interfaces are defined in terms of the
  81 equals(|java.lang.Object|) method. For example, the specification for the
  82 contains(Object o)(|java.util.Collection|) method says: "returns true if and
  83 only if this collection contains at least one element e such that (o==null ?
  84 e==null : o.equals(e))." This specification should not be construed to imply
  85 that invoking Collection.contains with a non-null argument o will cause
  86 o.equals(e) to be invoked for any element e. Implementations are free to
  87 implement optimizations whereby the equals invocation is avoided, for example,
  88 by first comparing the hash codes of the two elements. (The
  89 (|java.lang.Object|) specification guarantees that two objects with unequal
  90 hash codes cannot be equal.) More generally, implementations of the various
  91 Collections Framework interfaces are free to take advantage of the specified
  92 behavior of underlying (|java.lang.Object|) methods wherever the implementor
  93 deems it appropriate.
  94
  95
  96 *java.util.Collection.add(E)*
  97
  98 public boolean add(java.lang.Object o)
  99
 100 Ensures that this collection contains the specified element (optional
 101 operation). Returns true if this collection changed as a result of the call.
 102 (Returns false if this collection does not permit duplicates and already
 103 contains the specified element.)
 104
 105 Collections that support this operation may place limitations on what elements
 106 may be added to this collection. In particular, some collections will refuse to
 107 add null elements, and others will impose restrictions on the type of elements
 108 that may be added. Collection classes should clearly specify in their
 109 documentation any restrictions on what elements may be added.
 110
 111 If a collection refuses to add a particular element for any reason other than
 112 that it already contains the element, it must throw an exception (rather than
 113 returning false). This preserves the invariant that a collection always
 114 contains the specified element after this call returns.
 115
 116     o - element whose presence in this collection is to be ensured.
 117
 118     Returns: true if this collection changed as a result of the call
 119 *java.util.Collection.addAll(Collection)*
 120
 121 public boolean addAll(java.util.Collection c)
 122
 123 Adds all of the elements in the specified collection to this collection
 124 (optional operation). The behavior of this operation is undefined if the
 125 specified collection is modified while the operation is in progress. (This
 126 implies that the behavior of this call is undefined if the specified collection
 127 is this collection, and this collection is nonempty.)
 128
 129     c - elements to be inserted into this collection.
 130
 131     Returns: true if this collection changed as a result of the call
 132 *java.util.Collection.clear()*
 133
 134 public void clear()
 135
 136 Removes all of the elements from this collection (optional operation). This
 137 collection will be empty after this method returns unless it throws an
 138 exception.
 139
 140
 141 *java.util.Collection.contains(Object)*
 142
 143 public boolean contains(java.lang.Object o)
 144
 145 Returns true if this collection contains the specified element. More formally,
 146 returns true if and only if this collection contains at least one element e
 147 such that (o==null ? e==null : o.equals(e)).
 148
 149     o - element whose presence in this collection is to be tested.
 150
 151     Returns: true if this collection contains the specified element
 152 *java.util.Collection.containsAll(Collection)*
 153
 154 public boolean containsAll(java.util.Collection c)
 155
 156 Returns true if this collection contains all of the elements in the specified
 157 collection.
 158
 159     c - collection to be checked for containment in this collection.
 160
 161     Returns: true if this collection contains all of the elements in the specified
 162              collection
 163 *java.util.Collection.equals(Object)*
 164
 165 public boolean equals(java.lang.Object o)
 166
 167 Compares the specified object with this collection for equality.
 168
 169 While the Collection interface adds no stipulations to the general contract for
 170 the Object.equals, programmers who implement the Collection interface
 171 "directly" (in other words, create a class that is a Collection but is not a
 172 Set or a List) must exercise care if they choose to override the Object.equals.
 173 It is not necessary to do so, and the simplest course of action is to rely on
 174 Object's implementation, but the implementer may wish to implement a "value
 175 comparison" in place of the default "reference comparison." (The List and Set
 176 interfaces mandate such value comparisons.)
 177
 178 The general contract for the Object.equals method states that equals must be
 179 symmetric (in other words, a.equals(b) if and only if b.equals(a)). The
 180 contracts for List.equals and Set.equals state that lists are only equal to
 181 other lists, and sets to other sets. Thus, a custom equals method for a
 182 collection class that implements neither the List nor Set interface must return
 183 false when this collection is compared to any list or set. (By the same logic,
 184 it is not possible to write a class that correctly implements both the Set and
 185 List interfaces.)
 186
 187     o - Object to be compared for equality with this collection.
 188
 189     Returns: true if the specified object is equal to this collection
 190 *java.util.Collection.hashCode()*
 191
 192 public int hashCode()
 193
 194 Returns the hash code value for this collection. While the Collection interface
 195 adds no stipulations to the general contract for the Object.hashCode method,
 196 programmers should take note that any class that overrides the Object.equals
 197 method must also override the Object.hashCode method in order to satisfy the
 198 general contract for the Object.hashCodemethod. In particular, c1.equals(c2)
 199 implies that c1.hashCode()==c2.hashCode().
 200
 201
 202     Returns: the hash code value for this collection
 203 *java.util.Collection.isEmpty()*
 204
 205 public boolean isEmpty()
 206
 207 Returns true if this collection contains no elements.
 208
 209
 210     Returns: true if this collection contains no elements
 211 *java.util.Collection.iterator()*
 212
 213 public |java.util.Iterator| iterator()
 214
 215 Returns an iterator over the elements in this collection. There are no
 216 guarantees concerning the order in which the elements are returned (unless this
 217 collection is an instance of some class that provides a guarantee).
 218
 219
 220     Returns: an Iterator over the elements in this collection
 221 *java.util.Collection.remove(Object)*
 222
 223 public boolean remove(java.lang.Object o)
 224
 225 Removes a single instance of the specified element from this collection, if it
 226 is present (optional operation). More formally, removes an element e such that
 227 (o==null ? e==null : o.equals(e)), if this collection contains one or more such
 228 elements. Returns true if this collection contained the specified element (or
 229 equivalently, if this collection changed as a result of the call).
 230
 231     o - element to be removed from this collection, if present.
 232
 233     Returns: true if this collection changed as a result of the call
 234 *java.util.Collection.removeAll(Collection)*
 235
 236 public boolean removeAll(java.util.Collection c)
 237
 238 Removes all this collection's elements that are also contained in the specified
 239 collection (optional operation). After this call returns, this collection will
 240 contain no elements in common with the specified collection.
 241
 242     c - elements to be removed from this collection.
 243
 244     Returns: true if this collection changed as a result of the call
 245 *java.util.Collection.retainAll(Collection)*
 246
 247 public boolean retainAll(java.util.Collection c)
 248
 249 Retains only the elements in this collection that are contained in the
 250 specified collection (optional operation). In other words, removes from this
 251 collection all of its elements that are not contained in the specified
 252 collection.
 253
 254     c - elements to be retained in this collection.
 255
 256     Returns: true if this collection changed as a result of the call
 257 *java.util.Collection.size()*
 258
 259 public int size()
 260
 261 Returns the number of elements in this collection. If this collection contains
 262 more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
 263
 264
 265     Returns: the number of elements in this collection
 266 *java.util.Collection.toArray()*
 267
 268 public |java.lang.Object| toArray()
 269
 270 Returns an array containing all of the elements in this collection. If the
 271 collection makes any guarantees as to what order its elements are returned by
 272 its iterator, this method must return the elements in the same order.
 273
 274 The returned array will be "safe" in that no references to it are maintained by
 275 this collection. (In other words, this method must allocate a new array even if
 276 this collection is backed by an array). The caller is thus free to modify the
 277 returned array.
 278
 279 This method acts as bridge between array-based and collection-based APIs.
 280
 281
 282     Returns: an array containing all of the elements in this collection
 283 *java.util.Collection.toArray(T[])*
 284
 285 public |java.lang.Object| toArray(java.lang.Object[] a)
 286
 287 Returns an array containing all of the elements in this collection; the runtime
 288 type of the returned array is that of the specified array. If the collection
 289 fits in the specified array, it is returned therein. Otherwise, a new array is
 290 allocated with the runtime type of the specified array and the size of this
 291 collection.
 292
 293 If this collection fits in the specified array with room to spare (i.e., the
 294 array has more elements than this collection), the element in the array
 295 immediately following the end of the collection is set to null. This is useful
 296 in determining the length of this collection only if the caller knows that this
 297 collection does not contain any null elements.)
 298
 299 If this collection makes any guarantees as to what order its elements are
 300 returned by its iterator, this method must return the elements in the same
 301 order.
 302
 303 Like the toArray method, this method acts as bridge between array-based and
 304 collection-based APIs. Further, this method allows precise control over the
 305 runtime type of the output array, and may, under certain circumstances, be used
 306 to save allocation costs
 307
 308 Suppose l is a List known to contain only strings. The following code can be
 309 used to dump the list into a newly allocated array of String:
 310
 311
 312
 313 String[] x = (String[]) v.toArray(new String[0]);
 314
 315 Note that toArray(new Object[0]) is identical in function to toArray().
 316
 317     a - the array into which the elements of this collection are to be stored, if it is
 318        big enough; otherwise, a new array of the same runtime type is allocated
 319        for this purpose.
 320
 321     Returns: an array containing the elements of this collection
 322