Collection<E>接口

所在包：java.util .Collection

所有超级接口All Superinterfaces：Iterable<E> 
所有已知子接口All Known Subinterfaces：
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>


Collection 层次结构 中的根接口。Collection 表示一组对象，这些对象也称为 collection 的元素。一些 collection 允许有重复的元素，而另一些则不允许。一些 collection 是有序的，而另一些则是无序的。JDK 不提供此接口的任何直接 实现：它提供更具体的子接口（如 Set 和 List）实现。此接口通常用来传递 collection，并在需要最大普遍性的地方操作这些 collection。


包 (bag) 或多集合 (multiset)（可能包含重复元素的无序 collection）应该直接实现此接口。


所有通用的 Collection 实现类（通常通过它的一个子接口间接实现 Collection）应该提供两个“标准”构造方法：一个是 void（无参数）构造方法，用于创建空 collection；另一个是带有 Collection 类型单参数的构造方法，用于创建一个具有与其参数相同元素新的 collection。实际上，后者允许用户复制任何 collection，以生成所需实现类型的一个等效 collection。尽管无法强制执行此约定（因为接口不能包含构造方法），但是 Java 平台库中所有通用的 Collection 实现都遵从它。


此接口中包含的“破坏性”方法，是指可修改其所操作的 collection 的那些方法，如果此 collection 不支持该操作，则指定这些方法抛出 UnsupportedOperationException。如果是这样，那么在调用对该 collection 无效时，这些方法可能，但并不一定抛出 UnsupportedOperationException。例如，如果要添加的 collection 为空且不可修改，则对该 collection 调用 addAll(Collection) 方法时，可能但并不一定抛出异常。


一些 collection 实现对它们可能包含的元素有所限制。例如，某些实现禁止 null 元素，而某些实现则对元素的类型有限制。试图添加不合格的元素将抛出一个未经检查的异常，通常是 NullPointerException 或 ClassCastException。试图查询是否存在不合格的元素可能抛出一个异常，或者只是简单地返回 false；某些实现将表现出前一种行为，而某些实现则表现后一种。较为常见的是，试图对某个不合格的元素执行操作且该操作的完成不会导致将不合格的元素插入 collection 中，将可能抛出一个异常，也可能操作成功，这取决于实现本身。这样的异常在此接口的规范中标记为“可选”。


由每个 collection 来确定其自身的同步策略。在没有实现的强烈保证的情况下，调用由另一进程正在更改的 collection 的方法可能会出现不确定行为；这包括直接调用，将 collection 传递给可能执行调用的方法，以及使用现有迭代器检查 collection。


Collections Framework 接口中的很多方法是根据 equals 方法定义的。例如，contains(Object o) 方法的规范声明：“当且仅当此 collection 包含至少一个满足 (o==null ? e==null :o.equals(e)) 的元素 e 时，返回 true。”不 应将此规范理解为它暗指调用具有非空参数 o 的 Collection.contains 方法会导致为任意的 e 元素调用 o.equals(e) 方法。可随意对各种实现执行优化，只要避免调用 equals 即可，例如，通过首先比较两个元素的哈希码。（Object.hashCode() 规范保证哈希码不相等的两个对象不会相等）。较为常见的是，各种 Collections Framework 接口的实现可随意利用底层 Object 方法的指定行为，而不管实现程序认为它是否合适。


此接口是 Java Collections Framework 的一个成员。


从以下版本开始：
1.2
另请参见：
Set, List, Map, SortedSet, SortedMap, HashSet, TreeSet, ArrayList, LinkedList, Vector, Collections, Arrays, AbstractCollection


 


 





方法摘要


Modifier and TypeMethod and Description



boolean
add(E e)

确保此集合包含指定的元素（可选操作）。






boolean
addAll(Collection<? extends E> c)

将指定集合中的所有元素添加到此集合（可选操作）。






void
clear()

从此集合中删除所有元素（可选操作）。






boolean
contains(Object o)

