jdk源码分析之Collection
2016-05-06 23:10
429 查看
package java.util; public interface Collection<E> extends Iterable<E> { // Query Operations /** * Returns the number of elements in this collection. If this collection * contains more than <tt>Integer.MAX_VALUE</tt> elements, returns * <tt>Integer.MAX_VALUE</tt>. * * @return the number of elements in this collection */ //元素的数量 int size(); /** * Returns <tt>true</tt> if this collection contains no elements. * * @return <tt>true</tt> if this collection contains no elements */ //有没有元素 boolean isEmpty(); /** * Returns <tt>true</tt> if this collection contains the specified element. * More formally, returns <tt>true</tt> if and only if this collection * contains at least one element <tt>e</tt> such that * <tt>(o==null ? e==null : o.equals(e))</tt>. * * @param o element whose presence in this collection is to be tested * @return <tt>true</tt> if this collection contains the specified * element * @throws ClassCastException if the type of the specified element * is incompatible with this collection * (<a href="#optional-restrictions">optional</a>) * @throws NullPointerException if the specified element is null and this * collection does not permit null elements * (<a href="#optional-restrictions">optional</a>) */ //检查此元素是否在此集合内 //如果类型与此集合不符抛出ClassCastException //如果此元素是null而且此集合不允许null,则会抛出NullPointerException boolean contains(Object o); /** * Returns an iterator over the elements in this collection. There are no * guarantees concerning the order in which the elements are returned * (unless this collection is an instance of some class that provides a * guarantee). * * @return an <tt>Iterator</tt> over the elements in this collection */ //返回一个迭代器,并不一定要求子类都需要返回有序的。对顺序没有要求 //如果迭代器有顺序,一切顺序以它的顺序为标准 Iterator<E> iterator(); /** * Returns an array containing all of the elements in this collection. * If this collection makes any guarantees as to what order its elements * are returned by its iterator, this method must return the elements in * the same order. * * <p>The returned array will be "safe" in that no references to it are * maintained by this collection. (In other words, this method must * allocate a new array even if this collection is backed by an array). * The caller is thus free to modify the returned array. * * <p>This method acts as bridge between array-based and collection-based * APIs. * * @return an array containing all of the elements in this collection */ //返回一个包含所有元素的数组,如果迭代器是有序的,则此数组顺序与迭代器顺序相同 //colletion和array之间的桥梁,使得colletion类型的对象可以使用array类型的api //要求是安全的,即返回此数组后,此colletion与它就完全没关系了,外界怎么改变此数组都不会影响此colletion Object[] toArray(); /** * Returns an array containing all of the elements in this collection; * the runtime type of the returned array is that of the specified array. * If the collection fits in the specified array, it is returned therein. * Otherwise, a new array is allocated with the runtime type of the * specified array and the size of this collection. * * <p>If this collection fits in the specified array with room to spare * (i.e., the array has more elements than this collection), the element * in the array immediately following the end of the collection is set to * <tt>null</tt>. (This is useful in determining the length of this * collection <i>only</i> if the caller knows that this collection does * not contain any <tt>null</tt> elements.) * * <p>If this collection makes any guarantees as to what order its elements * are returned by its iterator, this method must return the elements in * the same order. * * <p>Like the {@link #toArray()} method, this method acts as bridge between * array-based and collection-based APIs. Further, this method allows * precise control over the runtime type of the output array, and may, * under certain circumstances, be used to save allocation costs. * * <p>Suppose <tt>x</tt> is a collection known to contain only strings. * The following code can be used to dump the collection into a newly * allocated array of <tt>String</tt>: * * <pre> * String[] y = x.toArray(new String[0]);</pre> * * Note that <tt>toArray(new Object[0])</tt> is identical in function to * <tt>toArray()</tt>. * * @param a the array into which the elements of this collection are to be * stored, if it is big enough; otherwise, a new array of the same * runtime type is allocated for this purpose. * @return an array containing all of the elements in this collection * @throws ArrayStoreException if the runtime type of the specified array * is not a supertype of the runtime type of every element in * this collection * @throws NullPointerException if the specified array is null */ // <T> T[] toArray(T[] a); // Modification Operations /** * Ensures that this collection contains the specified element (optional * operation). Returns <tt>true</tt> if this collection changed as a * result of the call. (Returns <tt>false</tt> if this collection does * not permit duplicates and already contains the specified element.)<p> * * Collections that support this operation may place limitations on what * elements may be added to this collection. In particular, some * collections will refuse to add <tt>null</tt> elements, and others will * impose restrictions on the type of elements that may be added. * Collection classes should clearly specify in their documentation any * restrictions on what elements may be added.<p> * * If a collection refuses to add a particular element for any reason * other than that it already contains the element, it <i>must</i> throw * an exception (rather than returning <tt>false</tt>). This preserves * the invariant that a collection always contains the specified element * after this call returns. * * @param e element whose presence in this collection is to be ensured * @return <tt>true</tt> if this collection changed as a result of the * call * @throws UnsupportedOperationException if the <tt>add</tt> operation * is not supported by this collection * @throws ClassCastException if the class of the specified element * prevents it from being added to this collection * @throws NullPointerException if the specified element is null and this * collection does not permit null elements * @throws IllegalArgumentException if some property of the element * prevents it from being added to this collection * @throws IllegalStateException if the element cannot be added at this * time due to insertion restrictions */ //返回true,如果成功插入;返回false,如果此集合不允许重复,且且此元素已经在集合中。 //具体实现时,需要对可以插入什么元素进行限制,如,是否可以插入null,对插入元素的类型进行限制 //如果集合 不是因为重复而拒绝添加一个元素,一定要抛出异常而不是返回false, //UnsupportedOperationException,如果此集合不支持add //ClassCastException,如果元素类型与集合不符合 //NullPointerException,如果插入null且此集合不支持null //IllegalArgumentException,如果此元素中的某些属性使它不能被添加 //IllegalStateException if the element cannot be added at this time //due to insertion restrictions(不知道怎么翻译。。。) boolean add(E e); /** * Removes a single instance of the specified element from 4000 this * collection, if it is present (optional operation). More formally, * removes an element <tt>e</tt> such that * <tt>(o==null ? e==null : o.equals(e))</tt>, if * this collection contains one or more such elements. Returns * <tt>true</tt> if this collection contained the specified element (or * equivalently, if this collection changed as a result of the call). * * @param o element to be removed from this collection, if present * @return <tt>true</tt> if an element was removed as a result of this call * @throws ClassCastException if the type of the specified element * is incompatible with this collection * (<a href="#optional-restrictions">optional</a>) * @throws NullPointerException if the specified element is null and this * collection does not permit null elements * (<a href="#optional-restrictions">optional</a>) * @throws UnsupportedOperationException if the <tt>remove</tt> operation * is not supported by this collection */ //从集合中移除一个元素(对象实例) //移除一个元素e,e满足,如果此集合包含一个或者多个满足此条件 //返回true,如果确实找到满足的元素,并且删除了 //ClassCastException,NullPointerException,UnsupportedOperationException(同上) boolean remove(Object o); // Bulk Operations //大块操作,大部分操作,对整体进行的操作 /** * Returns <tt>true</tt> if this collection contains all of the elements * in the specified collection. * * @param c collection to be checked for containment in this collection * @return <tt>true</tt> if this collection contains all of the elements * in the specified collection * @throws ClassCastException if the types of one or more elements * in the specified collection are incompatible with this * collection * (<a href="#optional-restrictions">optional</a>) * @throws NullPointerException if the specified collection contains one * or more null elements and this collection does not permit null * elements * (<a href="#optional-restrictions">optional</a>), * or if the specified collection is null. * @see #contains(Object) */ //返回true,如果本集合包括传入参数集合中的所有元素 //ClassCastException,如果参数集合中某个或者多个元素不符合类型(可选) //NullPointerException,如果参数集合中包含一个或多个null(可选),或者参数集合为null(必选) boolean containsAll(Collection<?> c); /** * Adds all of the elements in the specified collection to this collection * (optional operation). The behavior of this operation is undefined if * the specified collection is modified while the operation is in progress. * (This implies that the behavior of this call is undefined if the * specified collection is this collection, and this collection is * nonempty.) * * @param c collection containing elements to be added to this collection * @return <tt>true</tt> if this collection changed as a result of the call * @throws UnsupportedOperationException if the <tt>addAll</tt> operation * is not supported by this collection * @throws ClassCastException if the class of an element of the specified * collection prevents it from being added to this collection * @throws NullPointerException if the specified collection contains a * null element and this collection does not permit null elements, * or if the specified collection is null * @throws IllegalArgumentException if some property of an element of the * specified collection prevents it from being added to this * collection * @throws IllegalStateException if not all the elements can be added at * this time due to insertion restrictions * @see #add(Object) */ //将参数集合中的所有元素加入本集合,此行为是不确定的,如果addAll操作时,参数集合也在被修改 //如:如果参数是本身,则结果是不明确的 //UnsupportedOperationException,ClassCastException,NullPointerException //IllegalArgumentException,IllegalStateException(同上) boolean addAll(Collection<? extends E> c); /** * Removes all of this collection's elements that are also contained in the * specified collection (optional operation). After this call returns, * this collection will contain no elements in common with the specified * collection. * * @param c collection containing elements to be removed from this collection * @return <tt>true</tt> if this collection changed as a result of the * call * @throws UnsupportedOperationException if the <tt>removeAll</tt> method * is not supported by this collection * @throws ClassCastException if the types of one or more elements * in this collection are incompatible with the specified * collection * (<a href="#optional-restrictions">optional</a>) * @throws NullPointerException if this collection contains one or more * null elements and the specified collection does not support * null elements * (<a href="#optional-restrictions">optional</a>), * or if the specified collection is null * @see #remove(Object) * @see #contains(Object) */ //移除本集合中所有与参数集合中某元素相同的元素,完成后,本集合将不包含任何与参数集合中某元素相同的集合 //UnsupportedOperationException,ClassCastException,NullPointerException boolean removeAll(Collection<?> c); /** * Retains only the elements in this collection that are contained in the * specified collection (optional operation). In other words, removes from * this collection all of its elements that are not contained in the * specified collection. * * @param c collection containing elements to be retained in this collection * @return <tt>true</tt> if this collection changed as a result of the call * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation * is not supported by this collection * @throws ClassCastException if the types of one or more elements * in this collection are incompatible with the specified * collection * (<a href="#optional-restrictions">optional</a>) * @throws NullPointerException if this collection contains one or more * null elements and the specified collection does not permit null * elements * (<a href="#optional-restrictions">optional</a>), * or if the specified collection is null * @see #remove(Object) * @see #contains(Object) */ //仅保存本集合中与参数集合中某元素相同的元素,或者说,把参数集合中不包含的元素从本集合中除去 //UnsupportedOperationException,ClassCastException,NullPointerException boolean retainAll(Collection<?> c); /** * Removes all of the elements from this collection (optional operation). * The collection will be empty after this method returns. * * @throws UnsupportedOperationException if the <tt>clear</tt> operation * is not supported by this collection */ //清除所有元素,完成后size为0 //UnsupportedOperationException void clear(); // Comparison and hashing //比较和哈希 /** * Compares the specified object with this collection for equality. <p> * * While the <tt>Collection</tt> interface adds no stipulations to the * general contract for the <tt>Object.equals</tt>, programmers who * implement the <tt>Collection</tt> interface "directly" (in other words, * create a class that is a <tt>Collection</tt> but is not a <tt>Set</tt> * or a <tt>List</tt>) must exercise care if they choose to override the * <tt>Object.equals</tt>. It is not necessary to do so, and the simplest * course of action is to rely on <tt>Object</tt>'s implementation, but * the implementor may wish to implement a "value comparison" in place of * the default "reference comparison." (The <tt>List</tt> and * <tt>Set</tt> interfaces mandate such value comparisons.)<p> * * The general contract for the <tt>Object.equals</tt> method states that * equals must be symmetric (in other words, <tt>a.equals(b)</tt> if and * only if <tt>b.equals(a)</tt>). The contracts for <tt>List.equals</tt> * and <tt>Set.equals</tt> state that lists are only equal to other lists, * and sets to other sets. Thus, a custom <tt>equals</tt> method for a * collection class that implements neither the <tt>List</tt> nor * <tt>Set</tt> interface must return <tt>false</tt> when this collection * is compared to any list or set. (By the same logic, it is not possible * to write a class that correctly implements both the <tt>Set</tt> and * <tt>List</tt> interfaces.) * * @param o object to be compared for equality with this collection * @return <tt>true</tt> if the specified object is equal to this * collection * * @see Object#equals(Object) * @see Set#equals(Object) * @see List#equals(Object) */ //比较参数与本集合是否qual //去看看Object#equals(Object),Set#equals(Object),List#equals(Object) //在实现中可以选择去override Object#equals(Object),(不是必要的,最后就用原本的) //如果想要进行value comparison,而不是原本的reference comparison,则需要override(如Set和List) //value comparison,即只要其中包含的元素相同,值相同,即使是不同的引用,也视为相同,返回true boolean equals(Object o); /** * Returns the hash code value for this collection. While the * <tt>Collection</tt> interface adds no stipulations to the general * contract for the <tt>Object.hashCode</tt> method, programmers should * take note that any class that overrides the <tt>Object.equals</tt> * method must also override the <tt>Object.hashCode</tt> method in order * to satisfy the general contract for the <tt>Object.hashCode</tt> method. * In particular, <tt>c1.equals(c2)</tt> implies that * <tt>c1.hashCode()==c2.hashCode()</tt>. * * @return the hash code value for this collection * * @see Object#hashCode() * @see Object#equals(Object) */ //返回本集合的hash code value //与上个方法呼应,override Object.equals的集合类必须也要相应地override Object.hashCode //使得一定保证,若c1.equals(c2),则c1.hashCode()==c2.hashCode() int hashCode(); }
相关文章推荐
- java集合10--HashMap源码走读
- 如何用Java写一个原生wav播放器
- 异常 -- Cause: java.sql.SQLSyntaxErrorException: ORA-00911: 无效字符
- jdk源码分析之AbstractMap
- 《java入门第一季》之面向对象(谈谈接口)
- 《java入门第一季》之面向对象(谈谈接口)
- jdk源码分析之AbstractSet
- 浅谈Spring事务隔离级别
- 浅谈Spring事务隔离级别
- 浅谈Spring事务隔离级别
- 浅谈Spring事务隔离级别
- 浅谈Spring事务隔离级别
- classload之java程序入口sun.misc.Launcher源码分析
- java学习路线
- java的类加载机制
- java从0开始学习第十一课-IO也是非常简单的
- 20145324 Java实验五
- JAVA集合
- 整理 java 分页思路
- 69 个经典 Spring 面试题和答案