Java 进阶 -- 流

Java I/O, NIO, and NIO.2

BaseStream> 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

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

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
	}
}