如果此集合包含指定的元素，则返回 true 。






boolean
containsAll(Collection<?> c)

如果此集合包含指定 集合中的所有元素，则返回true。






boolean
equals(Object o)

将指定的对象与此集合进行比较以获得相等性。






int
hashCode()

返回此集合的哈希码值。






boolean
isEmpty()

如果此集合不包含元素，则返回 true 。






Iterator<E>
iterator()

返回此集合中的元素的迭代器。






default Stream<E>
parallelStream()

返回可能并行的 Stream与此集合作为其来源。






boolean
remove(Object o)

从该集合中删除指定元素的单个实例（如果存在）（可选操作）。






boolean
removeAll(Collection<?> c)

删除指定集合中包含的所有此集合的元素（可选操作）。






default boolean
removeIf(Predicate<? super E> filter)

删除满足给定谓词的此集合的所有元素。






boolean
retainAll(Collection<?> c)

仅保留此集合中包含在指定集合中的元素（可选操作）。






int
size()

返回此集合中的元素数。






default Spliterator<E>
spliterator()

创建一个Spliterator在这个集合中的元素。






default Stream<E>
stream()

返回以此集合作为源的顺序 Stream 。






Object[]
toArray()

返回一个包含此集合中所有元素的数组。






<T> T[]
toArray(T[] a)

返回包含此集合中所有元素的数组; 返回的数组的运行时类型是指定数组的运行时类型。










方法详细信息


    

  • 

    size
    

    int size()
    

    返回此集合中的元素数。 如果此收藏包含超过Integer.MAX_VALUE个元素，则返回Integer.MAX_VALUE 。
    

    结果 
    此集合中的元素数 
    • 



    

  • 

    isEmpty
    

    boolean isEmpty()
    

    如果此集合不包含元素，则返回 true 。
    

    结果 
    true如果此集合不包含元素 
    • 



    

  • 

    contains
    

    boolean contains(Object o)
    

    如果此集合包含指定的元素，则返回true 。 更正式地，返回true如果且仅当该集合至少包含一个元素e使得(o==null ? e==null : o.equals(e)) 。
    

    参数 
    o - 要在此集合中存在的元素要进行测试
    结果 
    true如果此集合包含指定的元素
    异常 
    ClassCastException - 如果指定元素的类型与此集合不兼容（ optional ）
    NullPointerException - 如果指定的元素为空，并且此集合不允许空元素（ optional ）  
    • 



    

  • 

    iterator
    

    Iterator<E> iterator()
    

    返回此集合中的元素的迭代器。 没有关于元素返回顺序的保证（除非这个集合是提供保证的某个类的实例）。
    

    Specified by: 
    iterator在接口 Iterable<E>
    结果 
    一个 Iterator在这个集合中的元素 
    • 



    

  • 

    toArray
    

    Object[] toArray()
    

    返回一个包含此集合中所有元素的数组。 如果此集合对其迭代器返回的元素的顺序做出任何保证，则此方法必须以相同的顺序返回元素。

    返回的数组将是“安全的”，因为该集合不保留对它的引用。 （换句话说，这个方法必须分配一个新的数组，即使这个集合是由数组支持的）。 因此，调用者可以自由地修改返回的数组。
    

    此方法充当基于阵列和基于集合的API之间的桥梁。
    

    

    结果 
    一个包含此集合中所有元素的数组 
    • 



    

  • 

    toArray
    

    <T> T[] toArray(T[] a)
    

    返回包含此集合中所有元素的数组; 返回的数组的运行时类型是指定数组的运行时类型。 如果集合适合指定的数组，则返回其中。 否则，将为指定数组的运行时类型和此集合的大小分配一个新数组。

    如果此集合适合指定的数组，并具有剩余空间（即，该数组具有比此集合更多的元素），则紧跟在集合结束后的数组中的元素将设置为null 。 （ 仅当调用者知道此集合不包含任何null元素时，这才有助于确定此集合的长度。）
    

    如果此集合对其迭代器返回的元素的顺序做出任何保证，则此方法必须以相同的顺序返回元素。
    

    像toArray()方法一样，此方法充当基于数组和基于集合的API之间的桥梁。 此外，该方法允许精确地控制输出阵列的运行时类型，并且在某些情况下可以用于节省分配成本。
    

    假设x是一个已知只包含字符串的集合。 以下代码可用于将集合转储到新分配的数组中： String ：
    

      String[] y = x.toArray(new String[0]); 
    
