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