Java I/O, NIO, and NIO.2

BaseStream<T, S extends BaseStream<T, S>> extends AutoCloseable

流(streams)的基本接口，流是支持顺序和并行聚合操作的元素序列。下面的例子演示了一个使用流类型stream和IntStream的聚合操作，计算红色小部件的权重之和:

  int sum = widgets.stream().filter(w -> w.getColor() == RED).mapToInt(w -> w.getWeight()).sum();

请参阅Stream的类文档和java.util.stream的包文档，了解有关流、流操作、流管道和并行性的其他规范，这些规范管理所有流类型的行为。

public interface BaseStream<T, S extends BaseStream<T, S>> extends AutoCloseable {// 返回此流元素的迭代器。// 这是一个最终操作。Iterator<T> iterator();// 返回此流元素的 spliterator。Spliterator<T> spliterator();// 如果要执行最终操作，返回此流是否并行执行。在调用最终流操作方法后调用此方法可能会// 产生不可预测的结果。boolean isParallel();// 返回等效的顺序流。可能返回自身，因为流已经是顺序的，或者因为底层流状态被修改为顺序的。// 这是一个中间操作。S sequential();S parallel();S unordered();// 返回具有附加关闭处理程序的等效流。关闭处理程序在流上调用Close()方法时运行，并按照添加的顺序执行。// 所有关闭处理程序都将运行，即使先前的关闭处理程序抛出异常。如果任何close处理程序抛出异常，则抛出的第// 一个异常将被传递给close()的调用者，剩余的任何异常都将作为抑制异常添加到该异常中(除非剩余异常中的一// 个与第一个异常相同，因为异常无法抑制自身)。可以返回自己。S onClose(Runnable closeHandler);void close();
}

AutoCloseable

一个对象，它可以保存资源(如文件句柄或套接字句柄)，直到它被关闭。AutoCloseable对象的close()方法在退出一个在资源规范头文件中声明了该对象的try-with-resources块时自动调用。这种构造确保了及时释放，避免了资源耗尽异常和可能发生的错误。

public interface AutoCloseable {// 关闭此资源，放弃所有底层资源。此方法在由try-with-resources语句管理的对象上自动调用。void close() throws Exception;
}

Stream<T>

public interface Stream<T> extends BaseStream<T, Stream<T>> {// 返回由此流中与给定谓词匹配的元素组成的流。// 这是一个中间操作。Stream<T> filter(Predicate<? super T> predicate);// 返回由将给定函数应用于此流的元素的结果组成的流。// 这是一个中间操作。<R> Stream<R> map(Function<? super T, ? extends R> mapper);// 返回一个IntStream，由将给定函数应用于此流的元素的结果组成。// 这是一个中间操作。IntStream mapToInt(ToIntFunction<? super T> mapper);LongStream mapToLong(ToLongFunction<? super T> mapper);DoubleStream mapToDouble(ToDoubleFunction<? super T> mapper);// 返回一个流，其中包含将此流的每个元素替换为通过对每个元// 素应用所提供的映射函数生成的映射流的内容的结果。每个映// 射流在其内容被放入该流之后是{@link // java.util.stream.BaseStream#close()} 关闭。(如果// 映射流是{@code null}，则使用空流。)// 这是一个中间操作。// {@code flatMap()}操作的效果是对流中的元素应用一对多// 转换，然后将生成的元素扁平化到一个新的流中。<R> Stream<R> flatMap(Function<? super T, ? extends Stream<? extends R>> mapper);IntStream flatMapToInt(Function<? super T, ? extends IntStream> mapper);LongStream flatMapToLong(Function<? super T, ? extends LongStream> mapper);DoubleStream flatMapToDouble(Function<? super T, ? extends DoubleStream> mapper);// 返回由该流的不同元素组成的流(根据Object.equals(Object))。// 对于有序流，不同元素的选择是稳定的(对于重复元素，保留// 在遇到顺序中首先出现的元素)。对于无序流，没有稳定性保证。// 这是一个有状态的中间操作。Stream<T> distinct();// 返回由此流的元素组成的流，按自然顺序排序。如果此流的元// 素不具有可比性，则在执行终端操作时可能会抛出java.lang.ClassCastException。// 对于有序流，排序是稳定的。对于无序流，没有稳定性保证。// 这是一个有状态的中间操作。Stream<T> sorted();// 返回由此流的元素组成的流，根据提供的比较器排序。Stream<T> sorted(Comparator<? super T> comparator);// 返回由此流的元素组成的流，并在从结果流中消费元素时对每// 个元素执行所提供的操作。// 这是一个中间操作。Stream<T> peek(Consumer<? super T> action);// 返回一个元素为指定值的有序流。public static<T> Stream<T> of(T... values) {return Arrays.stream(values);}// 使用提供的恒等值和关联累加函数对该流的元素执行约简，并// 返回约简后的值。这相当于:T result = identity;for (T element : this stream)result = accumulator.apply(result, element)return result;// 但不受顺序执行的约束。// 恒等值必须是累加器函数的标识。这意味着对于所有t，// accumulator.apply(identity, t)与t相等。累加器函数必须是关联函数。// 这是一个最终操作。T reduce(T identity, BinaryOperator<T> accumulator);// 对该流的元素执行可变归纳操作。可变归纳是指被归纳简后的值// 是一个可变的结果容器，如ArrayList，通过更新结果的状态// 而不是替换结果来合并元素。这产生的结果相当于:R result = supplier.get();   for (T element : this stream)accumulator.accept(result, element);   return result;// 与`reduce(Object, BinaryOperator)`类似，collect操作可以// 并行化，而不需要额外的同步。// 这是一个最终操作。<R> R collect(Supplier<R> supplier,BiConsumer<R, ? super T> accumulator,BiConsumer<R, R> combiner);// 使用Collector对此流的元素执行可变归纳操作。Collector封装// 了用作collect(Supplier, BiConsumer, BiConsumer)参数的函数，// 允许重用收集策略和组合收集操作(如多级分组或分区)。//如果流是并行的，而收集器是并发的，并且流是无序的，或者// 收集器是无序的，那么将执行并发归纳(有关并发归纳的详细// 信息，请参阅Collector)。// 这是一个最终操作。<R, A> R collect(Collector<? super T, A, R> collector);
}