请注意， toArray(new Object[0])的功能与toArray()相同 。
    

    参数类型 
    T - 包含集合的数组的运行时类型
    参数 
    a - 要存储此集合的元素的数组，如果它足够大; 否则，为此目的分配相同运行时类型的新数组。
    结果 
    一个包含此集合中所有元素的数组
    异常 
    ArrayStoreException - 如果指定数组的运行时类型不是此集合中每个元素的运行时类型的超类型
    NullPointerException - 如果指定的数组为空 
    • 



    

  • 

    add
    

    boolean add(E e)
    

    确保此集合包含指定的元素（可选操作）。 如果此集合由于调用而更改，则返回true 。 （如果此集合不允许重复，并且已包含指定的元素，则返回false。 ）

    支持此操作的集合可能会限制可能添加到此集合的元素。 特别是一些集合拒绝添加null种元素，和其他人将强加可添加元素的类型限制。 收集类应在其文档中明确说明可能添加哪些元素的限制。
    

    如果一个集合拒绝添加一个特定的元素，除了它已经包含该元素之外，它必须抛出异常（而不是返回false ）。 这保留了一个集合在此调用返回后始终包含指定元素的不变量。
    

    

    参数 
    e - 要确保在此集合中的存在的元素
    结果 
    true如果此集合由于调用而更改
    异常 
    UnsupportedOperationException - 如果此 集合不支持add操作
    ClassCastException - 如果指定元素的类阻止将其添加到此集合
    NullPointerException - 如果指定的元素为空，并且该集合不允许空元素
    IllegalArgumentException - 如果元素的某些属性阻止其添加到此集合
    IllegalStateException - 如果由于插入限制，此时无法添加该元素 
    • 



    

  • 

    remove
    

    boolean remove(Object o)
    

    从该集合中删除指定元素的单个实例（如果存在）（可选操作）。 更正式地，删除元素e ，使得(o==null ? e==null : o.equals(e)) ，如果该集合包含一个或多个这样的元素。 如果此集合包含指定的元素（或等效地，如果此集合由于调用而更改），则返回true 。
    

    参数 
    o - 要从此集合中删除的元素（如果存在）
    结果 
    true如果一个元素因此调用而被删除
    异常 
    ClassCastException - 如果指定元素的类型与此集合不兼容（ optional ）
    NullPointerException - 如果指定的元素为空，并且此集合不允许空元素（ optional ）
    UnsupportedOperationException - 如果此 集合不支持remove操作 
    • 



    

  • 

    containsAll
    

    boolean containsAll(Collection<?> c)
    

    如果此集合包含指定 集合中的所有元素，则返回true。
    

    参数 
    c - 要在此集合中检查遏制的集合
    结果 
    true如果此集合包含指定集合中的所有元素
    异常 
    ClassCastException - 如果指定集合中的一个或多个元素的类型与此集合不兼容（ optional ）
    NullPointerException - 如果指定的集合包含一个或多个空元素，并且此集合不允许空元素（ optional ），或者指定的集合为空。
    另请参见： 
    contains(Object)
    • 



    

  • 

    addAll
    

    boolean addAll(Collection<? extends E> c)
    

    将指定集合中的所有元素添加到此集合（可选操作）。 如果在操作进行中修改了指定的集合，则此操作的行为是未定义的。 （这意味着如果指定的集合是此集合，此调用的行为是未定义的，并且此集合是非空的。）
    

    参数 
    c - 包含要添加到此集合的元素的集合
    结果 
    true如果此收集因呼叫而更改
    异常 
    UnsupportedOperationException - 如果此 集合不支持addAll操作
    ClassCastException - 如果指定集合的元素的类阻止将其添加到此集合
    NullPointerException - 如果指定的集合包含一个空元素，并且此集合不允许空元素，或者如果指定的集合为空
    IllegalArgumentException - 如果指定集合的元素的某些属性阻止其添加到此集合
    IllegalStateException - 如果不是所有的元素可以在此时由于插入限制添加
    另请参见： 
    add(Object)
    • 



    

  • 

    removeAll
    

    boolean removeAll(Collection<?> c)
    

    删除指定集合中包含的所有此集合的元素（可选操作）。 此调用返回后，此集合将不包含与指定集合相同的元素。
    

    参数 
    c - 包含要从此集合中删除的元素的集合
    结果 
    true如果此集合由于调用而更改
    异常 
    UnsupportedOperationException - 如果此 集合不支持 removeAll方法
    ClassCastException - 如果此集合中的一个或多个元素的类型与指定的集合不兼容（ optional ）
    NullPointerException - 如果此集合包含一个或多个空元素，并且指定的集合不支持空元素（ optional ），或者如果指定的集合为空
    另请参见： 
    remove(Object) ， contains(Object)
    • 



    

  • 

    removeIf
    

    default boolean removeIf(Predicate<? super E> filter)
    

    删除满足给定谓词的此集合的所有元素。 在迭代或谓词中抛出的错误或运行时异常被转发给调用者。
    

    实现要求： 
    默认实现使用其iterator()遍历集合的所有元素。 使用Iterator.remove()删除每个匹配元素。 如果集合的迭代器不支持删除，那么UnsupportedOperationException将被抛出第一个匹配元素。
    参数 
    filter - 对要删除的元素返回 true
    结果 
    true如果有任何元素被删除
    异常 
    NullPointerException - 如果指定的过滤器为空
    UnsupportedOperationException - 如果元素无法从此集合中删除。 如果不能删除匹配的元素，或者一般来说，不支持删除，则实现可能会抛出此异常。
    从以下版本开始： 
    1.8 
    • 



    

  • 

    retainAll
    

    boolean retainAll(Collection<?> c)
    

    仅保留此集合中包含在指定集合中的元素（可选操作）。 换句话说，从该集合中删除所有不包含在指定集合中的元素。
    

    参数 
    c - 包含要保留在此集合中的元素的集合
    结果 
    true如果此收集因呼叫而更改
    异常 
    UnsupportedOperationException - 如果此 集合不支持retainAll操作
    ClassCastException - 如果此集合中的一个或多个元素的类型与指定的集合不兼容（ optional ）
    NullPointerException - 如果此集合包含一个或多个空元素，并且指定的集合不允许空元素（ optional ），或者如果指定的集合为空
    另请参见： 
    remove(Object) ， contains(Object)
    • 



    

  • 

    clear
    

    void clear()
    

    从此集合中删除所有元素（可选操作）。 此方法返回后，集合将为空。
    

    异常 
    UnsupportedOperationException - 如果此 集合不支持clear操作 
    • 



    

  • 

    equals
    

    boolean equals(Object o)
    

    将指定的对象与此集合进行比较以获得相等性。

    虽然Collection接口不会增加规定向工程总承包为Object.equals，谁落实Collection接口程序员“直接”（换句话说，创建一个类，是Collection，但不是一个Set或List），如果必须小心谨慎，他们选择覆盖Object.equals 。 没有必要这样做，最简单的行动是依靠Object的实现，但实施者可能希望实现“价值比较”来代替默认的“参考比较”。 （ List和Set接口要求这样的价值比较。）
    

    Object.equals方法的一般合同规定，等于必须是对称的（换句话说， a.equals(b)当且仅当b.equals(a) ）。 List.equals和Set.equals的合同规定列表仅等于其他列表，并设置为其他集合。 因此，一个既不实现List也不实现Set接口的集合类的自定义equals方法必须返回false，当该集合与任何列表或集合进行比较时。 （通过相同的逻辑，不可能编写一个正确实现Set和List接口的类。）
    

    

    重写： 
    equals在类别 Object
    参数 
    o - 要与此集合相等的对象进行比较
    结果 
    true如果指定的对象等于此集合
    另请参见： 
    Object.equals(Object) ， Set.equals(Object) ， List.equals(Object)
    • 



    

  • 

    hashCode
    

    int hashCode()
    

    返回此集合的哈希码值。 虽然Collection接口不会增加规定为Object.hashCode方法的常规协定，程序员应该注意的是，它覆盖Object.equals方法也必须重写Object.hashCode方法，以满足为Object.hashCode方法一般合同中的任何类。 特别是c1.equals(c2)意味着c1.hashCode()==c2.hashCode() 。
    

    重写： 
    hashCode在类别 Object
    结果 
    该集合的哈希码值
    另请参见： 
    Object.hashCode() ， Object.equals(Object)
    • 



    

  • 

    spliterator
    

    default Spliterator<E> spliterator()
    

    创建一个Spliterator在这个集合中的元素。 实现应该记录分配器报告的特征值。 如果拼接器报告Spliterator.SIZED并且此集合不包含元素，则不需要报告此类特征值。

    应该通过可以返回更高效的拼接器的子类覆盖默认实现。 为了保持stream()和parallelStream() }方法的预期懒惰行为，分频器应具有IMMUTABLE或CONCURRENT ，或者为late-binding 。 如果这些都不实际，那么首要的类应该是描述绑定者所记录的绑定和结构性干扰的策略，并且应该覆盖stream()和parallelStream()方法以使用Supplier的Supplier创建流，如下所示：
    

       Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics)  
    

    这些要求确保由stream()和parallelStream()方法生成的流将反映终端流操作启动时集合的内容。
    

    

    Specified by: 
    spliterator在界面 Iterable<E>
    实现要求： 
    默认实现从集合的Iterator创建一个late-binding拼接Iterator 。 分割器继承集合的迭代器的故障快速属性。

    创建的Spliterator报告Spliterator.SIZED 。
    

    Implementation Note: 
    创建的Spliterator另外报告Spliterator.SUBSIZED 。

    如果spliterator涵盖任何元素，然后附加特性值的报表，超出的SIZED和SUBSIZED ，不帮助客户控制，专业或简化计算。 但是，这样做可以使空集合能够共享使用一个不变的和空的Spliterator实例（参见Spliterators.emptySpliterator() ），并且允许客户端确定这样一个分割器是否不覆盖任何元素。
    

    结果 
    一个 Spliterator在这个集合中的元素
    从以下版本开始： 
    1.8 
    • 



    

  • 

    stream
    

    default Stream<E> stream()
    

    返回一个顺序Stream与此集合作为其来源。

    当此方法应该重写spliterator()方法不能返回spliterator是IMMUTABLE ， CONCURRENT ，或后期绑定 。 （详见spliterator() ）
    

    

    实现要求： 
    默认的实现创建顺序 Stream从收集的 Spliterator 。
    结果 
    连续 Stream在这个集合中的元素
    从以下版本开始： 
    1.8 
    • 



    

  • 

    parallelStream
    

    default Stream<E> parallelStream()
    

    返回可能并行的Stream与此集合作为其来源。 该方法允许返回顺序流。

    当此方法应该重写spliterator()方法不能返回spliterator是IMMUTABLE ， CONCURRENT ，或后期绑定 。 （详见spliterator() ）
    

    

    实现要求： 
    默认的实现创建了一个平行 Stream从收集的 Spliterator 。
    结果 
    一个可能平行 Stream移到该集合中的元素
    从以下版本开始： 
    1.8 
    • 





 






            

            
posted @ 
2020-03-06 10:37 
厸清扬 
阅读(186) 
评论(0) 
编辑 
收藏 
举报