Java8 Collection接口API翻译

compact1, compact2, compact3

java.util

Interface Collection

• 类型参数:

  E -此集合中的元素的类型

  所有超级接口：

  Iterable

  所有已知子接口

  BeanContext, BeanContextServices, BlockingDeque, BlockingQueue, Deque, List, NavigableSet, Queue,Set, SortedSet, TransferQueue

  所有已知实现类：

  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
extends Iterable

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

包（bag）或多集合（可能包含重复元素的无序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 方法的指定行为，而不管实现程序认为它是否合适。

执行递归遍历集合的一些集合操作可能会失败，而自引用实例的异常会导致集合直接或间接包含其自身。 这包括clone()，equals()，hashCode()和toString()方法。 实现可以可选地处理自引用场景，然而大多数当前实现不这样做。

此接口是Java集合框架的成员。

实现要求：

       默认方法实现（继承或其他）不应用任何同步协议。 如果Collection的实现具有特定的同步协议，则必须覆盖默认实现以应用该协议。

从以下版本开始：

1.2

另请参见：

Set, List, Map, SortedSet, SortedMap, HashSet, TreeSet, ArrayList, LinkedList, Vector, Collections, Arrays,AbstractCollection

方法摘要

• All MethodsInstance MethodsAbstract MethodsDefault Methods

  修饰符和类型	方法和说明
  boolean	add(E e) 确保此 collection 包含指定的元素（可选操作）。
  boolean	addAll(Collection E> c) 将指定 collection 中的所有元素都添加到此 collection 中（可选操作）。
  void	clear() 移除此 collection 中的所有元素（可选操作）。
  boolean	contains(Object o) 如果此 collection 包含指定的元素，则返回 true。
  boolean	containsAll(Collection c) 如果此 collection 包含指定 collection 中的所有元素，则返回 true。
  boolean	equals(Object o) 比较此 collection 与指定对象是否相等。
  int	hashCode() 返回此 collection 的哈希码值。
  boolean	isEmpty() 如果此 collection 不包含元素，则返回 true。
  Iterator<E>	iterator() 返回在此 collection 的元素上进行迭代的迭代器。
  default Stream<E>	parallelStream() 返回一个可能并行的Stream，该集合作为其源。
  boolean	remove(Object o) 从此 collection 中移除指定元素的单个实例，如果存在的话（可选操作）。
  boolean	removeAll(Collection c) 移除此 collection 中那些也包含在指定 collection 中的所有元素（可选操作）。
  default boolean	removeIf(PredicateE> filter) 删除满足给定谓词的此集合的所有元素。
  boolean	retainAll(Collection c) 仅保留此 collection 中那些也包含在指定 collection 的元素（可选操作）。
  int	size() 返回此 collection 中的元素数。
  default Spliterator<E>	spliterator() 在此集合中的元素上创建一个Spliterator。
  default Stream<E>	stream() 返回一个以此集合为依据的顺序流。
  Object[]	toArray() 返回包含此 collection 中所有元素的数组。
  T[]	toArray(T[] a) 返回包含此 collection 中所有元素的数组；返回数组的运行时类型与指定数组的运行时类型相同。

  
  

  • 从java.lang.Iterable接口继承的方法:

                     forEach

• • 方法详细信息

    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 是某个能提供保证顺序的类实例）。

    指定者：

    接口 Iterable<E> 中的 iterator

    返回：

    在此 collection 的元素上进行迭代的 Iterator

    ---

    toArray

    Object[] toArray()

    返回包含此 collection 中所有元素的数组。如果 collection 对其迭代器返回的元素顺序做出了某些保证，那么此方法必须以相同的顺序返回这些元素。

    返回的数组将是“安全的”，因为此 collection 并不维护对返回数组的任何引用。（换句话说，即使 collection 受到数组的支持，此方法也必须分配一个新的数组）。因此，调用者可以随意修改返回的数组。

    此方法充当了基于数组的 API 与基于 collection 的 API 之间的桥梁。

    返回：

    包含此 collection 中所有元素的数组

    ---

    toArray

     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(CollectionE> 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)

    
    

    
    

    • removeIf

      default boolean removeIf(PredicateE> filter)

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

                    实现要求： 

                            默认实现使用iterator()遍历集合的所有元素。 使用Iterator.remove()删除每个匹配元素。 如果集合的迭代器不支持删除，那么将在第一个匹配元素上                                           抛出一个UnsupportedOperationException。 

                    参数： 

                            filter - 对要删除的元素返回true的谓词 

                    返回：

                            如果删除任何元素，则为true 

                    抛出： 

                            NullPointerException - 如果指定的过滤器为空 

                            UnsupportedOperationException - 如果元素无法从此集合中删除。 如果不能删除匹配的元素，或者一般来说，不支持删除，则实现可能会抛出此异常。 

                    从以下版本开始：

                            1.8

• • retainAll

• 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 接口的类。）

  覆盖：

  类 Object 中的 equals

  参数：

  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()。

  覆盖：

  类 Object 中的 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 s = StreamSupport.stream(()-> spliterator()，spliteratorCharacteristics)

     

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

    指定者：

                接口Iterable 中的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

  • parallelStream

    default Stream<E> parallelStream()

    返回一个可能并行的流，该集合作为其源头。 该方法允许返回顺序流。

    当spliterator()方法不能返回IMMUTABLE，CONCURRENT或后期绑定的spliterator时，应该覆盖此方法。 （有关详细信息，请参阅spliterator（））

    实现要求：

            默认实现从集合的Spliterator创建一个并行流。

    返回：

            这个集合中的元素可能是并行的Stream

    从以下版本开始：

            1.8

从API文档中可以看到，Java8 Collection接口新增了以下方法：

1. default boolean removeIf(Predicate filter)
   
2. default Spliterator spliterator()
   
3. default Stream stream()
   
4. default Stream parallelStream()
   

这几个新增的方法牵涉到以下几个接口/方法：

1. Interface Predicate
   
2. Interface Spliterator
   
3. Interface Stream
   

关于这些接口的API和用法，请看：http://docs.oracle.com/javase/8/docs/api/index.html

来源： http://docs.oracle.com/javase/8/docs/api/java/util/Collection.html