58 * invocation would have no effect on the collection. For example, invoking |
58 * invocation would have no effect on the collection. For example, invoking |
59 * the {@link #addAll(Collection)} method on an unmodifiable collection may, |
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 |
60 * but is not required to, throw the exception if the collection to be added |
61 * is empty. |
61 * is empty. |
62 * |
62 * |
63 * <p>Some collection implementations have restrictions on the elements that |
63 * <p><a name="optional-restrictions"/> |
|
64 * Some collection implementations have restrictions on the elements that |
64 * they may contain. For example, some implementations prohibit null elements, |
65 * they may contain. For example, some implementations prohibit null elements, |
65 * and some have restrictions on the types of their elements. Attempting to |
66 * and some have restrictions on the types of their elements. Attempting to |
66 * add an ineligible element throws an unchecked exception, typically |
67 * add an ineligible element throws an unchecked exception, typically |
67 * <tt>NullPointerException</tt> or <tt>ClassCastException</tt>. Attempting |
68 * <tt>NullPointerException</tt> or <tt>ClassCastException</tt>. Attempting |
68 * to query the presence of an ineligible element may throw an exception, |
69 * to query the presence of an ineligible element may throw an exception, |
150 * |
151 * |
151 * @param o element whose presence in this collection is to be tested |
152 * @param o element whose presence in this collection is to be tested |
152 * @return <tt>true</tt> if this collection contains the specified |
153 * @return <tt>true</tt> if this collection contains the specified |
153 * element |
154 * element |
154 * @throws ClassCastException if the type of the specified element |
155 * @throws ClassCastException if the type of the specified element |
155 * is incompatible with this collection (optional) |
156 * is incompatible with this collection |
|
157 * (<a href="#optional-restrictions">optional</a>) |
156 * @throws NullPointerException if the specified element is null and this |
158 * @throws NullPointerException if the specified element is null and this |
157 * collection does not permit null elements (optional) |
159 * collection does not permit null elements |
|
160 * (<a href="#optional-restrictions">optional</a>) |
158 */ |
161 */ |
159 boolean contains(Object o); |
162 boolean contains(Object o); |
160 |
163 |
161 /** |
164 /** |
162 * Returns an iterator over the elements in this collection. There are no |
165 * Returns an iterator over the elements in this collection. There are no |
277 * equivalently, if this collection changed as a result of the call). |
280 * equivalently, if this collection changed as a result of the call). |
278 * |
281 * |
279 * @param o element to be removed from this collection, if present |
282 * @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 |
283 * @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 |
284 * @throws ClassCastException if the type of the specified element |
282 * is incompatible with this collection (optional) |
285 * is incompatible with this collection |
|
286 * (<a href="#optional-restrictions">optional</a>) |
283 * @throws NullPointerException if the specified element is null and this |
287 * @throws NullPointerException if the specified element is null and this |
284 * collection does not permit null elements (optional) |
288 * collection does not permit null elements |
|
289 * (<a href="#optional-restrictions">optional</a>) |
285 * @throws UnsupportedOperationException if the <tt>remove</tt> operation |
290 * @throws UnsupportedOperationException if the <tt>remove</tt> operation |
286 * is not supported by this collection |
291 * is not supported by this collection |
287 */ |
292 */ |
288 boolean remove(Object o); |
293 boolean remove(Object o); |
289 |
294 |
297 * @param c collection to be checked for containment in this collection |
302 * @param c collection to be checked for containment in this collection |
298 * @return <tt>true</tt> if this collection contains all of the elements |
303 * @return <tt>true</tt> if this collection contains all of the elements |
299 * in the specified collection |
304 * in the specified collection |
300 * @throws ClassCastException if the types of one or more elements |
305 * @throws ClassCastException if the types of one or more elements |
301 * in the specified collection are incompatible with this |
306 * in the specified collection are incompatible with this |
302 * collection (optional) |
307 * collection |
|
308 * (<a href="#optional-restrictions">optional</a>) |
303 * @throws NullPointerException if the specified collection contains one |
309 * @throws NullPointerException if the specified collection contains one |
304 * or more null elements and this collection does not permit null |
310 * or more null elements and this collection does not permit null |
305 * elements (optional), or if the specified collection is null |
311 * elements |
|
312 * (<a href="#optional-restrictions">optional</a>), |
|
313 * or if the specified collection is null. |
306 * @see #contains(Object) |
314 * @see #contains(Object) |
307 */ |
315 */ |
308 boolean containsAll(Collection<?> c); |
316 boolean containsAll(Collection<?> c); |
309 |
317 |
310 /** |
318 /** |
344 * call |
352 * call |
345 * @throws UnsupportedOperationException if the <tt>removeAll</tt> method |
353 * @throws UnsupportedOperationException if the <tt>removeAll</tt> method |
346 * is not supported by this collection |
354 * is not supported by this collection |
347 * @throws ClassCastException if the types of one or more elements |
355 * @throws ClassCastException if the types of one or more elements |
348 * in this collection are incompatible with the specified |
356 * in this collection are incompatible with the specified |
349 * collection (optional) |
357 * collection |
|
358 * (<a href="#optional-restrictions">optional</a>) |
350 * @throws NullPointerException if this collection contains one or more |
359 * @throws NullPointerException if this collection contains one or more |
351 * null elements and the specified collection does not support |
360 * null elements and the specified collection does not support |
352 * null elements (optional), or if the specified collection is null |
361 * null elements |
|
362 * (<a href="#optional-restrictions">optional</a>), |
|
363 * or if the specified collection is null |
353 * @see #remove(Object) |
364 * @see #remove(Object) |
354 * @see #contains(Object) |
365 * @see #contains(Object) |
355 */ |
366 */ |
356 boolean removeAll(Collection<?> c); |
367 boolean removeAll(Collection<?> c); |
357 |
368 |
365 * @return <tt>true</tt> if this collection changed as a result of the call |
376 * @return <tt>true</tt> if this collection changed as a result of the call |
366 * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation |
377 * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation |
367 * is not supported by this collection |
378 * is not supported by this collection |
368 * @throws ClassCastException if the types of one or more elements |
379 * @throws ClassCastException if the types of one or more elements |
369 * in this collection are incompatible with the specified |
380 * in this collection are incompatible with the specified |
370 * collection (optional) |
381 * collection |
|
382 * (<a href="#optional-restrictions">optional</a>) |
371 * @throws NullPointerException if this collection contains one or more |
383 * @throws NullPointerException if this collection contains one or more |
372 * null elements and the specified collection does not permit null |
384 * null elements and the specified collection does not permit null |
373 * elements (optional), or if the specified collection is null |
385 * elements |
|
386 * (<a href="#optional-restrictions">optional</a>), |
|
387 * or if the specified collection is null |
374 * @see #remove(Object) |
388 * @see #remove(Object) |
375 * @see #contains(Object) |
389 * @see #contains(Object) |
376 */ |
390 */ |
377 boolean retainAll(Collection<?> c); |
391 boolean retainAll(Collection<?> c); |
378 |
392 |