Interface Collection<E>
-
-
类型参数:
- E -此集合中的元素的类型
-
所有超级接口:
- Iterable<E>
-
所有已知子接口
- BeanContext, BeanContextServices, BlockingDeque<E>, BlockingQueue<E>, Deque<E>, List<E>, NavigableSet<E>, Queue<E>,Set<E>, SortedSet<E>, TransferQueue<E>
-
所有已知实现类:
- AbstractCollection, AbstractList, AbstractQueue, AbstractSequentialList, AbstractSet, ArrayBlockingQueue, ArrayDeque,ArrayList, AttributeList, BeanContextServicesSupport, BeanContextSupport, ConcurrentHashMap.KeySetView,ConcurrentLinkedDeque, ConcurrentLinkedQueue, ConcurrentSkipListSet, CopyOnWriteArrayList, CopyOnWriteArraySet,DelayQueue, EnumSet, HashSet, JobStateReasons, LinkedBlockingDeque, LinkedBlockingQueue, LinkedHashSet, LinkedList,LinkedTransferQueue, PriorityBlockingQueue, PriorityQueue, RoleList, RoleUnresolvedList, Stack, SynchronousQueue, TreeSet,Vector
public interface Collection<E>
extends Iterable<E>
执行递归遍历集合的一些集合操作可能会失败,而自引用实例的异常会导致集合直接或间接包含其自身。 这包括clone(),equals(),hashCode()和toString()方法。 实现可以可选地处理自引用场景,然而大多数当前实现不这样做。
此接口是Java集合框架的成员。
实现要求:
默认方法实现(继承或其他)不应用任何同步协议。 如果Collection的实现具有特定的同步协议,则必须覆盖默认实现以应用该协议。
-
从以下版本开始:
- 1.2 另请参见:
- Set, List, Map, SortedSet, SortedMap, HashSet, TreeSet, ArrayList, LinkedList, Vector, Collections, Arrays,AbstractCollection
-
-
- 方法摘要
-
-
方法详细信息
size
int size()
- 返回此 collection 中的元素数。如果此 collection 包含的元素大于 Integer.MAX_VALUE,则返回 Integer.MAX_VALUE。
-
-
-
返回:
- 此 collection 中的元素数
isEmpty
boolean isEmpty()
- 如果此 collection 不包含元素,则返回 true。
-
-
-
返回:
- 如果此 collection 不包含元素,则返回 true
contains
boolean contains(Object o)
- 如果此 collection 包含指定的元素,则返回 true。更确切地讲,当且仅当此 collection 至少包含一个满足 (o==null ? e==null : o.equals(e)) 的元素 e 时,返回 true。
-
-
-
参数:
-
o
- 测试在此 collection 中是否存在的元素。
返回:
- 如果此 collection 包含指定的元素,则返回 true 抛出:
-
ClassCastException
- 如果指定元素的类型与此 collection 不兼容(可选)。 -
NullPointerException
- 如果指定的元素为 null,并且此 collection 不允许 null 元素(可选)。
-
iterator
Iterator<E> iterator()
- 返回在此 collection 的元素上进行迭代的迭代器。关于元素返回的顺序没有任何保证(除非此 collection 是某个能提供保证顺序的类实例)。
-
-
返回:
- 在此 collection 的元素上进行迭代的 Iterator
toArray
Object[] toArray()
-
返回包含此 collection 中所有元素的数组。如果 collection 对其迭代器返回的元素顺序做出了某些保证,那么此方法必须以相同的顺序返回这些元素。
返回的数组将是“安全的”,因为此 collection 并不维护对返回数组的任何引用。(换句话说,即使 collection 受到数组的支持,此方法也必须分配一个新的数组)。因此,调用者可以随意修改返回的数组。
此方法充当了基于数组的 API 与基于 collection 的 API 之间的桥梁。
-
-
-
返回:
- 包含此 collection 中所有元素的数组
toArray
<T> T[] toArray(T[] a)
-
返回包含此 collection 中所有元素的数组;返回数组的运行时类型与指定数组的运行时类型相同。如果指定的数组能容纳该 collection,则返回包含此 collection 元素的数组。否则,将分配一个具有指定数组的运行时类型和此 collection 大小的新数组。
如果指定的数组能容纳 collection,并有剩余空间(即数组的元素比 collection 的元素多),那么会将数组中紧接 collection 尾部的元素设置为 null。(只有 在调用者知道此 collection 没有包含任何 null 元素时才能用此方法确定 collection 的长度。)
如果此 collection 对其迭代器返回的元素顺序做出了某些保证,那么此方法必须以相同的顺序返回这些元素。
像
toArray()
方法一样,此方法充当基于数组的 API 与基于 collection 的 API 之间的桥梁。更进一步说,此方法允许对输出数组的运行时类型进行精确控制,并且在某些情况下,可以用来节省分配开销。假定 x 是只包含字符串的一个已知 collection。以下代码用来将 collection 转储到一个新分配的String 数组:
String[] y = x.toArray(new String[0]);
注意,toArray(new Object[0]) 和 toArray() 在功能上是相同的。 -
-
-
参数:
-
a
- 存储此 collection 元素的数组(如果其足够大);否则,将为此分配一个具有相同运行时类型的新数组。
返回:
- 包含此 collection 中所有元素的数组 抛出:
-
ArrayStoreException
- 如果指定数组的运行时类型不是此 collection 每个元素运行时类型的超类型 -
NullPointerException
- 如果指定的数组为 null
-
add
boolean add(E e)
-
确保此 collection 包含指定的元素(可选操作)。如果此 collection 由于调用而发生更改,则返回 true。(如果此 collection 不允许有重复元素,并且已经包含了指定的元素,则返回false。)
支持此操作的 collection 可以限制哪些元素能添加到此 collection 中来。需要特别指出的是,一些 collection 拒绝添加 null 元素,其他一些 collection 将对可以添加的元素类型强加限制。Collection 类应该在其文档中清楚地指定能添加哪些元素方面的所有限制。
如果 collection 由于某些原因(已经包含该元素的原因除外)拒绝添加特定的元素,那么它必须抛出一个异常(而不是返回 false)。这确保了在此调用返回后,collection 总是包含指定的元素。
-
-
-
参数:
-
e
- 确定此 collection 中是否存在的元素。
返回:
- 如果此 collection 由于调用而发生更改,则返回 true 抛出:
-
UnsupportedOperationException
- 如果此 collection 不支持 add 操作 -
ClassCastException
- 如果指定元素的类不允许它添加到此 collection 中 -
NullPointerException
- 如果指定的元素为 null,并且此 collection 不允许 null 元素 -
IllegalArgumentException
- 如果元素的某属性不允许它添加到此 collection 中 -
IllegalStateException
- 如果由于插入限制,元素不能在此时间添加
-
remove
boolean remove(Object o)
- 从此 collection 中移除指定元素的单个实例,如果存在的话(可选操作)。更确切地讲,如果此 collection 包含一个或多个满足 (o==null ? e==null : o.equals(e)) 的元素 e,则移除这样的元素。如果此 collection 包含指定的元素(或者此 collection 由于调用而发生更改),则返回true 。
-
-
-
参数:
-
o
- 要从此 collection 中移除的元素(如果存在)。
返回:
- 如果此调用将移除一个元素,则返回 true 抛出:
-
ClassCastException
- 如果指定元素的类型与此 collection 不兼容(可选) -
NullPointerException
- 如果指定的元素为 null,并且此 collection 不允许 null 元素(可选)。 -
UnsupportedOperationException
- 如果此 collection 不支持 remove 操作
-
containsAll
boolean containsAll(Collection<?> c)
- 如果此 collection 包含指定 collection 中的所有元素,则返回 true。
-
-
-
参数:
-
c
- 将检查是否包含在此 collection 中的 collection
返回:
- 如果此 collection 包含指定 collection 中的所有元素,则返回 true 抛出:
-
ClassCastException
- 如果指定 collection 中有一个或多个元素的类型与此 collection 不兼容(可选) -
NullPointerException
- 如果指定 collection 包含一个或多个 null 元素,并且此 collection 不允许 null 元素(可选),或者指定的 collection 为 null
另请参见:
-
contains(Object)
-
addAll
boolean addAll(Collection<? extends E> c)
- 将指定 collection 中的所有元素都添加到此 collection 中(可选操作)。如果在进行此操作的同时修改指定的 collection,那么此操作行为是不确定的。(这意味着如果指定的 collection 是此 collection,并且此 collection 为非空,那么此调用的行为是不确定的。)
-
-
-
参数:
-
c
- 包含要添加到此 collection 的元素的 collection
返回:
- 如果此 collection 由于调用而发生更改,则返回 true 抛出:
-
UnsupportedOperationException
- 如果此 collection 不支持 addAll 方法 -
ClassCastException
- 如果指定 collection 中某个元素的类不允许它添加到此 collection 中 -
NullPointerException
- 如果指定 collection 包含 null 元素,并且此 collection 不支持 null 元素,或者指定的 collection 为 null -
IllegalArgumentException
- 如果指定 collection 的元素的某属性不允许它添加到此 collection 中 -
IllegalStateException
- 如果由于插入限制,不是所有的元素都能在此时间添加
另请参见:
-
add(Object)
-
removeAll
boolean removeAll(Collection<?> c)
- 移除此 collection 中那些也包含在指定 collection 中的所有元素(可选操作)。此调用返回后,collection 中将不包含任何与指定 collection 相同的元素。
-
-
-
参数:
-
c
- 办好要从此 collection 移除的元素的 collection
返回:
- 如果此 collection 由于调用而发生更改,则返回 true 抛出:
-
UnsupportedOperationException
- 如果此 collection 不支持 removeAll 方法 -
ClassCastException
- 如果此 collection 中一个或多个元素的类型与指定 collection 不兼容(可选) -
NullPointerException
- 如果此 collection 包含一个或多个 null 元素,并且指定的 collection 不支持 null 元素(可选),或者指定的 collection 为 null
另请参见:
-
remove(Object)
,contains(Object)
-
-
-
-
boolean retainAll(Collection<?> c)
- 仅保留此 collection 中那些也包含在指定 collection 的元素(可选操作)。换句话说,移除此 collection 中未包含在指定 collection 中的所有元素。
-
-
-
参数:
- c - 包含保留在此 collection 中的元素的 collection 返回:
- 如果此 collection 由于调用而发生更改,则返回 true 抛出:
- UnsupportedOperationException - 如果此 collection 不支持 retainAll 操作
- ClassCastException - 如果此 collection 中一个或多个元素的类型与指定 collection 不兼容(可选)
- NullPointerException - 如果此 collection 包含一个或多个 null 元素,并且指定的 collection 不允许 null 元素(可选),或者指定的 collection 为 null 另请参见:
- remove(Object), contains(Object)
clear
void clear()
- 移除此 collection 中的所有元素(可选操作)。此方法返回后,除非抛出一个异常。
-
-
-
抛出:
- UnsupportedOperationException - 如果此 collection 不支持 clear 操作
equals
boolean equals(Object o)
-
比较此 collection 与指定对象是否相等。
当 Collection 接口没有对 Object.equals 的常规协定添加任何约定时,“直接”实现该 Collection 接口(换句话说,创建一个 Collection,但它不是 Set 或 List 的类)的程序员选择重写Object.equals 方法时必须小心。没必要这样做,最简单的方案是依靠 Object 的实现,然而实现者可能希望实现“值比较”,而不是默认的“引用比较”。(List 和 Set 接口要求进行这样的值比较。)
Object.equals 方法的常规协定声称相等必须是对称的(换句话说,当且仅当存在 b.equals(a) 时,才存在 a.equals(b))。List.equals 和 Set.equals 的协定声称列表只能与列表相等,set 只能与 set 相等。因此,对于一个既不实现 List 又不实现 Set 接口的 collection 类,当将此 collection 与任何列表或 set 进行比较时,常规的 equals 方法必须返回 false。(按照相同的逻辑,不可能编写一个同时正确实现 Set 和 List 接口的类。)
-
-
参数:
- o - 要与此 collection 进行相等性比较的对象。 返回:
- 如果指定对象与此 collection 相等,则返回 true 另请参见:
- Object.equals(Object), Set.equals(Object), List.equals(Object)
hashCode
int hashCode()
- 返回此 collection 的哈希码值。当 Collection 接口没有为 Object.hashCode 方法的常规协定添加任何约束时,为了满足 Object.hashCode 方法的常规协定,程序员应该注意任何重写Object.equals 方法的类必须重写 Object.hashCode 方法。需要特别指出的是,c1.equals(c2) 暗示着 c1.hashCode()==c2.hashCode()。
-
-
返回:
- 此 collection 的哈希码值 另请参见:
- Object.hashCode(), Object.equals(Object)
-
-
-
spliterator
default Spliterator<E> spliterator()
在此集合中的元素上创建一个Spliterator。实现应该记录spliterator报告的特征值。如果spliterator报告Spliterator.SIZED并且此集合不包含元素,则不需要报告此类特征值。应该通过可以返回更高效的spliterator的子类覆盖默认实现。为了保留stream()和parallelStream()方法的预期懒惰行为,spliterators 应具有IMMUTABLE或CONCURRENT的特性,或者具有后期绑定(late-binding)的特性。如果这些都不实用,则重写类应描述spliterator的绑定和结构干扰策略,并应重写stream()和parallelStream()方法来创建流,以使用Spliterator的提供者,如:Stream <E> s = StreamSupport.stream(()-> spliterator(),spliteratorCharacteristics)这些要求确保由stream()和parallelStream()方法生成的流将在终端流操作启动时反映集合的内容。指定者:接口Iterable <E>中的spliterator实现要求:默认实现从集合的Iterator创建一个后期绑定的spliterator。spliterator继承集合的迭代器的快速失败行为(spliterator)属性。创建的Spliterator报告Spliterator.SIZED。实现要注意的地方:创建的Spliterator还会报告Spliterator.SUBSIZED。如果拼接器不包含任何元素,那么超出SIZED和SISBSIZED的附加特征值的报告不会帮助客户控制,专门化或简化计算。但是,这样做可以使空集合能够 共享使用不可变和空的Spliterator实例(请参阅Spliterators.emptySpliterator()),并允许客户端确定此类spliterator 是否不覆盖任何元素。返回:一个Spliterator在这个集合中的元素从以下版本开始:1.8
-
stream
default Stream<E> stream()
返回一个以此集合为依据的顺序流。当spliterator()方法不能返回IMMUTABLE,CONCURRENT或后期绑定的spliterator 时,应该覆盖此方法。 (有关详细信息,请参阅spliterator())实施要求:默认实现从集合的Spliterator创建一个顺序流。返回:这个集合中的元素的顺序流从以下版本开始:1.8
- default boolean removeIf(Predicate<? super E> filter)
- default Spliterator<E> spliterator()
- default Stream<E> stream()
- default Stream<E> parallelStream()
- Interface Predicate<T>
- Interface Spliterator<T>
- Interface Stream<T>