Collection
2019-08-12 本文已影响0人
天堂挽歌
package java.util;
import java.util.function.Predicate;
import java.util.stream.Stream;
import java.util.stream.StreamSupport;
/**
* 属于<i>集合层次</i>中的根接口. 一个collection代表了一组数据，并成他们为<i>元素</i>
* 一些的集合允许重复元素而其他的并没有。有的是有序的而其他的是无序的
* JDK没有提供任何基于此接口的<i>直接</i>实现: 它提供很多基于子接口的实现
* 例如<tt>Set</tt> and <tt>List</tt>. 这些集合需要有最大通用性的地方用于
* 传递与操作(其实就是通用性的传递与操作)
*
* <p><i>包装(这里应该指的是容器)</i> or <i>多元集合</i> (未排序的集合可以包含重复的元素)
* 应该直接实现这个接口。
*
* <p>所有通用的<tt>Collection</tt> (他们通常一个子接口间接实现 <tt>Collection</tt>)
* 应该提供两个标准的构造器: 一个空(无参数)构造器，用来创建一个空集合，以
* 及一个只有一个<tt>Collection</tt>参数的构造器, 他将使用他的参数的相同元
* 素创建一个集合，事实上最后一个构造器允许用户复制任意的集合,产生一个与
* 期望的实现类型相同的集合。
* 同时没有强制约束(因为接口不能包含构造器) ，但是在Java平台函数库中，全部的通用<tt>Collection</tt>
* 实现都将遵守。
*
* <p>这个接口中包含"摧毁性的"方法，也就是说，在操作过程中，如果某些
* 方法修改了集合，并接这个集合不支持这个操作，这种"摧毁性的"将抛
* 出<tt>UnsupportedOperationException</tt>。
* 如果调用集合时期望不受影响。在这种情况下，这些方法可以但不是必须
* 要抛出<tt>UnsupportedOperationException</tt>。例如，在不可改变
* 集合中调用{@link #addAll(Collection)} 方法，当添加的集合是空的时候，这
* 个不哭便集合可以但不是必须抛出异常。
*
* <p><a name="optional-restrictions">一些结合实现类可能包含对元素的约束。</a>
* 例如，一些实现会阻止空元素，另一些会限制元素的类型。
* 尝试去添加一个不合格的元素，将会抛出一个未检查一场。典型的
* 如<tt>NullPointerException</tt> 或 <tt>ClassCastException</tt>。
* 尝试去查询一个已经存在的不合格元素，可能会抛出一个异常或简单的返回false;
* 一些实现将展示出前面的行为以及一些后边的行为。
* 普遍性的，在插入操作中，尝试一个基于不合格元素将不会有结果，这
* 次操作有可能抛出异常或也有可能成功。
*
* <p>由每一个集合自己决定同步策略，在实现没有保证时，在其他线程中调用
* 这个集合方法时，将会发生为定义的行为并发生异常; 这包含的直接调用，传
* 递集合到一个可能调用他的方法以及使用已经存在的迭代器进行展示时。
*
* <p>和多方法在集合框架接口中是基于{@link Object#equals(Object) equals}方法
* 的。例如，声明{@link #contains(Object) contains(Object o)}方法。表现为:"只
* 有当这个集合中包含超过一个元素<tt>e</tt>时返回<tt>true</tt>看起来像这
* 样<tt>(o==null ? e==null : o.equals(e))</tt>." 这表明应该<i>不</i>需要去做
* 潜在的分析，当使用一个非空参数<tt>o</tt>，将会造成每一个元素<tt>e</tt>
* 在<tt>o.equals(e)</tt>中被调用。所有的实现可以自由的通过不再调用
* <tt>equals</tt>以达到最优化，例如， 首先比较两个元素的hash code，
* ({@link Object#hashCode()}保证两个对象的唯一hash code不一样) 一
* 般情况下，实现者在实现一个变量集合接口框架可以根据具体的行为去自由
* 的决定，是不是用来底层的{@link Object} 方法。
*
* <p>当递归循环等一些集合操作时，不论是直接或间接的操作，都可能发生异常。这
* 包含{@code clone()}, {@code equals()}, {@code hashCode()} 和 {@code toString()}
* 等方法。具体实现可以选择行的操作自引用，不论怎样，大多数当前的实现都没有这么做。
*
* <p>这个接口是Java集合框架
* <a href="{@docRoot}/../technotes/guides/collections/index.html"></a>的成员。
*
* @implSpec
* 默认方法的实现(继承或非集成)没有任何的同步策略。如果一个{@code Collection}的实现拥有制定的同步协议，那它们必须重写默认的方法以适应同步协议。
*
* @param <E> 在集合中元素的类型
*
* @author Josh Bloch
* @author Neal Gafter
* @see Set
* @see List
* @see Map
* @see SortedSet
* @see SortedMap
* @see HashSet
* @see TreeSet
* @see ArrayList
* @see LinkedList
* @see Vector
* @see Collections
* @see Arrays
* @see AbstractCollection
* @since 1.2
*/
public interface Collection<E> extends Iterable<E> {
// 查询操作(原文为“Query Operations”。)
/**
* 返回当前集合中的元素个数。如果这个集合中包含超
* 过<tt>Integer.MAX_VALUE</tt>个元素，则返回<tt>Integer.MAX_VALUE</tt>.
*
* @return 返回当前集合中的元素个数
*/
int size();
/**
* 当前集合没有包含任何元素时返回<tt>true</tt>。
*
* @return 当钱集合不包含任何元素时返回<tt>true</tt>。
*/
boolean isEmpty();
/**
* 如果当前集合中包含制定的元素则返回<tt>true</tt>。
* 更正式的说，当最少包含一个元素<tt>e</tt>时，返回<tt>true</tt>。
* 像这样<tt>(o==null ? e==null : o.equals(e))</tt>。
*
* @param o 测试这个元素是否存在于这个集合中
* @return 如果这个集合中包含指定的元素则<tt>true</tt>
* @throws ClassCastException 当指定的元素类型与当前集合不兼容时
* (<a href="#optional-restrictions">optional</a>)
* @throws NullPointerException 当指定的元素是null并且这个集合不允许空元素时
* (<a href="#optional-restrictions">optional</a>)
*/
boolean contains(Object o);
/**
* 返回一个覆盖当前集合全部元素的迭代器。它不保证返回元素的顺序。
* (除非这个集合是一些其他提供了这个保证的实例)。
*
* @return 覆盖了当前结合全部元素的<tt>迭代器</tt>
*/
Iterator<E> iterator();
/**
* 返回一个包含了当前集合全部元素的数组。如果这个集合保证它的迭代
* 器的元素顺序是有序的，那这个方法返回的元素必须具有相同的顺序
*
* <p>返回的数组将是“安全”的，这个集合内没有维持这个引用。
* (换据话说，即使这个集合是基于数组的，这个方法也必须返回一个新的数组)。
* 调用这可以自由的去修改返回的数组。
*
* <p>这个方法是链接基于数据与基于集合的桥梁APIs。
*
* @return 一个数组，包含当前集合的全部元素。
*/
Object[] toArray();
/**
* 返回一个包含了当前集合全部对象的数组;
* 返回指定数组的类型作为返回数组的运行时类型。
* 如果指定的数组与集合相符，他将返回到参数之中。
* 其他情况时，一个新的数据将使用给定数组的运行时类型与当前集合的大小所创建。
*
* <p>如果制定数组长度大于当前集合元素数量 (i.e., 这个数组中有元素数量大于
* 当前集合), 设置数组中，当前集合元素的最后一个位置，设置为<tt>null</tt>。
* (在确定了当前集合的长度，这是有用的，<i>只有</i> 如果调用这知道当前集合
* 中不包含任何<tt>null</tt> 元素。)
*
* <p>如果当前集合进行了任何像是如何保证他返回的迭代器是如何排序的，那
* 么这个方法返回的元素也需要有相同的排序。
*
* <p>像是{@link #toArray()}方法，这个方法建立了数组与集合间的APis桥梁。
* 换一种说法，这个方法允许精确的控制返回数组的运行时类型，不论如何，在某些的环境以下，用来节约分配成本。
*
* <p>假定 <tt>x</tt>是一个之包含字符串的集合。下面的代码可以用于将这个集合转存到一个新分配的 <tt>String</tt>数组中去:
*
* <pre>
* String[] y = x.toArray(new String[0]);</pre>
*
* 注意 <tt>toArray(new Object[0])</tt> 与<tt>toArray()</tt>方法是完全相同的。
*
* @param <T> 数组中的集合元素的运行时类型
* @param a 如果这个数组足够储存，集合中的元素将被储存到这个数组中;
* 否则，一个与运行时类型相同的数组进行操作。
* @return 一个包含当前集合全部元素的数组。
* @throws ArrayStoreException 如果当前集合的任意一个元素的超类不是指定数组的运行时类型时
* @throws NullPointerException 如果指定的数组是空的
*/
<T> T[] toArray(T[] a);
// 修改操作(原文: Modification Operations)
/**
* 保证当前集合包含指定元素(可选项)。如果这个集合因本次调用而改变了，则
* 返回<tt>true</tt>。 (如果这个集合不允许重复元素或已经包含了指定的元素
* 时，返回<tt>false</tt> 。)
*
* <p>
* 支持这个操作的集合可能会显示有些元素是否可以被添加到此集合。在特殊
* 情况下，一些集合将会拒绝添加<tt>null</tt> elements，以及其他的将会对
* 添加元素的类型进行限制。
* 集合类应该在他们的文档中明确对添加元素的类型的限制。<p>
*
* 如果一个集合因为任何原因拒绝添加特定的元素，除了它已经包含了这个元素
* 之外，那么它 <i>必须</i>抛出一个异常(我而不是返回<tt>false</tt>)。这保证
* 在本次调用后，一个集合总是包含指定元素的不变性。
*
* @param e 保证这个元素存在与当前集合
* @return 如果调用后集合被改变，则返回<tt>true</tt>
* @throws UnsupportedOperationException 如果当前集合不支持<tt>add</tt>操作
* @throws ClassCastException 添加指定元素到当前集合时，指定元素拒绝转换
* @throws NullPointerException 如果指定元素是null并且当前集合拒绝空元素
* @throws IllegalArgumentException 如果元素的属性拒绝添加到当前集合
* @throws IllegalStateException 由于插入显示导致元素不能被添加
*/
boolean add(E e);
/**
* 通过指定元素删除当前集合中的单个实例，(如果它存在的话)。更正式讲，如
* 果当前集合中包含一个或多个匹配的元素，使
* 用<tt>(o==null ? e==null : o.equals(e))</tt>的方式删
* 除元素<tt>e</tt>。如果集合中包含指定的元素时返回<tt>true</tt>(或者等价，或
* 调用完成后当前集合以改变)。
*
* @param o 当前集合中存在这个元素的话，将会被删除
* @return 如果本次调用完成后，元素被删除，则返回<tt>true</tt>
* @throws ClassCastException 如果制定的元素与当前集合不兼容
* (<a href="#optional-restrictions">optional</a>)
* @throws NullPointerException 如果制定元素是空兵器集合不允许空元素
* (<a href="#optional-restrictions">optional</a>)
* @throws UnsupportedOperationException 如果当前集合不支持<tt>remove</tt>操作
*/
boolean remove(Object o);
// 扩展操作(原文: Bulk Operations)
/**
* 如果当前集合包含全部来自指定集合时，返回<tt>true</tt>。
*
* @param c 用于检查当前集合中是否包含此集合
* @return 如果当前集合中包含全部参数集合中的元素，则返回<tt>true</tt>
* @throws ClassCastException 如果指定集合中的一个或多个集合与当前集合中的类型不兼容
* (<a href="#optional-restrictions">optional</a>)
* @throws NullPointerException 如果指定集合中包含一个或多个空元素并且当
* 前集合不允许空元素或者指定集合是空的
* (<a href="#optional-restrictions">optional</a>),
* or if the specified collection is null.
* @see #contains(Object)
*/
boolean containsAll(Collection<?> c);
/**
* 添加指定集合中的全部元素到当前集合中(可选操作)。在操作执行
* 期间，对指定集合进行修改的操作时为定义的。(这意味着，如果
* 指定集合就是当前集合并且当前集合是非空的，这个嗲用行为也是为定义的。)
*
* @param c 这个集合包含的元素将被添加到当前集合
* @return 如果调用后集合发生改变，则返回<tt>true</tt>
* @throws UnsupportedOperationException 如果当前集合不支持<tt>addAll</tt>操作
* @throws ClassCastException 如果当前集合拒绝添加指定集合中的元素的类型
* @throws NullPointerException 如果指定的集合中包含了空元素并且当前集合不
* 支持空元素或者指定元素是空的
* @throws IllegalArgumentException 如果指定集合中的元素的某些属性阻止添加到当前集合
* @throws IllegalStateException 由于插入限制，无法添加全部元素
* @see #add(Object)
*/
boolean addAll(Collection<? extends E> c);
/**
* 删除当前集合中，同时存在于当前集合与指定集合中的元素(可选)。在调用完
* 成后，当前集合中将不包含指定集合中的元素。
*
* @param c 这个集合包含的元素将从当前集合中移除
* @return <tt>true</tt> 如果调用后集合发生改变，则返回<tt>true</tt>
* @throws UnsupportedOperationException 如果当前方案不支持<tt>removeAll</tt>操作
* @throws ClassCastException 如果指定元素中的一个或多个元素的类型与当前元素不兼容
* (<a href="#optional-restrictions">optional</a>)
* @throws NullPointerException 如果当前集合包含一个或多个元素并且指定集合不支持空元素
* (<a href="#optional-restrictions">optional</a>),
* 或者指定的元素是空的
* @see #remove(Object)
* @see #contains(Object)
*/
boolean removeAll(Collection<?> c);
/**
* 删除所有满足指定断言的元素。错误或运行时异常抛出会在迭代或断言传播到调用者。
*
* @implSpec
* 默认实现通过使用{@link #iterator}遍历全部元素。每一个匹配的的元素都将使
* 用 {@link Iterator#remove()}进行删除。如果集合的迭代其不支持删除，那将会在第一
* 次匹配时抛出 {@code UnsupportedOperationException} 。
*
* @param filter 过滤断言，当返回 {@code true}时，对应的元素将被删除
* @return 有任何元素被删除，将返回{@code true}
* @throws NullPointerException 如果filter是空的
* @throws UnsupportedOperationException 如果元素不能从当前元素中删除。当实现
* 无法删除元需或删除操作不被支持时，可能抛出异常。
* @since 1.8
*/
default boolean removeIf(Predicate<? super E> filter) {
Objects.requireNonNull(filter);
boolean removed = false;
final Iterator<E> each = iterator();
while (each.hasNext()) {
if (filter.test(each.next())) {
each.remove();
removed = true;
}
}
return removed;
}
/**
* 只保留指定集合中拥有的元素(可选). 换句话说，删除指定集合中的元素以外的前全部元素。
*
* @param c 当前集合中与此参数中相同的元素将被保留
* @return 调用后当前集合被改变则返回<tt>true</tt>
* @throws UnsupportedOperationException 如果<tt>retainAll</tt>操作不被支持
* @throws ClassCastException 如果指定集合中的一个或多个元素与当前元素类型不兼容
* (<a href="#optional-restrictions">optional</a>)
* @throws NullPointerException 如果当前集合包含一个或多个空元素并且指定集合中不允许空元素
* (<a href="#optional-restrictions">optional</a>),
* 或者制定集合是空的
* @see #remove(Object)
* @see #contains(Object)
*/
boolean retainAll(Collection<?> c);
/**
* 删除集合中的全部元素(可选)，方法返回之后，这个集合将是空的
*
* @throws UnsupportedOperationException 如果这个集合不支持<tt>clear</tt>操作
*/
void clear();
// 比较与hash(原文: Comparison and hashing)
/**
* 比较指定的对象与当前集合是否相同。 <p>
*
* <tt>Collection</tt>接口中添加了未实现的<tt>Object.equals</tt>方法,开发者
* 们在“直接”实现<tt>Collection</tt>接（换句话说，创建一个 <tt>Collection</tt>类，
* 但不是<tt>Set</tt>或<tt>List</tt>）口时，必须小心谨慎的去重写<tt>Object.equals</tt>。
* 这不是必须去做的，可以简单的依赖<tt>Object</tt>去实现这个动作，但是实现者
* 可能希望实现使用“值比较”去替换默认的“引用比较”。（<tt>List</tt>和<tt>Set</tt>接
* 口要求注入值比较。）
*
* 一般情况下，<tt>Object.equals</tt>方法所表现的相等是有具有对称性
* 的（换句话说，<tt>a.equals(b)</tt>并且<tt>b.equals(a)</tt>），这表
* 明<tt>List.equals</tt> 和 <tt>Set.equals</tt>只能出现list与其他list相等的
* 情况以及set与其他set。因此，集合的实现中，自定义的<tt>equals</tt>
* 方法比较List与Set时，必须返回false。
*
* @param o 用于与当前集合比较是否相同的一个对象
* @return 当指定对象与当前集合相同是，返回<tt>true</tt>
*
* @see Object#equals(Object)
* @see Set#equals(Object)
* @see List#equals(Object)
*/
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)
*/
int hashCode();
/**
* 创建一个包含当前集合全部元素的{@link Spliterator}
*
* Implementations should document characteristic values reported by the
* spliterator. Such characteristic values are not required to be reported
* if the spliterator reports {@link Spliterator#SIZED} and this collection
* contains no elements.
*
* <p>The default implementation should be overridden by subclasses that
* can return a more efficient spliterator. In order to
* preserve expected laziness behavior for the {@link #stream()} and
* {@link #parallelStream()}} methods, spliterators should either have the
* characteristic of {@code IMMUTABLE} or {@code CONCURRENT}, or be
* <em><a href="Spliterator.html#binding">late-binding</a></em>.
* If none of these is practical, the overriding class should describe the
* spliterator's documented policy of binding and structural interference,
* and should override the {@link #stream()} and {@link #parallelStream()}
* methods to create streams using a {@code Supplier} of the spliterator,
* as in:
* <pre>{@code
* Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics)
* }</pre>
* <p>These requirements ensure that streams produced by the
* {@link #stream()} and {@link #parallelStream()} methods will reflect the
* contents of the collection as of initiation of the terminal stream
* operation.
*
* @implSpec
* The default implementation creates a
* <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
* from the collections's {@code Iterator}. The spliterator inherits the
* <em>fail-fast</em> properties of the collection's iterator.
* <p>
* The created {@code Spliterator} reports {@link Spliterator#SIZED}.
*
* @implNote
* The created {@code Spliterator} additionally reports
* {@link Spliterator#SUBSIZED}.
*
* <p>If a spliterator covers no elements then the reporting of additional
* characteristic values, beyond that of {@code SIZED} and {@code SUBSIZED},
* does not aid clients to control, specialize or simplify computation.
* However, this does enable shared use of an immutable and empty
* spliterator instance (see {@link Spliterators#emptySpliterator()}) for
* empty collections, and enables clients to determine if such a spliterator
* covers no elements.
*
* @return a {@code Spliterator} over the elements in this collection
* @since 1.8
*/
@Override
default Spliterator<E> spliterator() {
return Spliterators.spliterator(this, 0);
}
/**
* Returns a sequential {@code Stream} with this collection as its source.
*
* <p>This method should be overridden when the {@link #spliterator()}
* method cannot return a spliterator that is {@code IMMUTABLE},
* {@code CONCURRENT}, or <em>late-binding</em>. (See {@link #spliterator()}
* for details.)
*
* @implSpec
* The default implementation creates a sequential {@code Stream} from the
* collection's {@code Spliterator}.
*
* @return a sequential {@code Stream} over the elements in this collection
* @since 1.8
*/
default Stream<E> stream() {
return StreamSupport.stream(spliterator(), false);
}
/**
* Returns a possibly parallel {@code Stream} with this collection as its
* source. It is allowable for this method to return a sequential stream.
*
* <p>This method should be overridden when the {@link #spliterator()}
* method cannot return a spliterator that is {@code IMMUTABLE},
* {@code CONCURRENT}, or <em>late-binding</em>. (See {@link #spliterator()}
* for details.)
*
* @implSpec
* The default implementation creates a parallel {@code Stream} from the
* collection's {@code Spliterator}.
*
* @return a possibly parallel {@code Stream} over the elements in this
* collection
* @since 1.8
*/
default Stream<E> parallelStream() {
return StreamSupport.stream(spliterator(), true);
}
}