IntStream

public interface IntStream extends BaseStream<Integer, IntStream> {// 返回一个OptionalDouble，描述此流中元素的算术平均值，如果此流为空，// 则返回一个空可选值。这是约简的一个特例。// 这是一个最终操作。OptionalDouble average();// 返回此流中元素的总和。这是一个简化的特殊情况，相当于:// return reduce(0, Integer::sum);int sum();
}

OptionalDouble

可以包含也可以不包含双精度(double)值的容器对象。如果存在一个值，isPresent()将返回true, getAsDouble()将返回该值。

提供了依赖于包含值是否存在的其他方法，例如orElse()(如果值不存在则返回默认值)和ifPresent()(如果值存在则执行代码块)。

这是一个基于值的类;在OptionalDouble实例上使用标识敏感操作(包括引用相等(==)、身份哈希码或同步)可能会产生不可预测的结果，应该避免。

public final class OptionalDouble {}

Collectors

Collector的实现，实现各种有用的归纳操作，例如将元素累积到集合中，根据各种标准汇总元素等。

public final class Collectors {// 通过在累加前对每个输入元素应用映射函数，将一个接受U类// 型元素的Collector适配为一个接受T类型元素的Collector。Collector<T, ?, R> mapping(Function<? super T, ? extends U> mapper,Collector<? super U, A, R> downstream) {}// 返回一个Collector，在指定的mapping函数和BinaryOperator// 下对其输入元素进行约简。这是reducing(Object, BinaryOperator) 的泛化，// 它允许在reduce之前对元素进行转换。public static <T, U>Collector<T, ?, U> reducing(U identity,Function<? super T, ? extends U> mapper,BinaryOperator<U> op){}// 返回一个Collector，该Collector使用提供的标识在指定的// BinaryOperator下执行输入元素的约简。public static <T> Collector<T, ?, T>reducing(T identity, BinaryOperator<T> op) {}// 返回一个Collector，该Collector对类型为T的输入元素执// 行级联“group by”操作，根据分类函数对元素进行分组，然// 后使用指定的下游Collector对与给定键相关的值执行归纳操// 作。Collector 生成的 Map 是用提供的工厂函数创建的。// 分类函数将元素映射到某个键类型K。下游收集器对类型T的元// 素进行操作，并产生类型D的结果。结果收集器生成一个Map。public static <T, K, D, A, M extends Map<K, D>>Collector<T, ?, M> groupingBy(Function<? super T, ? extends K> classifier,Supplier<M> mapFactory,Collector<? super T, A, D> downstream) {}public static <T, K> Collector<T, ?, Map<K, List<T>>>      groupingBy(Function<? super T, ? extends K> classifier) {}public static <T, K, A, D>Collector<T, ?, Map<K, D>> groupingBy(Function<? super T, ? extends K> classifier,Collector<? super T, A, D> downstream) {}}

Collector<T, A, R>

public interface Collector<T, A, R> {// 创建并返回一个新的可变结果容器的函数。Supplier<A> supplier();// 将值折叠到可变结果容器中的函数。BiConsumer<A, T> accumulator();// 一个接受两个部分结果并合并它们的函数。组合函数可以将一// 个参数的状态折叠到另一个参数中并返回，也可以返回一个新// 的结果容器。BinaryOperator<A> combiner();// 执行从中间累积类型A到最终结果类型R的最终转换。Function<A, R> finisher();// 返回Collector.Characteristics 的Set 表明此收集器的特性。// 这个集合应该是不可变的。Set<Characteristics> characteristics();// 指示收集器属性的特征，可用于优化归纳实现。enum Characteristics {// 指示此收集器是并发的，这意味着结果容器可以支持从多// 个线程并发地使用相同的结果容器调用累加器函数。// 如果CONCURRENT collector也不是UNORDERED的，那么只有// 在应用于无序数据源时才应该并发地对其进行评估。CONCURRENT,// 指示集合操作不承诺保留输入元素的相遇顺序。(如果结// 果容器没有内在顺序，例如Set，则可能是这样。)UNORDERED,// 表示结束函数是恒等函数，可以省略。如果设置，则从A// 到R的未检查强制转换必须成功。IDENTITY_FINISH}
}