Java源码解析 Collection<E>

位置:  java.util.Collection<E>

interface

用途:

参数:<E>

Iterable<E>

子类:

接口:

方法

     int  size();

    返回这个集合中的元素个数，返回为Integer类型， 如果这个集合中的元素个数大于 Integer.MAX_VALUE 那么，就返回 Integer.MAX_VALUE

param:

return:

exception：

     boolean  isEmpty();

    返回 true 如果这个集合里面没有元素

param:

return:

exception：

     boolean  contains(Object o);

    返回 true 如果这个集合中包含特定的元素。更准确的说，返回true 当且仅当集合中存在元素 “e”,满足条 件 (o==null ? e==null : o.equals(e)) .

param: Object o

return:true/false

    ClassCastException      如果指定元素的类型与此collection不兼容

               NullPointerException      如果指定的元素为null，并且此collection不允许null元素

     Iterator<E> iterator();

    返回一个迭代器，不考虑这个迭代器中元素的顺序问题（除非这个集合的一些实现类保证顺序）

param:

return:      Iterator

exception：

     Object[] toArray();

    返回一个数组，里面包含所有集合中的元素，如果集合返回的迭代器中元素的顺序是一定的，那么数组里面返回的元素的顺序应该和迭代器中的一致。

返回的数组与集合的关系是独立的，换句话说，这个方法返回的数组是新建的一个数组，调用者可以随意修改这个数组。

这个方法扮演一个“桥”的角色，在array-based 和collection-based 之间

param:

return:   Object[]

exception：

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

    返回一个数组，包含集合中所有的元素；返回数组的运行时类型是指定数组的。如果集合指定的数组能容纳，则在其中返回。否则，会新建一个数组类型为指定数组类型，长度是该集合的长度

param:

return:

exception：

     boolean  add(E e);

    确保这个Collection 里面包含指定的元素（可选操作）。返回true,如果通过调用collection的结果发生改变.

（返回false，如果这个collection不允许重复记录并且这个集合中已经包含这个需要添加的指定的元素）

collection 支持这个操作需要做限制，哪些元素类型可以添加到这个collection里。特别的，有些collections拒绝添加null元素，而有些明确的限制约束将要添加到集合中元素的类型。集合类需要在文档中明确指出需要添加元素的类型。

如果一个集合拒绝添加一个特定的元素，而不是因为集合中已经包含这个元素的其他原因，那么必须需要抛出异常(比返回false强)。结果是不变的，如下：当调用过这个方法后，这个collection中一定包含这个元素。

param:      E元素存在于此集合要保证

return:      返回true,如果通过调用collection的结果发生改变.

     UnsupportedOperationException      如果这个集合不支持这个操作

     ClassCastExceptio      如果类指定的元素不允许将其添加到此集合     

     NullPointerException    如果这个元素是null 并且 这个集合不允许null 元素

     IllegalArgumentException      如果元素的某些属性不允许将其添加到此集合

     IllegalStateException      如果元素不能在这个时候加入，由于插入限制     

     boolean  remove(Object o);

    从这个集合中移除指定元素的单个实例，如果存在。更正式的，移除元素e，如果collection中存在一个或者多个元素这样的元素满足 (o==null ? e==null : o.equals(e)) 如果此collection包含指定的元素（或者，如果此collection由于调用而更改的结果），则返回true。

param:     o  - 元素从这个集合中删除（如果存在）

return:          返回true 如果由于调用 出现元素被移除了的结果

ClassCastException  如果指定元素的类型与此collection不兼容

NullPointerException

UnsupportedOperationException 如果这个集合不支持remove 这个方法

       boolean  containsAll(Collection<?> c);

    返回true 如果这个集合中包含指定集合中的所有的元素

param:     c 集合在此几个中被检查是否包含

return:      返回true 如果这个集合中包含指定集合中的所有的元素

ClassCastException 如果指定集合中的一个或者多个元素的类型与此collection不兼容

NullPointerException 如果指定集合中包含一个或者多个null 元素，但是此collection不允许null 元素 

     boolean  addAll(Collection<?  extends  E> c);

    添加所有指定集合中的元素此collection中（可选操作）。此操作的行为是不确定的，如果指定的集合被修改，在执行这个方法操作过程中。这意味着，此调用的行为是不确定的，如果指定的集合是这样的集合，这个集合非空。

param:c -collection 包含将要被添加的所有元素的集合

return:     返回true如果此collection 由于调用而改变的结果

     UnsupportedOperationException 如果这个addAll操作在这个集合中不支持

ClassCastException

NullPointerException 如果指定集合中包含null元但是此collection不允许null元素，或者指定的集合就是null 

     boolean removeAll(Collection<?> c);

    移除掉所有这个集合中和指定集合中共有的元素（可选操作），这个方法return之后，这个集合中就没有和指定集合中相共有的元素了。

param:  参数c集合中包含将要在这个集合中要移除的元素

return:     返回true 如果此collection 由于调用而更改的结果

     UnsupportedOperationException 如果这个removeAll操作在这个集合中不支持的话

ClassCastException 如果集合中存在一个或者多个元素与指定集合的类型不匹配（可选）

NullPointerException 如果集合中存在一个或者多个null元素,但是和指定集合中不允许有null元素，或者指定的集合是null

     boolean retainAll(Collection<?> c);

    只保留集合中仅有的在指定集合中的元素（可选操作），换句话说，remove掉所有集合中的那些指定集合中没有的元素

param:     c 集合中将要保留元素的指定集合

return:     返回true  如果此collection由于调用而更改的结果

UnsupportedOperationException  如果这个retainAll操作在这个集合中不支持的话，会抛这个异常    

ClassCastException 如果集合中存在一个或者多个元素与指定集合的类型不匹配（可选）

NullPointerException 如果集合中存在一个或者多个null元素,但是和指定集合中不允许有null元素，或者指定的集合是null  

     void  clear();

    移除集合中的所有元素（可选操作），这个方法执行后，集合是empty的

param:

return:

UnsupportedOperationException 如果这个clear操作在这个集合中不支持的话，会抛这个异常

     boolean  equals(Object o);

    比较指定对象是否和此collection相等

Collection中没有增加规定，拿过来Object.Equals. 程序员直接实现Collection要非常小心，如果选择重写Object.equals.(换句话说，创建一个类是Collection，而不是List或者Set). 这是没有必要的话，最简单的动作，当然是依靠对象的实现，但实现者可能希望实现代替默认的“值比较”，“参考比较。”（该List和Set接口的任务，例如值比较。）

Object.equals方法 通常的约定的约定是等于必须是对称的。（换句话说，a.equals(b) 当且仅当b.equals(b)）. List.equals和Set.equals 的约定声明是lists 仅仅等于另一个lists, sets也是一样。因此，一个collection类中的自定义equals方法既不实现List也不实现Set接口那么一定要返回false 当这个collection与任何list或者set比较的话。（按照同样的逻辑，不可能写出一个类同时实现Set和List接口）

overrides:     Object中的equals方法

param:     o 对象，将要和这个collection比较的对象

return:     返回true 如果这个collection等于指定的对象

exception：

     int  hashCode();

    返回此collection的哈希值。Collection接口不会对通用约定的Object.hashCode方法增加规定，实现人员需要注意任何类如果重写了Object.equals方法必须也要重写Object.hashCode方法，以适应通用约定的Object.hashCode方法。特别一点，c1.equals(c2) 意味着c1.hashCode() = c2.hashCode()

overrides:     Object中的hashCode方法

param:

return:      返回此collection的哈希值。

exception：