8008682: Inital Streams public API

Reviewed-by: mduigou, dholmes, darcy
Contributed-by: NBrian Goetz &lt;brian.goetz@oracle.com&gt;, Mike Duigou &lt;mike.duigou@oracle.com&gt;, Paul Sandoz &lt;paul.sandoz@oracle.com&gt;, JSR-335 EG <lambda-libs-spec-experts@openjdk.java.net>

src/share/classes/java/util/stream/BaseStream.java

+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.util.stream;
+
+import java.util.Iterator;
+import java.util.Spliterator;
+
+/**
+ * Base interface for stream types such as {@link Stream}, {@link IntStream},
+ * etc.  Contains methods common to all stream types.  Many of these methods
+ * are implemented by {@link AbstractPipeline}, even though
+ * {@code AbstractPipeline} does not directly implement {@code BaseStream}.
+ *
+ * @param <T> type of stream elements
+ * @param <S> type of stream implementing {@code BaseStream}
+ * @since 1.8
+ */
+interface BaseStream<T, S extends BaseStream<T, S>> {
+    /**
+     * Returns an iterator for the elements of this stream.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @return the element iterator for this stream
+     */
+    Iterator<T> iterator();
+
+    /**
+     * Returns a spliterator for the elements of this stream.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @return the element spliterator for this stream
+     */
+    Spliterator<T> spliterator();
+
+    /**
+     * Returns whether this stream, when executed, would execute in parallel
+     * (assuming no further modification of the stream, such as appending
+     * further intermediate operations or changing its parallelism).  Calling
+     * this method after invoking an intermediate or terminal stream operation
+     * method may yield unpredictable results.
+     *
+     * @return {@code true} if this stream would execute in parallel if executed
+     * without further modification otherwise {@code false}
+     */
+    boolean isParallel();
+
+    /**
+     * Returns an equivalent stream that is sequential.  May return
+     * itself, either because the stream was already sequential, or because
+     * the underlying stream state was modified to be sequential.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @return a sequential stream
+     */
+    S sequential();
+
+    /**
+     * Returns an equivalent stream that is parallel.  May return
+     * itself, either because the stream was already parallel, or because
+     * the underlying stream state was modified to be parallel.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @return a parallel stream
+     */
+    S parallel();
+
+    /**
+     * Returns an equivalent stream that is
+     * <a href="package-summary.html#Ordering">unordered</a>.  May return
+     * itself if the stream was already unordered.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @return an unordered stream
+     */
+    S unordered();
+}

src/share/classes/java/util/stream/CloseableStream.java

+/*
+ * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package java.util.stream;
+
+/**
+ * A {@code CloseableStream} is a {@code Stream} that can be closed.
+ * The close method is invoked to release resources that the object is
+ * holding (such as open files).
+ *
+ * @param <T> The type of stream elements
+ * @since 1.8
+ */
+public interface CloseableStream<T> extends Stream<T>, AutoCloseable {
+
+    /**
+     * Closes this resource, relinquishing any underlying resources.
+     * This method is invoked automatically on objects managed by the
+     * {@code try}-with-resources statement.  Does nothing if called when
+     * the resource has already been closed.
+     *
+     * This method does not allow throwing checked {@code Exception}s like
+     * {@link AutoCloseable#close() AutoCloseable.close()}. Cases where the
+     * close operation may fail require careful attention by implementers. It
+     * is strongly advised to relinquish the underlying resources and to
+     * internally <em>mark</em> the resource as closed. The {@code close}
+     * method is unlikely to be invoked more than once and so this ensures
+     * that the resources are released in a timely manner. Furthermore it
+     * reduces problems that could arise when the resource wraps, or is
+     * wrapped, by another resource.
+     *
+     * @see AutoCloseable#close()
+     */
+    void close();
+}

src/share/classes/java/util/stream/Collector.java

+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.util.stream;
+
+import java.util.Collections;
+import java.util.Set;
+import java.util.function.BiFunction;
+import java.util.function.BinaryOperator;
+import java.util.function.Supplier;
+
+/**
+ * A <a href="package-summary.html#Reduction">reduction operation</a> that
+ * supports folding input elements into a cumulative result.  The result may be
+ * a value or may be a mutable result container.  Examples of operations
+ * accumulating results into a mutable result container include: accumulating
+ * input elements into a {@code Collection}; concatenating strings into a
+ * {@code StringBuilder}; computing summary information about elements such as
+ * sum, min, max, or average; computing "pivot table" summaries such as "maximum
+ * valued transaction by seller", etc.  Reduction operations can be performed
+ * either sequentially or in parallel.
+ *
+ * <p>The following are examples of using the predefined {@code Collector}
+ * implementations in {@link Collectors} with the {@code Stream} API to perform
+ * mutable reduction tasks:
+ * <pre>{@code
+ *     // Accumulate elements into a List
+ *     List<String> list = stream.collect(Collectors.toList());
+ *
+ *     // Accumulate elements into a TreeSet
+ *     Set<String> list = stream.collect(Collectors.toCollection(TreeSet::new));
+ *
+ *     // Convert elements to strings and concatenate them, separated by commas
+ *     String joined = stream.map(Object::toString)
+ *                           .collect(Collectors.toStringJoiner(", "))
+ *                           .toString();
+ *
+ *     // Find highest-paid employee
+ *     Employee highestPaid = employees.stream()
+ *                                     .collect(Collectors.maxBy(Comparators.comparing(Employee::getSalary)));
+ *
+ *     // Group employees by department
+ *     Map<Department, List<Employee>> byDept
+ *         = employees.stream()
+ *                    .collect(Collectors.groupingBy(Employee::getDepartment));
+ *
+ *     // Find highest-paid employee by department
+ *     Map<Department, Employee> highestPaidByDept
+ *         = employees.stream()
+ *                    .collect(Collectors.groupingBy(Employee::getDepartment,
+ *                                                   Collectors.maxBy(Comparators.comparing(Employee::getSalary))));
+ *
+ *     // Partition students into passing and failing
+ *     Map<Boolean, List<Student>> passingFailing =
+ *         students.stream()
+ *                 .collect(Collectors.partitioningBy(s -> s.getGrade() >= PASS_THRESHOLD);
+ *
+ * }</pre>
+ *
+ * <p>A {@code Collector} is specified by three functions that work together to
+ * manage a result or result container.  They are: creation of an initial
+ * result, incorporating a new data element into a result, and combining two
+ * results into one. The last function -- combining two results into one -- is
+ * used during parallel operations, where subsets of the input are accumulated
+ * in parallel, and then the subresults merged into a combined result. The
+ * result may be a mutable container or a value.  If the result is mutable, the
+ * accumulation and combination functions may either mutate their left argument
+ * and return that (such as adding elements to a collection), or return a new
+ * result, in which case it should not perform any mutation.
+ *
+ * <p>Collectors also have a set of characteristics, including
+ * {@link Characteristics#CONCURRENT} and
+ * {@link Characteristics#STRICTLY_MUTATIVE}.  These characteristics provide
+ * hints that can be used by a reduction implementation to provide better
+ * performance.
+ *
+ * <p>Libraries that implement reduction based on {@code Collector}, such as
+ * {@link Stream#collect(Collector)}, must adhere to the following constraints:
+ * <ul>
+ *     <li>The first argument passed to the accumulator function, and both
+ *     arguments passed to the combiner function, must be the result of a
+ *     previous invocation of {@link #resultSupplier()}, {@link #accumulator()},
+ *     or {@link #combiner()}.</li>
+ *     <li>The implementation should not do anything with the result of any of
+ *     the result supplier, accumulator, or combiner functions other than to
+ *     pass them again to the accumulator or combiner functions, or return them
+ *     to the caller of the reduction operation.</li>
+ *     <li>If a result is passed to the accumulator or combiner function, and
+ *     the same object is not returned from that function, it is never used
+ *     again.</li>
+ *     <li>Once a result is passed to the combiner function, it is never passed
+ *     to the accumulator function again.</li>
+ *     <li>For non-concurrent collectors, any result returned from the result
+ *     supplier, accumulator, or combiner functions must be serially
+ *     thread-confined.  This enables collection to occur in parallel without
+ *     the {@code Collector} needing to implement any additional synchronization.
+ *     The reduction implementation must manage that the input is properly
+ *     partitioned, that partitions are processed in isolation, and combining
+ *     happens only after accumulation is complete.</li>
+ *     <li>For concurrent collectors, an implementation is free to (but not
+ *     required to) implement reduction concurrently.  A concurrent reduction
+ *     is one where the accumulator function is called concurrently from
+ *     multiple threads, using the same concurrently-modifiable result container,
+ *     rather than keeping the result isolated during accumulation.
+ *     A concurrent reduction should only be applied if the collector has the
+ *     {@link Characteristics#UNORDERED} characteristics or if the
+ *     originating data is unordered.</li>
+ * </ul>
+ *
+ * @apiNote
+ * Performing a reduction operation with a {@code Collector} should produce a
+ * result equivalent to:
+ * <pre>{@code
+ *     BiFunction<R,T,R> accumulator = collector.accumulator();
+ *     R result = collector.resultSupplier().get();
+ *     for (T t : data)
+ *         result = accumulator.apply(result, t);
+ *     return result;
+ * }</pre>
+ *
+ * <p>However, the library is free to partition the input, perform the reduction
+ * on the partitions, and then use the combiner function to combine the partial
+ * results to achieve a parallel reduction.  Depending on the specific reduction
+ * operation, this may perform better or worse, depending on the relative cost
+ * of the accumulator and combiner functions.
+ *
+ * <p>An example of an operation that can be easily modeled by {@code Collector}
+ * is accumulating elements into a {@code TreeSet}. In this case, the {@code
+ * resultSupplier()} function is {@code () -> new Treeset<T>()}, the
+ * {@code accumulator} function is
+ * {@code (set, element) -> { set.add(element); return set; }}, and the combiner
+ * function is {@code (left, right) -> { left.addAll(right); return left; }}.
+ * (This behavior is implemented by
+ * {@code Collectors.toCollection(TreeSet::new)}).
+ *
+ * TODO Associativity and commutativity
+ *
+ * @see Stream#collect(Collector)
+ * @see Collectors
+ *
+ * @param <T> the type of input element to the collect operation
+ * @param <R> the result type of the collect operation
+ * @since 1.8
+ */
+public interface Collector<T, R> {
+    /**
+     * A function that creates and returns a new result that represents
+     * "no values".  If the accumulator or combiner functions may mutate their
+     * arguments, this must be a new, empty result container.
+     *
+     * @return a function which, when invoked, returns a result representing
+     * "no values"
+     */
+    Supplier<R> resultSupplier();
+
+    /**
+     * A function that folds a new value into a cumulative result.  The result
+     * may be a mutable result container or a value.  The accumulator function
+     * may modify a mutable container and return it, or create a new result and
+     * return that, but if it returns a new result object, it must not modify
+     * any of its arguments.
+     *
+     * <p>If the collector has the {@link Characteristics#STRICTLY_MUTATIVE}
+     * characteristic, then the accumulator function <em>must</em> always return
+     * its first argument, after possibly mutating its state.
+     *
+     * @return a function which folds a new value into a cumulative result
+     */
+    BiFunction<R, T, R> accumulator();
+
+    /**
+     * A function that accepts two partial results and merges them.  The
+     * combiner function may fold state from one argument into the other and
+     * return that, or may return a new result object, but if it returns
+     * a new result object, it must not modify the state of either of its
+     * arguments.
+     *
+     * <p>If the collector has the {@link Characteristics#STRICTLY_MUTATIVE}
+     * characteristic, then the combiner function <em>must</em> always return
+     * its first argument, after possibly mutating its state.
+     *
+     * @return a function which combines two partial results into a cumulative
+     * result
+     */
+    BinaryOperator<R> combiner();
+
+    /**
+     * Returns a {@code Set} of {@code Collector.Characteristics} indicating
+     * the characteristics of this Collector.  This set should be immutable.
+     *
+     * @return an immutable set of collector characteristics
+     */
+    Set<Characteristics> characteristics();
+
+    /**
+     * Characteristics indicating properties of a {@code Collector}, which can
+     * be used to optimize reduction implementations.
+     */
+    enum Characteristics {
+        /**
+         * Indicates that this collector is <em>concurrent</em>, meaning that
+         * the result container can support the accumulator function being
+         * called concurrently with the same result container from multiple
+         * threads. Concurrent collectors must also always have the
+         * {@code STRICTLY_MUTATIVE} characteristic.
+         *
+         * <p>If a {@code CONCURRENT} collector is not also {@code UNORDERED},
+         * then it should only be evaluated concurrently if applied to an
+         * unordered data source.
+         */
+        CONCURRENT,
+
+        /**
+         * Indicates that the result container has no intrinsic order, such as
+         * a {@link Set}.
+         */
+        UNORDERED,
+
+        /**
+         * Indicates that this collector operates by strict mutation of its
+         * result container. This means that the {@link #accumulator()} and
+         * {@link #combiner()} functions will always modify the state of and
+         * return their first argument, rather than returning a different result
+         * container.
+         */
+        STRICTLY_MUTATIVE
+    }
+}

src/share/classes/java/util/stream/DelegatingStream.java

+/*
+ * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package java.util.stream;
+
+import java.util.Comparator;
+import java.util.Iterator;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Spliterator;
+import java.util.function.BiConsumer;
+import java.util.function.BiFunction;
+import java.util.function.BinaryOperator;
+import java.util.function.Consumer;
+import java.util.function.Function;
+import java.util.function.IntFunction;
+import java.util.function.Predicate;
+import java.util.function.Supplier;
+import java.util.function.ToDoubleFunction;
+import java.util.function.ToIntFunction;
+import java.util.function.ToLongFunction;
+
+/**
+ * A {@code Stream} implementation that delegates operations to another {@code
+ * Stream}.
+ *
+ * @param <T> type of stream elements for this stream and underlying delegate
+ * stream
+ *
+ * @since 1.8
+ */
+public class DelegatingStream<T> implements Stream<T> {
+    final private Stream<T> delegate;
+
+    /**
+     * Construct a {@code Stream} that delegates operations to another {@code
+     * Stream}.
+     *
+     * @param delegate the underlying {@link Stream} to which we delegate all
+     *                 {@code Stream} methods
+     * @throws NullPointerException if the delegate is null
+     */
+    public DelegatingStream(Stream<T> delegate) {
+        this.delegate = Objects.requireNonNull(delegate);
+    }
+
+    // -- BaseStream methods --
+
+    @Override
+    public Spliterator<T> spliterator() {
+        return delegate.spliterator();
+    }
+
+    @Override
+    public boolean isParallel() {
+        return delegate.isParallel();
+    }
+
+    @Override
+    public Iterator<T> iterator() {
+        return delegate.iterator();
+    }
+
+    // -- Stream methods --
+
+    @Override
+    public Stream<T> filter(Predicate<? super T> predicate) {
+        return delegate.filter(predicate);
+    }
+
+    @Override
+    public <R> Stream<R> map(Function<? super T, ? extends R> mapper) {
+        return delegate.map(mapper);
+    }
+
+    @Override
+    public IntStream mapToInt(ToIntFunction<? super T> mapper) {
+        return delegate.mapToInt(mapper);
+    }
+
+    @Override
+    public LongStream mapToLong(ToLongFunction<? super T> mapper) {
+        return delegate.mapToLong(mapper);
+    }
+
+    @Override
+    public DoubleStream mapToDouble(ToDoubleFunction<? super T> mapper) {
+        return delegate.mapToDouble(mapper);
+    }
+
+    @Override
+    public <R> Stream<R> flatMap(Function<? super T, ? extends Stream<? extends R>> mapper) {
+        return delegate.flatMap(mapper);
+    }
+
+    @Override
+    public IntStream flatMapToInt(Function<? super T, ? extends IntStream> mapper) {
+        return delegate.flatMapToInt(mapper);
+    }
+
+    @Override
+    public LongStream flatMapToLong(Function<? super T, ? extends LongStream> mapper) {
+        return delegate.flatMapToLong(mapper);
+    }
+
+    @Override
+    public DoubleStream flatMapToDouble(Function<? super T, ? extends DoubleStream> mapper) {
+        return delegate.flatMapToDouble(mapper);
+    }
+
+    @Override
+    public Stream<T> distinct() {
+        return delegate.distinct();
+    }
+
+    @Override
+    public Stream<T> sorted() {
+        return delegate.sorted();
+    }
+
+    @Override
+    public Stream<T> sorted(Comparator<? super T> comparator) {
+        return delegate.sorted(comparator);
+    }
+
+    @Override
+    public void forEach(Consumer<? super T> action) {
+        delegate.forEach(action);
+    }
+
+    @Override
+    public void forEachOrdered(Consumer<? super T> action) {
+        delegate.forEachOrdered(action);
+    }
+
+    @Override
+    public Stream<T> peek(Consumer<? super T> consumer) {
+        return delegate.peek(consumer);
+    }
+
+    @Override
+    public Stream<T> limit(long maxSize) {
+        return delegate.limit(maxSize);
+    }
+
+    @Override
+    public Stream<T> substream(long startingOffset) {
+        return delegate.substream(startingOffset);
+    }
+
+    @Override
+    public Stream<T> substream(long startingOffset, long endingOffset) {
+        return delegate.substream(startingOffset, endingOffset);
+    }
+
+    @Override
+    public <A> A[] toArray(IntFunction<A[]> generator) {
+        return delegate.toArray(generator);
+    }
+
+    @Override
+    public Object[] toArray() {
+        return delegate.toArray();
+    }
+
+    @Override
+    public T reduce(T identity, BinaryOperator<T> accumulator) {
+        return delegate.reduce(identity, accumulator);
+    }
+
+    @Override
+    public Optional<T> reduce(BinaryOperator<T> accumulator) {
+        return delegate.reduce(accumulator);
+    }
+
+    @Override
+    public <U> U reduce(U identity, BiFunction<U, ? super T, U> accumulator,
+                        BinaryOperator<U> combiner) {
+        return delegate.reduce(identity, accumulator, combiner);
+    }
+
+    @Override
+    public <R> R collect(Supplier<R> resultFactory,
+                         BiConsumer<R, ? super T> accumulator,
+                         BiConsumer<R, R> combiner) {
+        return delegate.collect(resultFactory, accumulator, combiner);
+    }
+
+    @Override
+    public <R> R collect(Collector<? super T, R> collector) {
+        return delegate.collect(collector);
+    }
+
+    @Override
+    public Optional<T> max(Comparator<? super T> comparator) {
+        return delegate.max(comparator);
+    }
+
+    @Override
+    public Optional<T> min(Comparator<? super T> comparator) {
+        return delegate.min(comparator);
+    }
+
+    @Override
+    public long count() {
+        return delegate.count();
+    }
+
+    @Override
+    public boolean anyMatch(Predicate<? super T> predicate) {
+        return delegate.anyMatch(predicate);
+    }
+
+    @Override
+    public boolean allMatch(Predicate<? super T> predicate) {
+        return delegate.allMatch(predicate);
+    }
+
+    @Override
+    public boolean noneMatch(Predicate<? super T> predicate) {
+        return delegate.noneMatch(predicate);
+    }
+
+    @Override
+    public Optional<T> findFirst() {
+        return delegate.findFirst();
+    }
+
+    @Override
+    public Optional<T> findAny() {
+        return delegate.findAny();
+    }
+
+    @Override
+    public Stream<T> unordered() {
+        return delegate.unordered();
+    }
+
+    @Override
+    public Stream<T> sequential() {
+        return delegate.sequential();
+    }
+
+    @Override
+    public Stream<T> parallel() {
+        return delegate.parallel();
+    }
+}

src/share/classes/java/util/stream/DoubleStream.java

+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.util.stream;
+
+import java.util.DoubleSummaryStatistics;
+import java.util.OptionalDouble;
+import java.util.PrimitiveIterator;
+import java.util.Spliterator;
+import java.util.function.BiConsumer;
+import java.util.function.DoubleBinaryOperator;
+import java.util.function.DoubleConsumer;
+import java.util.function.DoubleFunction;
+import java.util.function.DoublePredicate;
+import java.util.function.DoubleToIntFunction;
+import java.util.function.DoubleToLongFunction;
+import java.util.function.DoubleUnaryOperator;
+import java.util.function.Function;
+import java.util.function.ObjDoubleConsumer;
+import java.util.function.Supplier;
+
+/**
+ * A sequence of primitive double elements supporting sequential and parallel
+ * bulk operations. Streams support lazy intermediate operations (transforming
+ * a stream to another stream) such as {@code filter} and {@code map}, and terminal
+ * operations (consuming the contents of a stream to produce a result or
+ * side-effect), such as {@code forEach}, {@code findFirst}, and {@code
+ * iterator}.  Once an operation has been performed on a stream, it
+ * is considered <em>consumed</em> and no longer usable for other operations.
+ *
+ * <p>For sequential stream pipelines, all operations are performed in the
+ * <a href="package-summary.html#Ordering">encounter order</a> of the pipeline
+ * source, if the pipeline source has a defined encounter order.
+ *
+ * <p>For parallel stream pipelines, unless otherwise specified, intermediate
+ * stream operations preserve the <a href="package-summary.html#Ordering">
+ * encounter order</a> of their source, and terminal operations
+ * respect the encounter order of their source, if the source
+ * has an encounter order.  Provided that and parameters to stream operations
+ * satisfy the <a href="package-summary.html#NonInterference">non-interference
+ * requirements</a>, and excepting differences arising from the absence of
+ * a defined encounter order, the result of a stream pipeline should be the
+ * stable across multiple executions of the same operations on the same source.
+ * However, the timing and thread in which side-effects occur (for those
+ * operations which are allowed to produce side-effects, such as
+ * {@link #forEach(DoubleConsumer)}), are explicitly nondeterministic for parallel
+ * execution of stream pipelines.
+ *
+ * <p>Unless otherwise noted, passing a {@code null} argument to any stream
+ * method may result in a {@link NullPointerException}.
+ *
+ * @apiNote
+ * Streams are not data structures; they do not manage the storage for their
+ * elements, nor do they support access to individual elements.  However,
+ * you can use the {@link #iterator()} or {@link #spliterator()} operations to
+ * perform a controlled traversal.
+ *
+ * @since 1.8
+ * @see <a href="package-summary.html">java.util.stream</a>
+ */
+public interface DoubleStream extends BaseStream<Double, DoubleStream> {
+
+    /**
+     * Returns a stream consisting of the elements of this stream that match
+     * the given predicate.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">
+     *                  non-interfering, stateless</a> predicate to apply to
+     *                  each element to determine if it should be included
+     * @return the new stream
+     */
+    DoubleStream filter(DoublePredicate predicate);
+
+    /**
+     * Returns a stream consisting of the results of applying the given
+     * function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to
+     *               each element
+     * @return the new stream
+     */
+    DoubleStream map(DoubleUnaryOperator mapper);
+
+    /**
+     * Returns an object-valued {@code Stream} consisting of the results of
+     * applying the given function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">
+     *     intermediate operation</a>.
+     *
+     * @param <U> the element type of the new stream
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    <U> Stream<U> mapToObj(DoubleFunction<? extends U> mapper);
+
+    /**
+     * Returns an {@code IntStream} consisting of the results of applying the
+     * given function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    IntStream mapToInt(DoubleToIntFunction mapper);
+
+    /**
+     * Returns a {@code LongStream} consisting of the results of applying the
+     * given function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    LongStream mapToLong(DoubleToLongFunction mapper);
+
+    /**
+     * Returns a stream consisting of the results of replacing each element of
+     * this stream with the contents of the stream produced by applying the
+     * provided mapping function to each element.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @apiNote
+     * The {@code flatMap()} operation has the effect of applying a one-to-many
+     * tranformation to the elements of the stream, and then flattening the
+     * resulting elements into a new stream. For example, if {@code orders}
+     * is a stream of purchase orders, and each purchase order contains a
+     * collection of line items, then the following produces a stream of line
+     * items:
+     * <pre>{@code
+     *     orderStream.flatMap(order -> order.getLineItems().stream())...
+     * }</pre>
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to
+     *               each element which produces an {@code DoubleStream} of new
+     *               values
+     * @return the new stream
+     * @see Stream#flatMap(Function)
+     */
+    DoubleStream flatMap(DoubleFunction<? extends DoubleStream> mapper);
+
+    /**
+     * Returns a stream consisting of the distinct elements of this stream. The
+     * elements are compared for equality according to
+     * {@link java.lang.Double#compare(double, double)}.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">stateful
+     * intermediate operation</a>.
+     *
+     * @return the result stream
+     */
+    DoubleStream distinct();
+
+    /**
+     * Returns a stream consisting of the elements of this stream in sorted
+     * order. The elements are compared for equality according to
+     * {@link java.lang.Double#compare(double, double)}.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">stateful
+     * intermediate operation</a>.
+     *
+     * @return the result stream
+     */
+    DoubleStream sorted();
+
+    /**
+     * Returns a stream consisting of the elements of this stream, additionally
+     * performing the provided action on each element as elements are consumed
+     * from the resulting stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * <p>For parallel stream pipelines, the action may be called at
+     * whatever time and in whatever thread the element is made available by the
+     * upstream operation.  If the action modifies shared state,
+     * it is responsible for providing the required synchronization.
+     *
+     * @apiNote This method exists mainly to support debugging, where you want
+     * to see the elements as they flow past a certain point in a pipeline:
+     * <pre>{@code
+     *     list.stream()
+     *         .filter(filteringFunction)
+     *         .peek(e -> {System.out.println("Filtered value: " + e); });
+     *         .map(mappingFunction)
+     *         .peek(e -> {System.out.println("Mapped value: " + e); });
+     *         .collect(Collectors.toDoubleSummaryStastistics());
+     * }</pre>
+     *
+     * @param consumer a <a href="package-summary.html#NonInterference">
+     *                 non-interfering</a> action to perform on the elements as
+     *                 they are consumed from the stream
+     * @return the new stream
+     */
+    DoubleStream peek(DoubleConsumer consumer);
+
+    /**
+     * Returns a stream consisting of the elements of this stream, truncated
+     * to be no longer than {@code maxSize} in length.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * stateful intermediate operation</a>.
+     *
+     * @param maxSize the number of elements the stream should be limited to
+     * @return the new stream
+     * @throws IllegalArgumentException if {@code maxSize} is negative
+     */
+    DoubleStream limit(long maxSize);
+
+    /**
+     * Returns a stream consisting of the remaining elements of this stream
+     * after indexing {@code startInclusive} elements into the stream. If the
+     * {@code startInclusive} index lies past the end of this stream then an
+     * empty stream will be returned.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">stateful
+     * intermediate operation</a>.
+     *
+     * @param startInclusive the number of leading elements to skip
+     * @return the new stream
+     * @throws IllegalArgumentException if {@code startInclusive} is negative
+     */
+    DoubleStream substream(long startInclusive);
+
+    /**
+     * Returns a stream consisting of the remaining elements of this stream
+     * after indexing {@code startInclusive} elements into the stream and
+     * truncated to contain no more than {@code endExclusive - startInclusive}
+     * elements. If the {@code startInclusive} index lies past the end
+     * of this stream then an empty stream will be returned.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * stateful intermediate operation</a>.
+     *
+     * @param startInclusive the starting position of the substream, inclusive
+     * @param endExclusive the ending position of the substream, exclusive
+     * @return the new stream
+     * @throws IllegalArgumentException if {@code startInclusive} or
+     * {@code endExclusive} is negative or {@code startInclusive} is greater
+     * than {@code endExclusive}
+     */
+    DoubleStream substream(long startInclusive, long endExclusive);
+
+    /**
+     * Performs an action for each element of this stream.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * <p>For parallel stream pipelines, this operation does <em>not</em>
+     * guarantee to respect the encounter order of the stream, as doing so
+     * would sacrifice the benefit of parallelism.  For any given element, the
+     * action may be performed at whatever time and in whatever thread the
+     * library chooses.  If the action accesses shared state, it is
+     * responsible for providing the required synchronization.
+     *
+     * @param action a <a href="package-summary.html#NonInterference">
+     *               non-interfering</a> action to perform on the elements
+     */
+    void forEach(DoubleConsumer action);
+
+    /**
+     * Performs an action for each element of this stream, guaranteeing that
+     * each element is processed in encounter order for streams that have a
+     * defined encounter order.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @param action a <a href="package-summary.html#NonInterference">
+     *               non-interfering</a> action to perform on the elements
+     * @see #forEach(DoubleConsumer)
+     */
+    void forEachOrdered(DoubleConsumer action);
+
+    /**
+     * Returns an array containing the elements of this stream.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @return an array containing the elements of this stream
+     */
+    double[] toArray();
+
+    /**
+     * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
+     * elements of this stream, using the provided identity value and an
+     * <a href="package-summary.html#Associativity">associative</a>
+     * accumulation function, and returns the reduced value.  This is equivalent
+     * to:
+     * <pre>{@code
+     *     double result = identity;
+     *     for (double element : this stream)
+     *         result = accumulator.apply(result, element)
+     *     return result;
+     * }</pre>
+     *
+     * but is not constrained to execute sequentially.
+     *
+     * <p>The {@code identity} value must be an identity for the accumulator
+     * function. This means that for all {@code x},
+     * {@code accumulator.apply(identity, x)} is equal to {@code x}.
+     * The {@code accumulator} function must be an
+     * <a href="package-summary.html#Associativity">associative</a> function.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @apiNote Sum, min, max, and average are all special cases of reduction.
+     * Summing a stream of numbers can be expressed as:
+
+     * <pre>{@code
+     *     double sum = numbers.reduce(0, (a, b) -> a+b);
+     * }</pre>
+     *
+     * or more compactly:
+     *
+     * <pre>{@code
+     *     double sum = numbers.reduce(0, Double::sum);
+     * }</pre>
+     *
+     * <p>While this may seem a more roundabout way to perform an aggregation
+     * compared to simply mutating a running total in a loop, reduction
+     * operations parallelize more gracefully, without needing additional
+     * synchronization and with greatly reduced risk of data races.
+     *
+     * @param identity the identity value for the accumulating function
+     * @param op an <a href="package-summary.html#Associativity">associative</a>
+     *                    <a href="package-summary.html#NonInterference">non-interfering,
+     *                    stateless</a> function for combining two values
+     * @return the result of the reduction
+     * @see #sum()
+     * @see #min()
+     * @see #max()
+     * @see #average()
+     */
+    double reduce(double identity, DoubleBinaryOperator op);
+
+    /**
+     * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
+     * elements of this stream, using an
+     * <a href="package-summary.html#Associativity">associative</a> accumulation
+     * function, and returns an {@code OptionalDouble} describing the reduced
+     * value, if any. This is equivalent to:
+     * <pre>{@code
+     *     boolean foundAny = false;
+     *     double result = null;
+     *     for (double element : this stream) {
+     *         if (!foundAny) {
+     *             foundAny = true;
+     *             result = element;
+     *         }
+     *         else
+     *             result = accumulator.apply(result, element);
+     *     }
+     *     return foundAny ? OptionalDouble.of(result) : OptionalDouble.empty();
+     * }</pre>
+     *
+     * but is not constrained to execute sequentially.
+     *
+     * <p>The {@code accumulator} function must be an
+     * <a href="package-summary.html#Associativity">associative</a> function.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @param op an <a href="package-summary.html#Associativity">associative</a>
+     *           <a href="package-summary.html#NonInterference">non-interfering,
+     *           stateless</a> function for combining two values
+     * @return the result of the reduction
+     * @see #reduce(double, DoubleBinaryOperator)
+     */
+    OptionalDouble reduce(DoubleBinaryOperator op);
+
+    /**
+     * Performs a <a href="package-summary.html#MutableReduction">mutable
+     * reduction</a> operation on the elements of this stream.  A mutable
+     * reduction is one in which the reduced value is a mutable value holder,
+     * such as an {@code ArrayList}, and elements are incorporated by updating
+     * the state of the result, rather than by replacing the result.  This
+     * produces a result equivalent to:
+     * <pre>{@code
+     *     R result = resultFactory.get();
+     *     for (double element : this stream)
+     *         accumulator.accept(result, element);
+     *     return result;
+     * }</pre>
+     *
+     * <p>Like {@link #reduce(double, DoubleBinaryOperator)}, {@code collect}
+     * operations can be parallelized without requiring additional
+     * synchronization.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @param <R> type of the result
+     * @param resultFactory a function that creates a new result container.
+     *                      For a parallel execution, this function may be
+     *                      called multiple times and must return a fresh value
+     *                      each time.
+     * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
+     *                    <a href="package-summary.html#NonInterference">non-interfering,
+     *                    stateless</a> function for incorporating an additional
+     *                    element into a result
+     * @param combiner an <a href="package-summary.html#Associativity">associative</a>
+     *                 <a href="package-summary.html#NonInterference">non-interfering,
+     *                 stateless</a> function for combining two values, which
+     *                 must be compatible with the accumulator function
+     * @return the result of the reduction
+     * @see Stream#collect(Supplier, BiConsumer, BiConsumer)
+     */
+    <R> R collect(Supplier<R> resultFactory,
+                  ObjDoubleConsumer<R> accumulator,
+                  BiConsumer<R, R> combiner);
+
+    /**
+     * Returns the sum of elements in this stream.  The sum returned can vary
+     * depending upon the order in which elements are encountered.  This is due
+     * to accumulated rounding error in addition of values of differing
+     * magnitudes. Elements sorted by increasing absolute magnitude tend to
+     * yield more accurate results.  If any stream element is a {@code NaN} or
+     * the sum is at any point a {@code NaN} then the sum will be {@code NaN}.
+     * This is a special case of a
+     * <a href="package-summary.html#MutableReduction">reduction</a> and is
+     * equivalent to:
+     * <pre>{@code
+     *     return reduce(0, Double::sum);
+     * }</pre>
+     *
+     * @return the sum of elements in this stream
+     */
+    double sum();
+
+    /**
+     * Returns an {@code OptionalDouble} describing the minimum element of this
+     * stream, or an empty OptionalDouble if this stream is empty.  The minimum
+     * element will be {@code Double.NaN} if any stream element was NaN. Unlike
+     * the numerical comparison operators, this method considers negative zero
+     * to be strictly smaller than positive zero. This is a special case of a
+     * <a href="package-summary.html#MutableReduction">reduction</a> and is
+     * equivalent to:
+     * <pre>{@code
+     *     return reduce(Double::min);
+     * }</pre>
+     *
+     * @return an {@code OptionalDouble} containing the minimum element of this
+     * stream, or an empty optional if the stream is empty
+     */
+    OptionalDouble min();
+
+    /**
+     * Returns an {@code OptionalDouble} describing the maximum element of this
+     * stream, or an empty OptionalDouble if this stream is empty.  The maximum
+     * element will be {@code Double.NaN} if any stream element was NaN. Unlike
+     * the numerical comparison operators, this method considers negative zero
+     * to be strictly smaller than positive zero. This is a
+     * special case of a
+     * <a href="package-summary.html#MutableReduction">reduction</a> and is
+     * equivalent to:
+     * <pre>{@code
+     *     return reduce(Double::max);
+     * }</pre>
+     *
+     * @return an {@code OptionalDouble} containing the maximum element of this
+     * stream, or an empty optional if the stream is empty
+     */
+    OptionalDouble max();
+
+    /**
+     * Returns the count of elements in this stream.  This is a special case of
+     * a <a href="package-summary.html#MutableReduction">reduction</a> and is
+     * equivalent to:
+     * <pre>{@code
+     *     return mapToLong(e -> 1L).sum();
+     * }</pre>
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+     *
+     * @return the count of elements in this stream
+     */
+    long count();
+
+    /**
+     * Returns an {@code OptionalDouble} describing the average of elements of
+     * this stream, or an empty optional if this stream is empty.  The average
+     * returned can vary depending upon the order in which elements are
+     * encountered. This is due to accumulated rounding error in addition of
+     * elements of differing magnitudes. Elements sorted by increasing absolute
+     * magnitude tend to yield more accurate results. If any recorded value is
+     * a {@code NaN} or the sum is at any point a {@code NaN} then the average
+     * will be {@code NaN}. This is a special case of a
+     * <a href="package-summary.html#MutableReduction">reduction</a>.
+     *
+     * @return an {@code OptionalDouble} containing the average element of this
+     * stream, or an empty optional if the stream is empty
+     */
+    OptionalDouble average();
+
+    /**
+     * Returns a {@code DoubleSummaryStatistics} describing various summary data
+     * about the elements of this stream.  This is a special
+     * case of a <a href="package-summary.html#MutableReduction">reduction</a>.
+     *
+     * @return a {@code DoubleSummaryStatistics} describing various summary data
+     * about the elements of this stream
+     */
+    DoubleSummaryStatistics summaryStatistics();
+
+    /**
+     * Returns whether any elements of this stream match the provided
+     * predicate.  May not evaluate the predicate on all elements if not
+     * necessary for determining the result.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
+     * @return {@code true} if any elements of the stream match the provided
+     * predicate otherwise {@code false}
+     */
+    boolean anyMatch(DoublePredicate predicate);
+
+    /**
+     * Returns whether all elements of this stream match the provided predicate.
+     * May not evaluate the predicate on all elements if not necessary for
+     * determining the result.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
+     * @return {@code true} if all elements of the stream match the provided
+     * predicate otherwise {@code false}
+     */
+    boolean allMatch(DoublePredicate predicate);
+
+    /**
+     * Returns whether no elements of this stream match the provided predicate.
+     * May not evaluate the predicate on all elements if not necessary for
+     * determining the result.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
+     * @return {@code true} if no elements of the stream match the provided
+     * predicate otherwise {@code false}
+     */
+    boolean noneMatch(DoublePredicate predicate);
+
+    /**
+     * Returns an {@link OptionalDouble} describing the first element of this
+     * stream (in the encounter order), or an empty {@code OptionalDouble} if
+     * the stream is empty.  If the stream has no encounter order, than any
+     * element may be returned.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @return an {@code OptionalDouble} describing the first element of this
+     * stream, or an empty {@code OptionalDouble} if the stream is empty
+     */
+    OptionalDouble findFirst();
+
+    /**
+     * Returns an {@link OptionalDouble} describing some element of the stream,
+     * or an empty {@code OptionalDouble} if the stream is empty.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * <p>The behavior of this operation is explicitly nondeterministic; it is
+     * free to select any element in the stream.  This is to allow for maximal
+     * performance in parallel operations; the cost is that multiple invocations
+     * on the same source may not return the same result.  (If the first element
+     * in the encounter order is desired, use {@link #findFirst()} instead.)
+     *
+     * @return an {@code OptionalDouble} describing some element of this stream,
+     * or an empty {@code OptionalDouble} if the stream is empty
+     * @see #findFirst()
+     */
+    OptionalDouble findAny();
+
+    /**
+     * Returns a {@code Stream} consisting of the elements of this stream,
+     * boxed to {@code Double}.
+     *
+     * @return a {@code Stream} consistent of the elements of this stream,
+     * each boxed to a {@code Double}
+     */
+    Stream<Double> boxed();
+
+    @Override
+    DoubleStream sequential();
+
+    @Override
+    DoubleStream parallel();
+
+    @Override
+    PrimitiveIterator.OfDouble iterator();
+
+    @Override
+    Spliterator.OfDouble spliterator();
+}

src/share/classes/java/util/stream/IntStream.java

+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.util.stream;
+
+import java.util.IntSummaryStatistics;
+import java.util.OptionalDouble;
+import java.util.OptionalInt;
+import java.util.PrimitiveIterator;
+import java.util.Spliterator;
+import java.util.function.BiConsumer;
+import java.util.function.Function;
+import java.util.function.IntBinaryOperator;
+import java.util.function.IntConsumer;
+import java.util.function.IntFunction;
+import java.util.function.IntPredicate;
+import java.util.function.IntToDoubleFunction;
+import java.util.function.IntToLongFunction;
+import java.util.function.IntUnaryOperator;
+import java.util.function.ObjIntConsumer;
+import java.util.function.Supplier;
+
+/**
+ * A sequence of primitive integer elements supporting sequential and parallel
+ * bulk operations. Streams support lazy intermediate operations (transforming
+ * a stream to another stream) such as {@code filter} and {@code map}, and terminal
+ * operations (consuming the contents of a stream to produce a result or
+ * side-effect), such as {@code forEach}, {@code findFirst}, and {@code
+ * iterator}.  Once an operation has been performed on a stream, it
+ * is considered <em>consumed</em> and no longer usable for other operations.
+ *
+ * <p>For sequential stream pipelines, all operations are performed in the
+ * <a href="package-summary.html#Ordering">encounter order</a> of the pipeline
+ * source, if the pipeline source has a defined encounter order.
+ *
+ * <p>For parallel stream pipelines, unless otherwise specified, intermediate
+ * stream operations preserve the <a href="package-summary.html#Ordering">
+ * encounter order</a> of their source, and terminal operations
+ * respect the encounter order of their source, if the source
+ * has an encounter order.  Provided that and parameters to stream operations
+ * satisfy the <a href="package-summary.html#NonInterference">non-interference
+ * requirements</a>, and excepting differences arising from the absence of
+ * a defined encounter order, the result of a stream pipeline should be the
+ * stable across multiple executions of the same operations on the same source.
+ * However, the timing and thread in which side-effects occur (for those
+ * operations which are allowed to produce side-effects, such as
+ * {@link #forEach(IntConsumer)}), are explicitly nondeterministic for parallel
+ * execution of stream pipelines.
+ *
+ * <p>Unless otherwise noted, passing a {@code null} argument to any stream
+ * method may result in a {@link NullPointerException}.
+ *
+ * @apiNote
+ * Streams are not data structures; they do not manage the storage for their
+ * elements, nor do they support access to individual elements.  However,
+ * you can use the {@link #iterator()} or {@link #spliterator()} operations to
+ * perform a controlled traversal.
+ *
+ * @since 1.8
+ * @see <a href="package-summary.html">java.util.stream</a>
+ */
+public interface IntStream extends BaseStream<Integer, IntStream> {
+
+    /**
+     * Returns a stream consisting of the elements of this stream that match
+     * the given predicate.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">
+     *                  non-interfering, stateless</a> predicate to apply to
+     *                  each element to determine if it should be included
+     * @return the new stream
+     */
+    IntStream filter(IntPredicate predicate);
+
+    /**
+     * Returns a stream consisting of the results of applying the given
+     * function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    IntStream map(IntUnaryOperator mapper);
+
+    /**
+     * Returns an object-valued {@code Stream} consisting of the results of
+     * applying the given function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">
+     *     intermediate operation</a>.
+     *
+     * @param <U> the element type of the new stream
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    <U> Stream<U> mapToObj(IntFunction<? extends U> mapper);
+
+    /**
+     * Returns a {@code LongStream} consisting of the results of applying the
+     * given function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    LongStream mapToLong(IntToLongFunction mapper);
+
+    /**
+     * Returns a {@code DoubleStream} consisting of the results of applying the
+     * given function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    DoubleStream mapToDouble(IntToDoubleFunction mapper);
+
+    /**
+     * Returns a stream consisting of the results of replacing each element of
+     * this stream with the contents of the stream produced by applying the
+     * provided mapping function to each element.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @apiNote
+     * The {@code flatMap()} operation has the effect of applying a one-to-many
+     * tranformation to the elements of the stream, and then flattening the
+     * resulting elements into a new stream. For example, if {@code orders}
+     * is a stream of purchase orders, and each purchase order contains a
+     * collection of line items, then the following produces a stream of line
+     * items:
+     * <pre>{@code
+     *     orderStream.flatMap(order -> order.getLineItems().stream())...
+     * }</pre>
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to
+     *               each element which produces an {@code IntStream} of new
+     *               values
+     * @return the new stream
+     * @see Stream#flatMap(Function)
+     */
+    IntStream flatMap(IntFunction<? extends IntStream> mapper);
+
+    /**
+     * Returns a stream consisting of the distinct elements of this stream.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">stateful
+     * intermediate operation</a>.
+     *
+     * @return the new stream
+     */
+    IntStream distinct();
+
+    /**
+     * Returns a stream consisting of the elements of this stream in sorted
+     * order.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">stateful
+     * intermediate operation</a>.
+     *
+     * @return the new stream
+     */
+    IntStream sorted();
+
+    /**
+     * Returns a stream consisting of the elements of this stream, additionally
+     * performing the provided action on each element as elements are consumed
+     * from the resulting stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * <p>For parallel stream pipelines, the action may be called at
+     * whatever time and in whatever thread the element is made available by the
+     * upstream operation.  If the action modifies shared state,
+     * it is responsible for providing the required synchronization.
+     *
+     * @apiNote This method exists mainly to support debugging, where you want
+     * to see the elements as they flow past a certain point in a pipeline:
+     * <pre>{@code
+     *     list.stream()
+     *         .filter(filteringFunction)
+     *         .peek(e -> {System.out.println("Filtered value: " + e); });
+     *         .map(mappingFunction)
+     *         .peek(e -> {System.out.println("Mapped value: " + e); });
+     *         .collect(Collectors.toIntSummaryStastistics());
+     * }</pre>
+     *
+     * @param consumer a <a href="package-summary.html#NonInterference">
+     *                 non-interfering</a> action to perform on the elements as
+     *                 they are consumed from the stream
+     * @return the new stream
+     */
+    IntStream peek(IntConsumer consumer);
+
+    /**
+     * Returns a stream consisting of the elements of this stream, truncated
+     * to be no longer than {@code maxSize} in length.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * stateful intermediate operation</a>.
+     *
+     * @param maxSize the number of elements the stream should be limited to
+     * @return the new stream
+     * @throws IllegalArgumentException if {@code maxSize} is negative
+     */
+    IntStream limit(long maxSize);
+
+    /**
+     * Returns a stream consisting of the remaining elements of this stream
+     * after indexing {@code startInclusive} elements into the stream. If the
+     * {@code startInclusive} index lies past the end of this stream then an
+     * empty stream will be returned.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">stateful
+     * intermediate operation</a>.
+     *
+     * @param startInclusive the number of leading elements to skip
+     * @return the new stream
+     * @throws IllegalArgumentException if {@code startInclusive} is negative
+     */
+    IntStream substream(long startInclusive);
+
+    /**
+     * Returns a stream consisting of the remaining elements of this stream
+     * after indexing {@code startInclusive} elements into the stream and
+     * truncated to contain no more than {@code endExclusive - startInclusive}
+     * elements. If the {@code startInclusive} index lies past the end
+     * of this stream then an empty stream will be returned.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * stateful intermediate operation</a>.
+     *
+     * @param startInclusive the starting position of the substream, inclusive
+     * @param endExclusive the ending position of the substream, exclusive
+     * @return the new stream
+     * @throws IllegalArgumentException if {@code startInclusive} or
+     * {@code endExclusive} is negative or {@code startInclusive} is greater
+     * than {@code endExclusive}
+     */
+    IntStream substream(long startInclusive, long endExclusive);
+
+    /**
+     * Performs an action for each element of this stream.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * <p>For parallel stream pipelines, this operation does <em>not</em>
+     * guarantee to respect the encounter order of the stream, as doing so
+     * would sacrifice the benefit of parallelism.  For any given element, the
+     * action may be performed at whatever time and in whatever thread the
+     * library chooses.  If the action accesses shared state, it is
+     * responsible for providing the required synchronization.
+     *
+     * @param action a <a href="package-summary.html#NonInterference">
+     *               non-interfering</a> action to perform on the elements
+     */
+    void forEach(IntConsumer action);
+
+    /**
+     * Performs an action for each element of this stream, guaranteeing that
+     * each element is processed in encounter order for streams that have a
+     * defined encounter order.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @param action a <a href="package-summary.html#NonInterference">
+     *               non-interfering</a> action to perform on the elements
+     * @see #forEach(IntConsumer)
+     */
+    void forEachOrdered(IntConsumer action);
+
+    /**
+     * Returns an array containing the elements of this stream.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @return an array containing the elements of this stream
+     */
+    int[] toArray();
+
+    /**
+     * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
+     * elements of this stream, using the provided identity value and an
+     * <a href="package-summary.html#Associativity">associative</a>
+     * accumulation function, and returns the reduced value.  This is equivalent
+     * to:
+     * <pre>{@code
+     *     int result = identity;
+     *     for (int element : this stream)
+     *         result = accumulator.apply(result, element)
+     *     return result;
+     * }</pre>
+     *
+     * but is not constrained to execute sequentially.
+     *
+     * <p>The {@code identity} value must be an identity for the accumulator
+     * function. This means that for all {@code x},
+     * {@code accumulator.apply(identity, x)} is equal to {@code x}.
+     * The {@code accumulator} function must be an
+     * <a href="package-summary.html#Associativity">associative</a> function.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @apiNote Sum, min, max, and average are all special cases of reduction.
+     * Summing a stream of numbers can be expressed as:
+     *
+     * <pre>{@code
+     *     int sum = integers.reduce(0, (a, b) -> a+b);
+     * }</pre>
+     *
+     * or more compactly:
+     *
+     * <pre>{@code
+     *     int sum = integers.reduce(0, Integer::sum);
+     * }</pre>
+     *
+     * <p>While this may seem a more roundabout way to perform an aggregation
+     * compared to simply mutating a running total in a loop, reduction
+     * operations parallelize more gracefully, without needing additional
+     * synchronization and with greatly reduced risk of data races.
+     *
+     * @param identity the identity value for the accumulating function
+     * @param op an <a href="package-summary.html#Associativity">associative</a>
+     *                    <a href="package-summary.html#NonInterference">non-interfering,
+     *                    stateless</a> function for combining two values
+     * @return the result of the reduction
+     * @see #sum()
+     * @see #min()
+     * @see #max()
+     * @see #average()
+     */
+    int reduce(int identity, IntBinaryOperator op);
+
+    /**
+     * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
+     * elements of this stream, using an
+     * <a href="package-summary.html#Associativity">associative</a> accumulation
+     * function, and returns an {@code OptionalInt} describing the reduced value,
+     * if any. This is equivalent to:
+     * <pre>{@code
+     *     boolean foundAny = false;
+     *     int result = null;
+     *     for (int element : this stream) {
+     *         if (!foundAny) {
+     *             foundAny = true;
+     *             result = element;
+     *         }
+     *         else
+     *             result = accumulator.apply(result, element);
+     *     }
+     *     return foundAny ? OptionalInt.of(result) : OptionalInt.empty();
+     * }</pre>
+     *
+     * but is not constrained to execute sequentially.
+     *
+     * <p>The {@code accumulator} function must be an
+     * <a href="package-summary.html#Associativity">associative</a> function.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @param op an <a href="package-summary.html#Associativity">associative</a>
+     *           <a href="package-summary.html#NonInterference">non-interfering,
+     *           stateless</a> function for combining two values
+     * @return the result of the reduction
+     * @see #reduce(int, IntBinaryOperator)
+     */
+    OptionalInt reduce(IntBinaryOperator op);
+
+    /**
+     * Performs a <a href="package-summary.html#MutableReduction">mutable
+     * reduction</a> operation on the elements of this stream.  A mutable
+     * reduction is one in which the reduced value is a mutable value holder,
+     * such as an {@code ArrayList}, and elements are incorporated by updating
+     * the state of the result, rather than by replacing the result.  This
+     * produces a result equivalent to:
+     * <pre>{@code
+     *     R result = resultFactory.get();
+     *     for (int element : this stream)
+     *         accumulator.accept(result, element);
+     *     return result;
+     * }</pre>
+     *
+     * <p>Like {@link #reduce(int, IntBinaryOperator)}, {@code collect} operations
+     * can be parallelized without requiring additional synchronization.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @param <R> type of the result
+     * @param resultFactory a function that creates a new result container.
+     *                      For a parallel execution, this function may be
+     *                      called multiple times and must return a fresh value
+     *                      each time.
+     * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
+     *                    <a href="package-summary.html#NonInterference">non-interfering,
+     *                    stateless</a> function for incorporating an additional
+     *                    element into a result
+     * @param combiner an <a href="package-summary.html#Associativity">associative</a>
+     *                 <a href="package-summary.html#NonInterference">non-interfering,
+     *                 stateless</a> function for combining two values, which
+     *                 must be compatible with the accumulator function
+     * @return the result of the reduction
+     * @see Stream#collect(Supplier, BiConsumer, BiConsumer)
+     */
+    <R> R collect(Supplier<R> resultFactory,
+                  ObjIntConsumer<R> accumulator,
+                  BiConsumer<R, R> combiner);
+
+    /**
+     * Returns the sum of elements in this stream.  This is a special case
+     * of a <a href="package-summary.html#MutableReduction">reduction</a>
+     * and is equivalent to:
+     * <pre>{@code
+     *     return reduce(0, Integer::sum);
+     * }</pre>
+     *
+     * @return the sum of elements in this stream
+     */
+    int sum();
+
+    /**
+     * Returns an {@code OptionalInt} describing the minimum element of this
+     * stream, or an empty optional if this stream is empty.  This is a special
+     * case of a <a href="package-summary.html#MutableReduction">reduction</a>
+     * and is equivalent to:
+     * <pre>{@code
+     *     return reduce(Integer::min);
+     * }</pre>
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+     *
+
+     * @return an {@code OptionalInt} containing the minimum element of this
+     * stream, or an empty {@code OptionalInt} if the stream is empty
+     */
+    OptionalInt min();
+
+    /**
+     * Returns an {@code OptionalInt} describing the maximum element of this
+     * stream, or an empty optional if this stream is empty.  This is a special
+     * case of a <a href="package-summary.html#MutableReduction">reduction</a>
+     * and is equivalent to:
+     * <pre>{@code
+     *     return reduce(Integer::max);
+     * }</pre>
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @return an {@code OptionalInt} containing the maximum element of this
+     * stream, or an empty {@code OptionalInt} if the stream is empty
+     */
+    OptionalInt max();
+
+    /**
+     * Returns the count of elements in this stream.  This is a special case of
+     * a <a href="package-summary.html#MutableReduction">reduction</a> and is
+     * equivalent to:
+     * <pre>{@code
+     *     return mapToLong(e -> 1L).sum();
+     * }</pre>
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+     *
+     * @return the count of elements in this stream
+     */
+    long count();
+
+    /**
+     * Returns an {@code OptionalDouble} describing the average of elements of
+     * this stream, or an empty optional if this stream is empty.  This is a
+     * special case of a
+     * <a href="package-summary.html#MutableReduction">reduction</a>.
+     *
+     * @return an {@code OptionalDouble} containing the average element of this
+     * stream, or an empty optional if the stream is empty
+     */
+    OptionalDouble average();
+
+    /**
+     * Returns an {@code IntSummaryStatistics} describing various
+     * summary data about the elements of this stream.  This is a special
+     * case of a <a href="package-summary.html#MutableReduction">reduction</a>.
+     *
+     * @return an {@code IntSummaryStatistics} describing various summary data
+     * about the elements of this stream
+     */
+    IntSummaryStatistics summaryStatistics();
+
+    /**
+     * Returns whether any elements of this stream match the provided
+     * predicate.  May not evaluate the predicate on all elements if not
+     * necessary for determining the result.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
+     * @return {@code true} if any elements of the stream match the provided
+     * predicate otherwise {@code false}
+     */
+    boolean anyMatch(IntPredicate predicate);
+
+    /**
+     * Returns whether all elements of this stream match the provided predicate.
+     * May not evaluate the predicate on all elements if not necessary for
+     * determining the result.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
+     * @return {@code true} if all elements of the stream match the provided
+     * predicate otherwise {@code false}
+     */
+    boolean allMatch(IntPredicate predicate);
+
+    /**
+     * Returns whether no elements of this stream match the provided predicate.
+     * May not evaluate the predicate on all elements if not necessary for
+     * determining the result.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
+     * @return {@code true} if no elements of the stream match the provided
+     * predicate otherwise {@code false}
+     */
+    boolean noneMatch(IntPredicate predicate);
+
+    /**
+     * Returns an {@link OptionalInt} describing the first element of this
+     * stream (in the encounter order), or an empty {@code OptionalInt} if the
+     * stream is empty.  If the stream has no encounter order, than any element
+     * may be returned.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @return an {@code OptionalInt} describing the first element of this stream,
+     * or an empty {@code OptionalInt} if the stream is empty
+     */
+    OptionalInt findFirst();
+
+    /**
+     * Returns an {@link OptionalInt} describing some element of the stream, or
+     * an empty {@code OptionalInt} if the stream is empty.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * <p>The behavior of this operation is explicitly nondeterministic; it is
+     * free to select any element in the stream.  This is to allow for maximal
+     * performance in parallel operations; the cost is that multiple invocations
+     * on the same source may not return the same result.  (If the first element
+     * in the encounter order is desired, use {@link #findFirst()} instead.)
+     *
+     * @return an {@code OptionalInt} describing some element of this stream, or
+     * an empty {@code OptionalInt} if the stream is empty
+     * @see #findFirst()
+     */
+    OptionalInt findAny();
+
+    /**
+     * Returns a {@code LongStream} consisting of the elements of this stream,
+     * converted to {@code long}.
+     *
+     * @return a {@code LongStream} consisting of the elements of this stream,
+     * converted to {@code long}
+     */
+    LongStream longs();
+
+    /**
+     * Returns a {@code DoubleStream} consisting of the elements of this stream,
+     * converted to {@code double}.
+     *
+     * @return a {@code DoubleStream} consisting of the elements of this stream,
+     * converted to {@code double}
+     */
+    DoubleStream doubles();
+
+    /**
+     * Returns a {@code Stream} consisting of the elements of this stream,
+     * each boxed to an {@code Integer}.
+     *
+     * @return a {@code Stream} consistent of the elements of this stream,
+     * each boxed to an {@code Integer}
+     */
+    Stream<Integer> boxed();
+
+    @Override
+    IntStream sequential();
+
+    @Override
+    IntStream parallel();
+
+    @Override
+    PrimitiveIterator.OfInt iterator();
+
+    @Override
+    Spliterator.OfInt spliterator();
+}

src/share/classes/java/util/stream/LongStream.java

+/*
+ * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.util.stream;
+
+import java.util.LongSummaryStatistics;
+import java.util.OptionalDouble;
+import java.util.OptionalLong;
+import java.util.PrimitiveIterator;
+import java.util.Spliterator;
+import java.util.function.BiConsumer;
+import java.util.function.Function;
+import java.util.function.LongBinaryOperator;
+import java.util.function.LongConsumer;
+import java.util.function.LongFunction;
+import java.util.function.LongPredicate;
+import java.util.function.LongToDoubleFunction;
+import java.util.function.LongToIntFunction;
+import java.util.function.LongUnaryOperator;
+import java.util.function.ObjLongConsumer;
+import java.util.function.Supplier;
+
+/**
+ * A sequence of primitive long elements supporting sequential and parallel
+ * bulk operations. Streams support lazy intermediate operations (transforming
+ * a stream to another stream) such as {@code filter} and {@code map}, and terminal
+ * operations (consuming the contents of a stream to produce a result or
+ * side-effect), such as {@code forEach}, {@code findFirst}, and {@code
+ * iterator}.  Once an operation has been performed on a stream, it
+ * is considered <em>consumed</em> and no longer usable for other operations.
+ *
+ * <p>For sequential stream pipelines, all operations are performed in the
+ * <a href="package-summary.html#Ordering">encounter order</a> of the pipeline
+ * source, if the pipeline source has a defined encounter order.
+ *
+ * <p>For parallel stream pipelines, unless otherwise specified, intermediate
+ * stream operations preserve the <a href="package-summary.html#Ordering">
+ * encounter order</a> of their source, and terminal operations
+ * respect the encounter order of their source, if the source
+ * has an encounter order.  Provided that and parameters to stream operations
+ * satisfy the <a href="package-summary.html#NonInterference">non-interference
+ * requirements</a>, and excepting differences arising from the absence of
+ * a defined encounter order, the result of a stream pipeline should be the
+ * stable across multiple executions of the same operations on the same source.
+ * However, the timing and thread in which side-effects occur (for those
+ * operations which are allowed to produce side-effects, such as
+ * {@link #forEach(LongConsumer)}), are explicitly nondeterministic for parallel
+ * execution of stream pipelines.
+ *
+ * <p>Unless otherwise noted, passing a {@code null} argument to any stream
+ * method may result in a {@link NullPointerException}.
+ *
+ * @apiNote
+ * Streams are not data structures; they do not manage the storage for their
+ * elements, nor do they support access to individual elements.  However,
+ * you can use the {@link #iterator()} or {@link #spliterator()} operations to
+ * perform a controlled traversal.
+ *
+ * @since 1.8
+ * @see <a href="package-summary.html">java.util.stream</a>
+ */
+public interface LongStream extends BaseStream<Long, LongStream> {
+
+    /**
+     * Returns a stream consisting of the elements of this stream that match
+     * the given predicate.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">
+     *                  non-interfering, stateless</a> predicate to apply to
+     *                  each element to determine if it should be included
+     * @return the new stream
+     */
+    LongStream filter(LongPredicate predicate);
+
+    /**
+     * Returns a stream consisting of the results of applying the given
+     * function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    LongStream map(LongUnaryOperator mapper);
+
+    /**
+     * Returns an object-valued {@code Stream} consisting of the results of
+     * applying the given function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">
+     *     intermediate operation</a>.
+     *
+     * @param <U> the element type of the new stream
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    <U> Stream<U> mapToObj(LongFunction<? extends U> mapper);
+
+    /**
+     * Returns an {@code IntStream} consisting of the results of applying the
+     * given function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    IntStream mapToInt(LongToIntFunction mapper);
+
+    /**
+     * Returns a {@code DoubleStream} consisting of the results of applying the
+     * given function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    DoubleStream mapToDouble(LongToDoubleFunction mapper);
+
+    /**
+     * Returns a stream consisting of the results of replacing each element of
+     * this stream with the contents of the stream produced by applying the
+     * provided mapping function to each element.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @apiNote
+     * The {@code flatMap()} operation has the effect of applying a one-to-many
+     * tranformation to the elements of the stream, and then flattening the
+     * resulting elements into a new stream. For example, if {@code orders}
+     * is a stream of purchase orders, and each purchase order contains a
+     * collection of line items, then the following produces a stream of line
+     * items:
+     * <pre>{@code
+     *     orderStream.flatMap(order -> order.getLineItems().stream())...
+     * }</pre>
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to
+     *               each element which produces an {@code LongStream} of new
+     *               values
+     * @return the new stream
+     * @see Stream#flatMap(Function)
+     */
+    LongStream flatMap(LongFunction<? extends LongStream> mapper);
+
+    /**
+     * Returns a stream consisting of the distinct elements of this stream.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">stateful
+     * intermediate operation</a>.
+     *
+     * @return the new stream
+     */
+    LongStream distinct();
+
+    /**
+     * Returns a stream consisting of the elements of this stream in sorted
+     * order.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">stateful
+     * intermediate operation</a>.
+     *
+     * @return the new stream
+     */
+    LongStream sorted();
+
+    /**
+     * Returns a stream consisting of the elements of this stream, additionally
+     * performing the provided action on each element as elements are consumed
+     * from the resulting stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * <p>For parallel stream pipelines, the action may be called at
+     * whatever time and in whatever thread the element is made available by the
+     * upstream operation.  If the action modifies shared state,
+     * it is responsible for providing the required synchronization.
+     *
+     * @apiNote This method exists mainly to support debugging, where you want
+     * to see the elements as they flow past a certain point in a pipeline:
+     * <pre>{@code
+     *     list.stream()
+     *         .filter(filteringFunction)
+     *         .peek(e -> {System.out.println("Filtered value: " + e); });
+     *         .map(mappingFunction)
+     *         .peek(e -> {System.out.println("Mapped value: " + e); });
+     *         .collect(Collectors.toLongSummaryStastistics());
+     * }</pre>
+     *
+     * @param consumer a <a href="package-summary.html#NonInterference">
+     *                 non-interfering</a> action to perform on the elements as
+     *                 they are consumed from the stream
+     * @return the new stream
+     */
+    LongStream peek(LongConsumer consumer);
+
+    /**
+     * Returns a stream consisting of the elements of this stream, truncated
+     * to be no longer than {@code maxSize} in length.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * stateful intermediate operation</a>.
+     *
+     * @param maxSize the number of elements the stream should be limited to
+     * @return the new stream
+     * @throws IllegalArgumentException if {@code maxSize} is negative
+     */
+    LongStream limit(long maxSize);
+
+    /**
+     * Returns a stream consisting of the remaining elements of this stream
+     * after indexing {@code startInclusive} elements into the stream. If the
+     * {@code startInclusive} index lies past the end of this stream then an
+     * empty stream will be returned.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">stateful
+     * intermediate operation</a>.
+     *
+     * @param startInclusive the number of leading elements to skip
+     * @return the new stream
+     * @throws IllegalArgumentException if {@code startInclusive} is negative
+     */
+    LongStream substream(long startInclusive);
+
+    /**
+     * Returns a stream consisting of the remaining elements of this stream
+     * after indexing {@code startInclusive} elements into the stream and
+     * truncated to contain no more than {@code endExclusive - startInclusive}
+     * elements. If the {@code startInclusive} index lies past the end
+     * of this stream then an empty stream will be returned.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * stateful intermediate operation</a>.
+     *
+     * @param startInclusive the starting position of the substream, inclusive
+     * @param endExclusive the ending position of the substream, exclusive
+     * @return the new stream
+     * @throws IllegalArgumentException if {@code startInclusive} or
+     * {@code endExclusive} is negative or {@code startInclusive} is greater
+     * than {@code endExclusive}
+     */
+    LongStream substream(long startInclusive, long endExclusive);
+
+    /**
+     * Performs an action for each element of this stream.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * <p>For parallel stream pipelines, this operation does <em>not</em>
+     * guarantee to respect the encounter order of the stream, as doing so
+     * would sacrifice the benefit of parallelism.  For any given element, the
+     * action may be performed at whatever time and in whatever thread the
+     * library chooses.  If the action accesses shared state, it is
+     * responsible for providing the required synchronization.
+     *
+     * @param action a <a href="package-summary.html#NonInterference">
+     *               non-interfering</a> action to perform on the elements
+     */
+    void forEach(LongConsumer action);
+
+    /**
+     * Performs an action for each element of this stream, guaranteeing that
+     * each element is processed in encounter order for streams that have a
+     * defined encounter order.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @param action a <a href="package-summary.html#NonInterference">
+     *               non-interfering</a> action to perform on the elements
+     * @see #forEach(LongConsumer)
+     */
+    void forEachOrdered(LongConsumer action);
+
+    /**
+     * Returns an array containing the elements of this stream.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @return an array containing the elements of this stream
+     */
+    long[] toArray();
+
+    /**
+     * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
+     * elements of this stream, using the provided identity value and an
+     * <a href="package-summary.html#Associativity">associative</a>
+     * accumulation function, and returns the reduced value.  This is equivalent
+     * to:
+     * <pre>{@code
+     *     long result = identity;
+     *     for (long element : this stream)
+     *         result = accumulator.apply(result, element)
+     *     return result;
+     * }</pre>
+     *
+     * but is not constrained to execute sequentially.
+     *
+     * <p>The {@code identity} value must be an identity for the accumulator
+     * function. This means that for all {@code x},
+     * {@code accumulator.apply(identity, x)} is equal to {@code x}.
+     * The {@code accumulator} function must be an
+     * <a href="package-summary.html#Associativity">associative</a> function.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @apiNote Sum, min, max, and average are all special cases of reduction.
+     * Summing a stream of numbers can be expressed as:
+     *
+     * <pre>{@code
+     *     long sum = integers.reduce(0, (a, b) -> a+b);
+     * }</pre>
+     *
+     * or more compactly:
+     *
+     * <pre>{@code
+     *     long sum = integers.reduce(0, Long::sum);
+     * }</pre>
+     *
+     * <p>While this may seem a more roundabout way to perform an aggregation
+     * compared to simply mutating a running total in a loop, reduction
+     * operations parallelize more gracefully, without needing additional
+     * synchronization and with greatly reduced risk of data races.
+     *
+     * @param identity the identity value for the accumulating function
+     * @param op an <a href="package-summary.html#Associativity">associative</a>
+     *                    <a href="package-summary.html#NonInterference">non-interfering,
+     *                    stateless</a> function for combining two values
+     * @return the result of the reduction
+     * @see #sum()
+     * @see #min()
+     * @see #max()
+     * @see #average()
+     */
+    long reduce(long identity, LongBinaryOperator op);
+
+    /**
+     * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
+     * elements of this stream, using an
+     * <a href="package-summary.html#Associativity">associative</a> accumulation
+     * function, and returns an {@code OptionalLong} describing the reduced value,
+     * if any. This is equivalent to:
+     * <pre>{@code
+     *     boolean foundAny = false;
+     *     long result = null;
+     *     for (long element : this stream) {
+     *         if (!foundAny) {
+     *             foundAny = true;
+     *             result = element;
+     *         }
+     *         else
+     *             result = accumulator.apply(result, element);
+     *     }
+     *     return foundAny ? OptionalLong.of(result) : OptionalLong.empty();
+     * }</pre>
+     *
+     * but is not constrained to execute sequentially.
+     *
+     * <p>The {@code accumulator} function must be an
+     * <a href="package-summary.html#Associativity">associative</a> function.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @param op an <a href="package-summary.html#Associativity">associative</a>
+     *           <a href="package-summary.html#NonInterference">non-interfering,
+     *           stateless</a> function for combining two values
+     * @return the result of the reduction
+     * @see #reduce(long, LongBinaryOperator)
+     */
+    OptionalLong reduce(LongBinaryOperator op);
+
+    /**
+     * Performs a <a href="package-summary.html#MutableReduction">mutable
+     * reduction</a> operation on the elements of this stream.  A mutable
+     * reduction is one in which the reduced value is a mutable value holder,
+     * such as an {@code ArrayList}, and elements are incorporated by updating
+     * the state of the result, rather than by replacing the result.  This
+     * produces a result equivalent to:
+     * <pre>{@code
+     *     R result = resultFactory.get();
+     *     for (long element : this stream)
+     *         accumulator.accept(result, element);
+     *     return result;
+     * }</pre>
+     *
+     * <p>Like {@link #reduce(long, LongBinaryOperator)}, {@code collect} operations
+     * can be parallelized without requiring additional synchronization.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @param <R> type of the result
+     * @param resultFactory a function that creates a new result container.
+     *                      For a parallel execution, this function may be
+     *                      called multiple times and must return a fresh value
+     *                      each time.
+     * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
+     *                    <a href="package-summary.html#NonInterference">non-interfering,
+     *                    stateless</a> function for incorporating an additional
+     *                    element into a result
+     * @param combiner an <a href="package-summary.html#Associativity">associative</a>
+     *                 <a href="package-summary.html#NonInterference">non-interfering,
+     *                 stateless</a> function for combining two values, which
+     *                 must be compatible with the accumulator function
+     * @return the result of the reduction
+     * @see Stream#collect(Supplier, BiConsumer, BiConsumer)
+     */
+    <R> R collect(Supplier<R> resultFactory,
+                  ObjLongConsumer<R> accumulator,
+                  BiConsumer<R, R> combiner);
+
+    /**
+     * Returns the sum of elements in this stream.  This is a special case
+     * of a <a href="package-summary.html#MutableReduction">reduction</a>
+     * and is equivalent to:
+     * <pre>{@code
+     *     return reduce(0, Long::sum);
+     * }</pre>
+     *
+     * @return the sum of elements in this stream
+     */
+    long sum();
+
+    /**
+     * Returns an {@code OptionalLong} describing the minimum element of this
+     * stream, or an empty optional if this stream is empty.  This is a special
+     * case of a <a href="package-summary.html#MutableReduction">reduction</a>
+     * and is equivalent to:
+     * <pre>{@code
+     *     return reduce(Long::min);
+     * }</pre>
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+     *
+
+     * @return an {@code OptionalLong} containing the minimum element of this
+     * stream, or an empty {@code OptionalLong} if the stream is empty
+     */
+    OptionalLong min();
+
+    /**
+     * Returns an {@code OptionalLong} describing the maximum element of this
+     * stream, or an empty optional if this stream is empty.  This is a special
+     * case of a <a href="package-summary.html#MutableReduction">reduction</a>
+     * and is equivalent to:
+     * <pre>{@code
+     *     return reduce(Long::max);
+     * }</pre>
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @return an {@code OptionalLong} containing the maximum element of this
+     * stream, or an empty {@code OptionalLong} if the stream is empty
+     */
+    OptionalLong max();
+
+    /**
+     * Returns the count of elements in this stream.  This is a special case of
+     * a <a href="package-summary.html#MutableReduction">reduction</a> and is
+     * equivalent to:
+     * <pre>{@code
+     *     return map(e -> 1L).sum();
+     * }</pre>
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+     *
+     * @return the count of elements in this stream
+     */
+    long count();
+
+    /**
+     * Returns an {@code OptionalDouble} describing the average of elements of
+     * this stream, or an empty optional if this stream is empty.  This is a
+     * special case of a
+     * <a href="package-summary.html#MutableReduction">reduction</a>.
+     *
+     * @return an {@code OptionalDouble} containing the average element of this
+     * stream, or an empty optional if the stream is empty
+     */
+    OptionalDouble average();
+
+    /**
+     * Returns a {@code LongSummaryStatistics} describing various summary data
+     * about the elements of this stream.  This is a special case of a
+     * <a href="package-summary.html#MutableReduction">reduction</a>.
+     *
+     * @return a {@code LongSummaryStatistics} describing various summary data
+     * about the elements of this stream
+     */
+    LongSummaryStatistics summaryStatistics();
+
+    /**
+     * Returns whether any elements of this stream match the provided
+     * predicate.  May not evaluate the predicate on all elements if not
+     * necessary for determining the result.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
+     * @return {@code true} if any elements of the stream match the provided
+     * predicate otherwise {@code false}
+     */
+    boolean anyMatch(LongPredicate predicate);
+
+    /**
+     * Returns whether all elements of this stream match the provided predicate.
+     * May not evaluate the predicate on all elements if not necessary for
+     * determining the result.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
+     * @return {@code true} if all elements of the stream match the provided
+     * predicate otherwise {@code false}
+     */
+    boolean allMatch(LongPredicate predicate);
+
+    /**
+     * Returns whether no elements of this stream match the provided  predicate.
+     * May not evaluate the predicate on all elements if not necessary for
+     * determining the result.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
+     * @return {@code true} if no elements of the stream match the provided
+     * predicate otherwise {@code false}
+     */
+    boolean noneMatch(LongPredicate predicate);
+
+    /**
+     * Returns an {@link OptionalLong} describing the first element of this
+     * stream (in the encounter order), or an empty {@code OptionalLong} if the
+     * stream is empty.  If the stream has no encounter order, than any element
+     * may be returned.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @return an {@code OptionalLong} describing the first element of this
+     * stream, or an empty {@code OptionalLong} if the stream is empty
+     */
+    OptionalLong findFirst();
+
+    /**
+     * Returns an {@link OptionalLong} describing some element of the stream, or
+     * an empty {@code OptionalLong} if the stream is empty.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * <p>The behavior of this operation is explicitly nondeterministic; it is
+     * free to select any element in the stream.  This is to allow for maximal
+     * performance in parallel operations; the cost is that multiple invocations
+     * on the same source may not return the same result.  (If the first element
+     * in the encounter order is desired, use {@link #findFirst()} instead.)
+     *
+     * @return an {@code OptionalLong} describing some element of this stream,
+     * or an empty {@code OptionalLong} if the stream is empty
+     * @see #findFirst()
+     */
+    OptionalLong findAny();
+
+    /**
+     * Returns a {@code DoubleStream} consisting of the elements of this stream,
+     * converted to {@code double}.
+     *
+     * @return a {@code DoubleStream} consisting of the elements of this stream,
+     * converted to {@code double}
+     */
+    DoubleStream doubles();
+
+    /**
+     * Returns a {@code Stream} consisting of the elements of this stream,
+     * each boxed to a {@code Long}.
+     *
+     * @return a {@code Stream} consistent of the elements of this stream,
+     * each boxed to {@code Long}
+     */
+    Stream<Long> boxed();
+
+    @Override
+    LongStream sequential();
+
+    @Override
+    LongStream parallel();
+
+    @Override
+    PrimitiveIterator.OfLong iterator();
+
+    @Override
+    Spliterator.OfLong spliterator();
+}

src/share/classes/java/util/stream/Stream.java

+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.util.stream;
+
+import java.util.Comparator;
+import java.util.Optional;
+import java.util.function.BiConsumer;
+import java.util.function.BiFunction;
+import java.util.function.BinaryOperator;
+import java.util.function.Consumer;
+import java.util.function.Function;
+import java.util.function.IntFunction;
+import java.util.function.Predicate;
+import java.util.function.Supplier;
+import java.util.function.ToDoubleFunction;
+import java.util.function.ToIntFunction;
+import java.util.function.ToLongFunction;
+
+// @@@ Specification to-do list @@@
+// - Describe the difference between sequential and parallel streams
+// - More general information about reduce, better definitions for associativity, more description of
+//   how reduce employs parallelism, more examples
+// - Role of stream flags in various operations, specifically ordering
+//   - Whether each op preserves encounter order
+// @@@ Specification to-do list @@@
+
+/**
+ * A sequence of elements supporting sequential and parallel bulk operations.
+ * Streams support lazy intermediate operations (transforming a stream to
+ * another stream) such as {@code filter} and {@code map}, and terminal
+ * operations (consuming the contents of a stream to produce a result or
+ * side-effect), such as {@code forEach}, {@code findFirst}, and {@code
+ * iterator}.  Once an operation has been performed on a stream, it
+ * is considered <em>consumed</em> and no longer usable for other operations.
+ *
+ * <p>For sequential stream pipelines, all operations are performed in the
+ * <a href="package-summary.html#Ordering">encounter order</a> of the pipeline
+ * source, if the pipeline source has a defined encounter order.
+ *
+ * <p>For parallel stream pipelines, unless otherwise specified, intermediate
+ * stream operations preserve the <a href="package-summary.html#Ordering">
+ * encounter order</a> of their source, and terminal operations
+ * respect the encounter order of their source, if the source
+ * has an encounter order.  Provided that and parameters to stream operations
+ * satisfy the <a href="package-summary.html#NonInterference">non-interference
+ * requirements</a>, and excepting differences arising from the absence of
+ * a defined encounter order, the result of a stream pipeline should be the
+ * stable across multiple executions of the same operations on the same source.
+ * However, the timing and thread in which side-effects occur (for those
+ * operations which are allowed to produce side-effects, such as
+ * {@link #forEach(Consumer)}), are explicitly nondeterministic for parallel
+ * execution of stream pipelines.
+ *
+ * <p>Unless otherwise noted, passing a {@code null} argument to any stream
+ * method may result in a {@link NullPointerException}.
+ *
+ * @apiNote
+ * Streams are not data structures; they do not manage the storage for their
+ * elements, nor do they support access to individual elements.  However,
+ * you can use the {@link #iterator()} or {@link #spliterator()} operations to
+ * perform a controlled traversal.
+ *
+ * @param <T> type of elements
+ * @since 1.8
+ * @see <a href="package-summary.html">java.util.stream</a>
+ */
+public interface Stream<T> extends BaseStream<T, Stream<T>> {
+
+    /**
+     * Returns a stream consisting of the elements of this stream that match
+     * the given predicate.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">
+     *                  non-interfering, stateless</a> predicate to apply to
+     *                  each element to determine if it should be included
+     * @return the new stream
+     */
+    Stream<T> filter(Predicate<? super T> predicate);
+
+    /**
+     * Returns a stream consisting of the results of applying the given
+     * function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param <R> The element type of the new stream
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    <R> Stream<R> map(Function<? super T, ? extends R> mapper);
+
+    /**
+     * Returns an {@code IntStream} consisting of the results of applying the
+     * given function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">
+     *     intermediate operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    IntStream mapToInt(ToIntFunction<? super T> mapper);
+
+    /**
+     * Returns a {@code LongStream} consisting of the results of applying the
+     * given function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    LongStream mapToLong(ToLongFunction<? super T> mapper);
+
+    /**
+     * Returns a {@code DoubleStream} consisting of the results of applying the
+     * given function to the elements of this stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element
+     * @return the new stream
+     */
+    DoubleStream mapToDouble(ToDoubleFunction<? super T> mapper);
+
+    /**
+     * Returns a stream consisting of the results of replacing each element of
+     * this stream with the contents of the stream produced by applying the
+     * provided mapping function to each element.  If the result of the mapping
+     * function is {@code null}, this is treated as if the result is an empty
+     * stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @apiNote
+     * The {@code flatMap()} operation has the effect of applying a one-to-many
+     * tranformation to the elements of the stream, and then flattening the
+     * resulting elements into a new stream. For example, if {@code orders}
+     * is a stream of purchase orders, and each purchase order contains a
+     * collection of line items, then the following produces a stream of line
+     * items:
+     * <pre>{@code
+     *     orderStream.flatMap(order -> order.getLineItems().stream())...
+     * }</pre>
+     *
+     * @param <R> The element type of the new stream
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element which produces a stream of new values
+     * @return the new stream
+     */
+    <R> Stream<R> flatMap(Function<? super T, ? extends Stream<? extends R>> mapper);
+
+    /**
+     * Returns an {@code IntStream} consisting of the results of replacing each
+     * element of this stream with the contents of the stream produced by
+     * applying the provided mapping function to each element.  If the result of
+     * the mapping function is {@code null}, this is treated as if the result is
+     * an empty stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element which produces a stream of new values
+     * @return the new stream
+     */
+    IntStream flatMapToInt(Function<? super T, ? extends IntStream> mapper);
+
+    /**
+     * Returns a {@code LongStream} consisting of the results of replacing each
+     * element of this stream with the contents of the stream produced
+     * by applying the provided mapping function to each element.  If the result
+     * of the mapping function is {@code null}, this is treated as if the
+     * result is an empty stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to
+     *               each element which produces a stream of new values
+     * @return the new stream
+     */
+    LongStream flatMapToLong(Function<? super T, ? extends LongStream> mapper);
+
+    /**
+     * Returns a {@code DoubleStream} consisting of the results of replacing each
+     * element of this stream with the contents of the stream produced
+     * by applying the provided mapping function to each element.  If the result
+     * of the mapping function is {@code null}, this is treated as if the result
+     * is an empty stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * @param mapper a <a href="package-summary.html#NonInterference">
+     *               non-interfering, stateless</a> function to apply to each
+     *               element which produces a stream of new values
+     * @return the new stream
+     */
+    DoubleStream flatMapToDouble(Function<? super T, ? extends DoubleStream> mapper);
+
+    /**
+     * Returns a stream consisting of the distinct elements (according to
+     * {@link Object#equals(Object)}) of this stream.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">stateful
+     * intermediate operation</a>.
+     *
+     * @return the new stream
+     */
+    Stream<T> distinct();
+
+    /**
+     * Returns a stream consisting of the elements of this stream, sorted
+     * according to natural order.  If the elements of this stream are not
+     * {@code Comparable}, a {@code java.lang.ClassCastException} may be thrown
+     * when the stream pipeline is executed.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">stateful
+     * intermediate operation</a>.
+     *
+     * @return the new stream
+     */
+    Stream<T> sorted();
+
+    /**
+     * Returns a stream consisting of the elements of this stream, sorted
+     * according to the provided {@code Comparator}.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">stateful
+     * intermediate operation</a>.
+     *
+     * @param comparator a <a href="package-summary.html#NonInterference">
+     *                   non-interfering, stateless</a> {@code Comparator} to
+     *                   be used to compare stream elements
+     * @return the new stream
+     */
+    Stream<T> sorted(Comparator<? super T> comparator);
+
+    /**
+     * Returns a stream consisting of the elements of this stream, additionally
+     * performing the provided action on each element as elements are consumed
+     * from the resulting stream.
+     *
+     * <p>This is an <a href="package-summary.html#StreamOps">intermediate
+     * operation</a>.
+     *
+     * <p>For parallel stream pipelines, the action may be called at
+     * whatever time and in whatever thread the element is made available by the
+     * upstream operation.  If the action modifies shared state,
+     * it is responsible for providing the required synchronization.
+     *
+     * @apiNote This method exists mainly to support debugging, where you want
+     * to see the elements as they flow past a certain point in a pipeline:
+     * <pre>{@code
+     *     list.stream()
+     *         .filter(filteringFunction)
+     *         .peek(e -> {System.out.println("Filtered value: " + e); });
+     *         .map(mappingFunction)
+     *         .peek(e -> {System.out.println("Mapped value: " + e); });
+     *         .collect(Collectors.intoList());
+     * }</pre>
+     *
+     * @param consumer a <a href="package-summary.html#NonInterference">
+     *                 non-interfering</a> action to perform on the elements as
+     *                 they are consumed from the stream
+     * @return the new stream
+     */
+    Stream<T> peek(Consumer<? super T> consumer);
+
+    /**
+     * Returns a stream consisting of the elements of this stream, truncated
+     * to be no longer than {@code maxSize} in length.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * stateful intermediate operation</a>.
+     *
+     * @param maxSize the number of elements the stream should be limited to
+     * @return the new stream
+     * @throws IllegalArgumentException if {@code maxSize} is negative
+     */
+    Stream<T> limit(long maxSize);
+
+    /**
+     * Returns a stream consisting of the remaining elements of this stream
+     * after indexing {@code startInclusive} elements into the stream. If the
+     * {@code startInclusive} index lies past the end of this stream then an
+     * empty stream will be returned.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">stateful
+     * intermediate operation</a>.
+     *
+     * @param startInclusive the number of leading elements to skip
+     * @return the new stream
+     * @throws IllegalArgumentException if {@code startInclusive} is negative
+     */
+    Stream<T> substream(long startInclusive);
+
+    /**
+     * Returns a stream consisting of the remaining elements of this stream
+     * after indexing {@code startInclusive} elements into the stream and
+     * truncated to contain no more than {@code endExclusive - startInclusive}
+     * elements. If the {@code startInclusive} index lies past the end
+     * of this stream then an empty stream will be returned.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * stateful intermediate operation</a>.
+     *
+     * @param startInclusive the starting position of the substream, inclusive
+     * @param endExclusive the ending position of the substream, exclusive
+     * @return the new stream
+     * @throws IllegalArgumentException if {@code startInclusive} or
+     * {@code endExclusive} is negative or {@code startInclusive} is greater
+     * than {@code endExclusive}
+     */
+    Stream<T> substream(long startInclusive, long endExclusive);
+
+    /**
+     * Performs an action for each element of this stream.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * <p>For parallel stream pipelines, this operation does <em>not</em>
+     * guarantee to respect the encounter order of the stream, as doing so
+     * would sacrifice the benefit of parallelism.  For any given element, the
+     * action may be performed at whatever time and in whatever thread the
+     * library chooses.  If the action accesses shared state, it is
+     * responsible for providing the required synchronization.
+     *
+     * @param action a <a href="package-summary.html#NonInterference">
+     *               non-interfering</a> action to perform on the elements
+     */
+    void forEach(Consumer<? super T> action);
+
+    /**
+     * Performs an action for each element of this stream, guaranteeing that
+     * each element is processed in encounter order for streams that have a
+     * defined encounter order.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @param action a <a href="package-summary.html#NonInterference">
+     *               non-interfering</a> action to perform on the elements
+     * @see #forEach(Consumer)
+     */
+    void forEachOrdered(Consumer<? super T> action);
+
+    /**
+     * Returns an array containing the elements of this stream.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @return an array containing the elements of this stream
+     */
+    Object[] toArray();
+
+    /**
+     * Returns an array containing the elements of this stream, using the
+     * provided {@code generator} function to allocate the returned array.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @param <A> the element type of the resulting array
+     * @param generator a function which produces a new array of the desired
+     *                  type and the provided length
+     * @return an array containing the elements in this stream
+     * @throws ArrayStoreException if the runtime type of the array returned
+     * from the array generator is not a supertype of the runtime type of every
+     * element in this stream
+     */
+    <A> A[] toArray(IntFunction<A[]> generator);
+
+    /**
+     * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
+     * elements of this stream, using the provided identity value and an
+     * <a href="package-summary.html#Associativity">associative</a>
+     * accumulation function, and returns the reduced value.  This is equivalent
+     * to:
+     * <pre>{@code
+     *     T result = identity;
+     *     for (T element : this stream)
+     *         result = accumulator.apply(result, element)
+     *     return result;
+     * }</pre>
+     *
+     * but is not constrained to execute sequentially.
+     *
+     * <p>The {@code identity} value must be an identity for the accumulator
+     * function. This means that for all {@code t},
+     * {@code accumulator.apply(identity, t)} is equal to {@code t}.
+     * The {@code accumulator} function must be an
+     * <a href="package-summary.html#Associativity">associative</a> function.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @apiNote Sum, min, max, average, and string concatenation are all special
+     * cases of reduction. Summing a stream of numbers can be expressed as:
+     *
+     * <pre>{@code
+     *     Integer sum = integers.reduce(0, (a, b) -> a+b);
+     * }</pre>
+     *
+     * or more compactly:
+     *
+     * <pre>{@code
+     *     Integer sum = integers.reduce(0, Integer::sum);
+     * }</pre>
+     *
+     * <p>While this may seem a more roundabout way to perform an aggregation
+     * compared to simply mutating a running total in a loop, reduction
+     * operations parallelize more gracefully, without needing additional
+     * synchronization and with greatly reduced risk of data races.
+     *
+     * @param identity the identity value for the accumulating function
+     * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
+     *                    <a href="package-summary.html#NonInterference">non-interfering,
+     *                    stateless</a> function for combining two values
+     * @return the result of the reduction
+     */
+    T reduce(T identity, BinaryOperator<T> accumulator);
+
+    /**
+     * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
+     * elements of this stream, using an
+     * <a href="package-summary.html#Associativity">associative</a> accumulation
+     * function, and returns an {@code Optional} describing the reduced value,
+     * if any. This is equivalent to:
+     * <pre>{@code
+     *     boolean foundAny = false;
+     *     T result = null;
+     *     for (T element : this stream) {
+     *         if (!foundAny) {
+     *             foundAny = true;
+     *             result = element;
+     *         }
+     *         else
+     *             result = accumulator.apply(result, element);
+     *     }
+     *     return foundAny ? Optional.of(result) : Optional.empty();
+     * }</pre>
+     *
+     * but is not constrained to execute sequentially.
+     *
+     * <p>The {@code accumulator} function must be an
+     * <a href="package-summary.html#Associativity">associative</a> function.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
+     *                    <a href="package-summary.html#NonInterference">non-interfering,
+     *                    stateless</a> function for combining two values
+     * @return the result of the reduction
+     * @see #reduce(Object, BinaryOperator)
+     * @see #min(java.util.Comparator)
+     * @see #max(java.util.Comparator)
+     */
+    Optional<T> reduce(BinaryOperator<T> accumulator);
+
+    /**
+     * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
+     * elements of this stream, using the provided identity, accumulation
+     * function, and a combining functions.  This is equivalent to:
+     * <pre>{@code
+     *     U result = identity;
+     *     for (T element : this stream)
+     *         result = accumulator.apply(result, element)
+     *     return result;
+     * }</pre>
+     *
+     * but is not constrained to execute sequentially.
+     *
+     * <p>The {@code identity} value must be an identity for the combiner
+     * function.  This means that for all {@code u}, {@code combiner(identity, u)}
+     * is equal to {@code u}.  Additionally, the {@code combiner} function
+     * must be compatible with the {@code accumulator} function; for all
+     * {@code u} and {@code t}, the following must hold:
+     * <pre>{@code
+     *     combiner.apply(u, accumulator.apply(identity, t)) == accumulator.apply(u, t)
+     * }</pre>
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @apiNote Many reductions using this form can be represented more simply
+     * by an explicit combination of {@code map} and {@code reduce} operations.
+     * The {@code accumulator} function acts as a fused mapper and accumulator,
+     * which can sometimes be more efficient than separate mapping and reduction,
+     * such as in the case where knowing the previously reduced value allows you
+     * to avoid some computation.
+     *
+     * @param <U> The type of the result
+     * @param identity the identity value for the combiner function
+     * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
+     *                    <a href="package-summary.html#NonInterference">non-interfering,
+     *                    stateless</a> function for incorporating an additional
+     *                    element into a result
+     * @param combiner an <a href="package-summary.html#Associativity">associative</a>
+     *                 <a href="package-summary.html#NonInterference">non-interfering,
+     *                 stateless</a> function for combining two values, which
+     *                 must be compatible with the accumulator function
+     * @return the result of the reduction
+     * @see #reduce(BinaryOperator)
+     * @see #reduce(Object, BinaryOperator)
+     */
+    <U> U reduce(U identity,
+                 BiFunction<U, ? super T, U> accumulator,
+                 BinaryOperator<U> combiner);
+
+    /**
+     * Performs a <a href="package-summary.html#MutableReduction">mutable
+     * reduction</a> operation on the elements of this stream.  A mutable
+     * reduction is one in which the reduced value is a mutable value holder,
+     * such as an {@code ArrayList}, and elements are incorporated by updating
+     * the state of the result, rather than by replacing the result.  This
+     * produces a result equivalent to:
+     * <pre>{@code
+     *     R result = resultFactory.get();
+     *     for (T element : this stream)
+     *         accumulator.accept(result, element);
+     *     return result;
+     * }</pre>
+     *
+     * <p>Like {@link #reduce(Object, BinaryOperator)}, {@code collect} operations
+     * can be parallelized without requiring additional synchronization.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @apiNote There are many existing classes in the JDK whose signatures are
+     * a good match for use as arguments to {@code collect()}.  For example,
+     * the following will accumulate strings into an ArrayList:
+     * <pre>{@code
+     *     List<String> asList = stringStream.collect(ArrayList::new, ArrayList::add, ArrayList::addAll);
+     * }</pre>
+     *
+     * <p>The following will take a stream of strings and concatenates them into a
+     * single string:
+     * <pre>{@code
+     *     String concat = stringStream.collect(StringBuilder::new, StringBuilder::append,
+     *                                          StringBuilder::append)
+     *                                 .toString();
+     * }</pre>
+     *
+     * @param <R> type of the result
+     * @param resultFactory a function that creates a new result container.
+     *                      For a parallel execution, this function may be
+     *                      called multiple times and must return a fresh value
+     *                      each time.
+     * @param accumulator an <a href="package-summary.html#Associativity">associative</a>
+     *                    <a href="package-summary.html#NonInterference">non-interfering,
+     *                    stateless</a> function for incorporating an additional
+     *                    element into a result
+     * @param combiner an <a href="package-summary.html#Associativity">associative</a>
+     *                 <a href="package-summary.html#NonInterference">non-interfering,
+     *                 stateless</a> function for combining two values, which
+     *                 must be compatible with the accumulator function
+     * @return the result of the reduction
+     */
+    <R> R collect(Supplier<R> resultFactory,
+                  BiConsumer<R, ? super T> accumulator,
+                  BiConsumer<R, R> combiner);
+
+    /**
+     * Performs a <a href="package-summary.html#MutableReduction">mutable
+     * reduction</a> operation on the elements of this stream using a
+     * {@code Collector} object to describe the reduction.  A {@code Collector}
+     * encapsulates the functions used as arguments to
+     * {@link #collect(Supplier, BiConsumer, BiConsumer)}, allowing for reuse of
+     * collection strategies, and composition of collect operations such as
+     * multiple-level grouping or partitioning.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * <p>When executed in parallel, multiple intermediate results may be
+     * instantiated, populated, and merged, so as to maintain isolation of
+     * mutable data structures.  Therefore, even when executed in parallel
+     * with non-thread-safe data structures (such as {@code ArrayList}), no
+     * additional synchronization is needed for a parallel reduction.
+     *
+     * @apiNote
+     * The following will accumulate strings into an ArrayList:
+     * <pre>{@code
+     *     List<String> asList = stringStream.collect(Collectors.toList());
+     * }</pre>
+     *
+     * <p>The following will classify {@code Person} objects by city:
+     * <pre>{@code
+     *     Map<String, Collection<Person>> peopleByCity
+     *         = personStream.collect(Collectors.groupBy(Person::getCity));
+     * }</pre>
+     *
+     * <p>The following will classify {@code Person} objects by state and city,
+     * cascading two {@code Collector}s together:
+     * <pre>{@code
+     *     Map<String, Map<String, Collection<Person>>> peopleByStateAndCity
+     *         = personStream.collect(Collectors.groupBy(Person::getState,
+     *                                                   Collectors.groupBy(Person::getCity)));
+     * }</pre>
+     *
+     * @param <R> the type of the result
+     * @param collector the {@code Collector} describing the reduction
+     * @return the result of the reduction
+     * @see #collect(Supplier, BiConsumer, BiConsumer)
+     * @see Collectors
+     */
+    <R> R collect(Collector<? super T, R> collector);
+
+    /**
+     * Returns the minimum element of this stream according to the provided
+     * {@code Comparator}.  This is a special case of a
+     * <a href="package-summary.html#MutableReduction">reduction</a>.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+     *
+     * @param comparator a <a href="package-summary.html#NonInterference">non-interfering,
+     *                   stateless</a> {@code Comparator} to use to compare
+     *                   elements of this stream
+     * @return an {@code Optional} describing the minimum element of this stream,
+     * or an empty {@code Optional} if the stream is empty
+     */
+    Optional<T> min(Comparator<? super T> comparator);
+
+    /**
+     * Returns the maximum element of this stream according to the provided
+     * {@code Comparator}.  This is a special case of a
+     * <a href="package-summary.html#MutableReduction">reduction</a>.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal
+     * operation</a>.
+     *
+     * @param comparator a <a href="package-summary.html#NonInterference">non-interfering,
+     *                   stateless</a> {@code Comparator} to use to compare
+     *                   elements of this stream
+     * @return an {@code Optional} describing the maximum element of this stream,
+     * or an empty {@code Optional} if the stream is empty
+     */
+    Optional<T> max(Comparator<? super T> comparator);
+
+    /**
+     * Returns the count of elements in this stream.  This is a special case of
+     * a <a href="package-summary.html#MutableReduction">reduction</a> and is
+     * equivalent to:
+     * <pre>{@code
+     *     return mapToLong(e -> 1L).sum();
+     * }</pre>
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
+     *
+     * @return the count of elements in this stream
+     */
+    long count();
+
+    /**
+     * Returns whether any elements of this stream match the provided
+     * predicate.  May not evaluate the predicate on all elements if not
+     * necessary for determining the result.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
+     * @return {@code true} if any elements of the stream match the provided
+     * predicate otherwise {@code false}
+     */
+    boolean anyMatch(Predicate<? super T> predicate);
+
+    /**
+     * Returns whether all elements of this stream match the provided predicate.
+     * May not evaluate the predicate on all elements if not necessary for
+     * determining the result.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
+     * @return {@code true} if all elements of the stream match the provided
+     * predicate otherwise {@code false}
+     */
+    boolean allMatch(Predicate<? super T> predicate);
+
+    /**
+     * Returns whether no elements of this stream match the provided predicate.
+     * May not evaluate the predicate on all elements if not necessary for
+     * determining the result.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @param predicate a <a href="package-summary.html#NonInterference">non-interfering,
+     *                  stateless</a> predicate to apply to elements of this
+     *                  stream
+     * @return {@code true} if no elements of the stream match the provided
+     * predicate otherwise {@code false}
+     */
+    boolean noneMatch(Predicate<? super T> predicate);
+
+    /**
+     * Returns an {@link Optional} describing the first element of this stream
+     * (in the encounter order), or an empty {@code Optional} if the stream is
+     * empty.  If the stream has no encounter order, than any element may be
+     * returned.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * @return an {@code Optional} describing the first element of this stream,
+     * or an empty {@code Optional} if the stream is empty
+     * @throws NullPointerException if the element selected is null
+     */
+    Optional<T> findFirst();
+
+    /**
+     * Returns an {@link Optional} describing some element of the stream, or an
+     * empty {@code Optional} if the stream is empty.
+     *
+     * <p>This is a <a href="package-summary.html#StreamOps">short-circuiting
+     * terminal operation</a>.
+     *
+     * <p>The behavior of this operation is explicitly nondeterministic; it is
+     * free to select any element in the stream.  This is to allow for maximal
+     * performance in parallel operations; the cost is that multiple invocations
+     * on the same source may not return the same result.  (If the first element
+     * in the encounter order is desired, use {@link #findFirst()} instead.)
+     *
+     * @return an {@code Optional} describing some element of this stream, or an
+     * empty {@code Optional} if the stream is empty
+     * @throws NullPointerException if the element selected is null
+     * @see #findFirst()
+     */
+    Optional<T> findAny();
+}

src/share/classes/java/util/stream/package-info.java

+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * <h1>java.util.stream</h1>
+ *
+ * Classes to support functional-style operations on streams of values, as in the following:
+ *
+ * <pre>{@code
+ *     int sumOfWeights = blocks.stream().filter(b -> b.getColor() == RED)
+ *                                       .mapToInt(b -> b.getWeight())
+ *                                       .sum();
+ * }</pre>
+ *
+ * <p>Here we use {@code blocks}, which might be a {@code Collection}, as a source for a stream,
+ * and then perform a filter-map-reduce ({@code sum()} is an example of a <a href="package-summary.html#Reduction">reduction</a>
+ * operation) on the stream to obtain the sum of the weights of the red blocks.
+ *
+ * <p>The key abstraction used in this approach is {@link java.util.stream.Stream}, as well as its primitive
+ * specializations {@link java.util.stream.IntStream}, {@link java.util.stream.LongStream},
+ * and {@link java.util.stream.DoubleStream}.  Streams differ from Collections in several ways:
+ *
+ * <ul>
+ *     <li>No storage.  A stream is not a data structure that stores elements; instead, they
+ *     carry values from a source (which could be a data structure, a generator, an IO channel, etc)
+ *     through a pipeline of computational operations.</li>
+ *     <li>Functional in nature.  An operation on a stream produces a result, but does not modify
+ *     its underlying data source.  For example, filtering a {@code Stream} produces a new {@code Stream},
+ *     rather than removing elements from the underlying source.</li>
+ *     <li>Laziness-seeking.  Many stream operations, such as filtering, mapping, or duplicate removal,
+ *     can be implemented lazily, exposing opportunities for optimization.  (For example, "find the first
+ *     {@code String} matching a pattern" need not examine all the input strings.)  Stream operations
+ *     are divided into intermediate ({@code Stream}-producing) operations and terminal (value-producing)
+ *     operations; all intermediate operations are lazy.</li>
+ *     <li>Possibly unbounded.  While collections have a finite size, streams need not.  Operations
+ *     such as {@code limit(n)} or {@code findFirst()} can allow computations on infinite streams
+ *     to complete in finite time.</li>
+ * </ul>
+ *
+ * <h2><a name="StreamPipelines">Stream pipelines</a></h2>
+ *
+ * <p>Streams are used to create <em>pipelines</em> of <a href="package-summary.html#StreamOps">operations</a>.  A
+ * complete stream pipeline has several components: a source (which may be a {@code Collection},
+ * an array, a generator function, or an IO channel); zero or more <em>intermediate operations</em>
+ * such as {@code Stream.filter} or {@code Stream.map}; and a <em>terminal operation</em> such
+ * as {@code Stream.forEach} or {@code java.util.stream.Stream.reduce}.  Stream operations may take as parameters
+ * <em>function values</em> (which are often lambda expressions, but could be method references
+ * or objects) which parameterize the behavior of the operation, such as a {@code Predicate}
+ * passed to the {@code Stream#filter} method.
+ *
+ * <p>Intermediate operations return a new {@code Stream}.  They are lazy; executing an
+ * intermediate operation such as {@link java.util.stream.Stream#filter Stream.filter} does
+ * not actually perform any filtering, instead creating a new {@code Stream} that, when
+ * traversed, contains the elements of the initial {@code Stream} that match the
+ * given {@code Predicate}.  Consuming elements from the  stream source does not
+ * begin until the terminal operation is executed.
+ *
+ * <p>Terminal operations consume the {@code Stream} and produce a result or a side-effect.
+ * After a terminal operation is performed, the stream can no longer be used and you must
+ * return to the data source, or select a new data source, to get a new stream. For example,
+ * obtaining the sum of weights of all red blocks, and then of all blue blocks, requires a
+ * filter-map-reduce on two different streams:
+ * <pre>{@code
+ *     int sumOfRedWeights  = blocks.stream().filter(b -> b.getColor() == RED)
+ *                                           .mapToInt(b -> b.getWeight())
+ *                                           .sum();
+ *     int sumOfBlueWeights = blocks.stream().filter(b -> b.getColor() == BLUE)
+ *                                           .mapToInt(b -> b.getWeight())
+ *                                           .sum();
+ * }</pre>
+ *
+ * <p>However, there are other techniques that allow you to obtain both results in a single
+ * pass if multiple traversal is impractical or inefficient.  TODO provide link
+ *
+ * <h3><a name="StreamOps">Stream operations</a></h3>
+ *
+ * <p>Intermediate stream operation (such as {@code filter} or {@code sorted}) always produce a
+ * new {@code Stream}, and are always<em>lazy</em>.  Executing a lazy operations does not
+ * trigger processing of the stream contents; all processing is deferred until the terminal
+ * operation commences.  Processing streams lazily allows for significant efficiencies; in a
+ * pipeline such as the filter-map-sum example above, filtering, mapping, and addition can be
+ * fused into a single pass, with minimal intermediate state.  Laziness also enables us to avoid
+ * examining all the data when it is not necessary; for operations such as "find the first
+ * string longer than 1000 characters", one need not examine all the input strings, just enough
+ * to find one that has the desired characteristics.  (This behavior becomes even more important
+ * when the input stream is infinite and not merely large.)
+ *
+ * <p>Intermediate operations are further divided into <em>stateless</em> and <em>stateful</em>
+ * operations.  Stateless operations retain no state from previously seen values when processing
+ * a new value; examples of stateless intermediate operations include {@code filter} and
+ * {@code map}.  Stateful operations may incorporate state from previously seen elements in
+ * processing new values; examples of stateful intermediate operations include {@code distinct}
+ * and {@code sorted}.  Stateful operations may need to process the entire input before
+ * producing a result; for example, one cannot produce any results from sorting a stream until
+ * one has seen all elements of the stream.  As a result, under parallel computation, some
+ * pipelines containing stateful intermediate operations have to be executed in multiple passes.
+ * Pipelines containing exclusively stateless intermediate operations can be processed in a
+ * single pass, whether sequential or parallel.
+ *
+ * <p>Further, some operations are deemed <em>short-circuiting</em> operations.  An intermediate
+ * operation is short-circuiting if, when presented with infinite input, it may produce a
+ * finite stream as a result.  A terminal operation is short-circuiting if, when presented with
+ * infinite input, it may terminate in finite time.  (Having a short-circuiting operation is a
+ * necessary, but not sufficient, condition for the processing of an infinite stream to
+ * terminate normally in finite time.)
+ *
+ * Terminal operations (such as {@code forEach} or {@code findFirst}) are always eager
+ * (they execute completely before returning), and produce a non-{@code Stream} result, such
+ * as a primitive value or a {@code Collection}, or have side-effects.
+ *
+ * <h3>Parallelism</h3>
+ *
+ * <p>By recasting aggregate operations as a pipeline of operations on a stream of values, many
+ * aggregate operations can be more easily parallelized.  A {@code Stream} can execute either
+ * in serial or in parallel.  When streams are created, they are either created as sequential
+ * or parallel streams; the parallel-ness of streams can also be switched by the
+ * {@link java.util.stream Stream#sequential()} and {@link java.util.stream.Stream#parallel()}
+ * operations.  The {@code Stream} implementations in the JDK create serial streams unless
+ * parallelism is explicitly requested.  For example, {@code Collection} has methods
+ * {@link java.util.Collection#stream} and {@link java.util.Collection#parallelStream},
+ * which produce sequential and parallel streams respectively; other stream-bearing methods
+ * such as {@link java.util.stream.Streams#intRange(int, int)} produce sequential
+ * streams but these can be efficiently parallelized by calling {@code parallel()} on the
+ * result. The set of operations on serial and parallel streams is identical. To execute the
+ * "sum of weights of blocks" query in parallel, we would do:
+ *
+ * <pre>{@code
+ *     int sumOfWeights = blocks.parallelStream().filter(b -> b.getColor() == RED)
+ *                                               .mapToInt(b -> b.getWeight())
+ *                                               .sum();
+ * }</pre>
+ *
+ * <p>The only difference between the serial and parallel versions of this example code is
+ * the creation of the initial {@code Stream}.  Whether a {@code Stream} will execute in serial
+ * or parallel can be determined by the {@code Stream#isParallel} method.  When the terminal
+ * operation is initiated, the entire stream pipeline is either executed sequentially or in
+ * parallel, determined by the last operation that affected the stream's serial-parallel
+ * orientation (which could be the stream source, or the {@code sequential()} or
+ * {@code parallel()} methods.)
+ *
+ * <p>In order for the results of parallel operations to be deterministic and consistent with
+ * their serial equivalent, the function values passed into the various stream operations should
+ * be <a href="#NonInteference"><em>stateless</em></a>.
+ *
+ * <h3><a name="Ordering">Ordering</a></h3>
+ *
+ * <p>Streams may or may not have an <em>encounter order</em>.  An encounter
+ * order specifies the order in which elements are provided by the stream to the
+ * operations pipeline.  Whether or not there is an encounter order depends on
+ * the source, the intermediate  operations, and the terminal operation.
+ * Certain stream sources (such as {@code List} or arrays) are intrinsically
+ * ordered, whereas others (such as {@code HashSet}) are not.  Some intermediate
+ * operations may impose an encounter order on an otherwise unordered stream,
+ * such as {@link java.util.stream.Stream#sorted()}, and others may render an
+ * ordered stream unordered (such as {@link java.util.stream.Stream#unordered()}).
+ * Some terminal operations may ignore encounter order, such as
+ * {@link java.util.stream.Stream#forEach}.
+ *
+ * <p>If a Stream is ordered, most operations are constrained to operate on the
+ * elements in their encounter order; if the source of a stream is a {@code List}
+ * containing {@code [1, 2, 3]}, then the result of executing {@code map(x -> x*2)}
+ * must be {@code [2, 4, 6]}.  However, if the source has no defined encounter
+ * order, than any of the six permutations of the values {@code [2, 4, 6]} would
+ * be a valid result. Many operations can still be efficiently parallelized even
+ * under ordering constraints.
+ *
+ * <p>For sequential streams, ordering is only relevant to the determinism
+ * of operations performed repeatedly on the same source.  (An {@code ArrayList}
+ * is constrained to iterate elements in order; a {@code HashSet} is not, and
+ * repeated iteration might produce a different order.)
+ *
+ * <p>For parallel streams, relaxing the ordering constraint can enable
+ * optimized implementation for some operations.  For example, duplicate
+ * filtration on an ordered stream must completely process the first partition
+ * before it can return any elements from a subsequent partition, even if those
+ * elements are available earlier.  On the other hand, without the constraint of
+ * ordering, duplicate filtration can be done more efficiently by using
+ * a shared {@code ConcurrentHashSet}.  There will be cases where the stream
+ * is structurally ordered (the source is ordered and the intermediate
+ * operations are order-preserving), but the user does not particularly care
+ * about the encounter order.  In some cases, explicitly de-ordering the stream
+ * with the {@link java.util.stream.Stream#unordered()} method may result in
+ * improved parallel performance for some stateful or terminal operations.
+ *
+ * <h3><a name="Non-Interference">Non-interference</a></h3>
+ *
+ * The {@code java.util.stream} package enables you to execute possibly-parallel
+ * bulk-data operations over a variety of data sources, including even non-thread-safe
+ * collections such as {@code ArrayList}.  This is possible only if we can
+ * prevent <em>interference</em> with the data source during the execution of a
+ * stream pipeline.  (Execution begins when the terminal operation is invoked, and ends
+ * when the terminal operation completes.)  For most data sources, preventing interference
+ * means ensuring that the data source is <em>not modified at all</em> during the execution
+ * of the stream pipeline.  (Some data sources, such as concurrent collections, are
+ * specifically designed to handle concurrent modification.)
+ *
+ * <p>Accordingly, lambda expressions (or other objects implementing the appropriate functional
+ * interface) passed to stream methods should never modify the stream's data source.  An
+ * implementation is said to <em>interfere</em> with the data source if it modifies, or causes
+ * to be modified, the stream's data source.  The need for non-interference applies to all
+ * pipelines, not just parallel ones.  Unless the stream source is concurrent, modifying a
+ * stream's data source during execution of a stream pipeline can cause exceptions, incorrect
+ * answers, or nonconformant results.
+ *
+ * <p>Further, results may be nondeterministic or incorrect if the lambda expressions passed to
+ * stream operations are <em>stateful</em>.  A stateful lambda (or other object implementing the
+ * appropriate functional interface) is one whose result depends on any state which might change
+ * during the execution of the stream pipeline.  An example of a stateful lambda is:
+ * <pre>{@code
+ *     Set<Integer> seen = Collections.synchronizedSet(new HashSet<>());
+ *     stream.parallel().map(e -> { if (seen.add(e)) return 0; else return e; })...
+ * }</pre>
+ * Here, if the mapping operation is performed in parallel, the results for the same input
+ * could vary from run to run, due to thread scheduling differences, whereas, with a stateless
+ * lambda expression the results would always be the same.
+ *
+ * <h3>Side-effects</h3>
+ *
+ * <h2><a name="Reduction">Reduction operations</a></h2>
+ *
+ * A <em>reduction</em> operation takes a stream of elements and processes them in a way
+ * that reduces to a single value or summary description, such as finding the sum or maximum
+ * of a set of numbers.  (In more complex scenarios, the reduction operation might need to
+ * extract data from the elements before reducing that data to a single value, such as
+ * finding the sum of weights of a set of blocks.  This would require extracting the weight
+ * from each block before summing up the weights.)
+ *
+ * <p>Of course, such operations can be readily implemented as simple sequential loops, as in:
+ * <pre>{@code
+ *    int sum = 0;
+ *    for (int x : numbers) {
+ *       sum += x;
+ *    }
+ * }</pre>
+ * However, there may be a significant advantage to preferring a {@link java.util.stream.Stream#reduce reduce operation}
+ * over a mutative accumulation such as the above -- a properly constructed reduce operation is
+ * inherently parallelizable so long as the
+ * {@link java.util.function.BinaryOperator reduction operaterator}
+ * has the right characteristics. Specifically the operator must be
+ * <a href="#Associativity">associative</a>.  For example, given a
+ * stream of numbers for which we want to find the sum, we can write:
+ * <pre>{@code
+ *    int sum = numbers.reduce(0, (x,y) -> x+y);
+ * }</pre>
+ * or more succinctly:
+ * <pre>{@code
+ *    int sum = numbers.reduce(0, Integer::sum);
+ * }</pre>
+ *
+ * <p>(The primitive specializations of {@link java.util.stream.Stream}, such as
+ * {@link java.util.stream.IntStream}, even have convenience methods for common reductions,
+ * such as {@link java.util.stream.IntStream#sum() sum} and {@link java.util.stream.IntStream#max() max},
+ * which are implemented as simple wrappers around reduce.)
+ *
+ * <p>Reduction parallellizes well since the implementation of {@code reduce} can operate on
+ * subsets of the stream in parallel, and then combine the intermediate results to get the final
+ * correct answer.  Even if you were to use a parallelizable form of the
+ * {@link java.util.stream.Stream#forEach(Consumer) forEach()} method
+ * in place of the original for-each loop above, you would still have to provide thread-safe
+ * updates to the shared accumulating variable {@code sum}, and the required synchronization
+ * would likely eliminate any performance gain from parallelism. Using a {@code reduce} method
+ * instead removes all of the burden of parallelizing the reduction operation, and the library
+ * can provide an efficient parallel implementation with no additional synchronization needed.
+ *
+ * <p>The "blocks" examples shown earlier shows how reduction combines with other operations
+ * to replace for loops with bulk operations.  If {@code blocks} is a collection of {@code Block}
+ * objects, which have a {@code getWeight} method, we can find the heaviest block with:
+ * <pre>{@code
+ *     OptionalInt heaviest = blocks.stream()
+ *                                  .mapToInt(Block::getWeight)
+ *                                  .reduce(Integer::max);
+ * }</pre>
+ *
+ * <p>In its more general form, a {@code reduce} operation on elements of type {@code <T>}
+ * yielding a result of type {@code <U>} requires three parameters:
+ * <pre>{@code
+ * <U> U reduce(U identity,
+ *              BiFunction<U, ? super T, U> accumlator,
+ *              BinaryOperator<U> combiner);
+ * }</pre>
+ * Here, the <em>identity</em> element is both an initial seed for the reduction, and a default
+ * result if there are no elements. The <em>accumulator</em> function takes a partial result and
+ * the next element, and produce a new partial result. The <em>combiner</em> function combines
+ * the partial results of two accumulators to produce a new partial result, and eventually the
+ * final result.
+ *
+ * <p>This form is a generalization of the two-argument form, and is also a generalization of
+ * the map-reduce construct illustrated above.  If we wanted to re-cast the simple {@code sum}
+ * example using the more general form, {@code 0} would be the identity element, while
+ * {@code Integer::sum} would be both the accumulator and combiner. For the sum-of-weights
+ * example, this could be re-cast as:
+ * <pre>{@code
+ *     int sumOfWeights = blocks.stream().reduce(0,
+ *                                               (sum, b) -> sum + b.getWeight())
+ *                                               Integer::sum);
+ * }</pre>
+ * though the map-reduce form is more readable and generally preferable.  The generalized form
+ * is provided for cases where significant work can be optimized away by combining mapping and
+ * reducing into a single function.
+ *
+ * <p>More formally, the {@code identity} value must be an <em>identity</em> for the combiner
+ * function. This means that for all {@code u}, {@code combiner.apply(identity, u)} is equal
+ * to {@code u}. Additionally, the {@code combiner} function must be
+ * <a href="#Associativity">associative</a> and must be compatible with the {@code accumulator}
+ * function; for all {@code u} and {@code t}, the following must hold:
+ * <pre>{@code
+ *     combiner.apply(u, accumulator.apply(identity, t)) == accumulator.apply(u, t)
+ * }</pre>
+ *
+ * <h3><a name="MutableReduction">Mutable Reduction</a></h3>
+ *
+ * A <em>mutable</em> reduction operation is similar to an ordinary reduction, in that it reduces
+ * a stream of values to a single value, but instead of producing a distinct single-valued result, it
+ * mutates a general <em>result container</em>, such as a {@code Collection} or {@code StringBuilder},
+ * as it processes the elements in the stream.
+ *
+ * <p>For example, if we wanted to take a stream of strings and concatenate them into a single
+ * long string, we <em>could</em> achieve this with ordinary reduction:
+ * <pre>{@code
+ *     String concatenated = strings.reduce("", String::concat)
+ * }</pre>
+ *
+ * We would get the desired result, and it would even work in parallel.  However, we might not
+ * be happy about the performance!  Such an implementation would do a great deal of string
+ * copying, and the run time would be <em>O(n^2)</em> in the number of elements.  A more
+ * performant approach would be to accumulate the results into a {@link java.lang.StringBuilder}, which
+ * is a mutable container for accumulating strings.  We can use the same technique to
+ * parallelize mutable reduction as we do with ordinary reduction.
+ *
+ * <p>The mutable reduction operation is called {@link java.util.stream.Stream#collect(Collector) collect()}, as it
+ * collects together the desired results into a result container such as {@code StringBuilder}.
+ * A {@code collect} operation requires three things: a factory function which will construct
+ * new instances of the result container, an accumulating function that will update a result
+ * container by incorporating a new element, and a combining function that can take two
+ * result containers and merge their contents.  The form of this is very similar to the general
+ * form of ordinary reduction:
+ * <pre>{@code
+ * <R> R collect(Supplier<R> resultFactory,
+ *               BiConsumer<R, ? super T> accumulator,
+ *               BiConsumer<R, R> combiner);
+ * }</pre>
+ * As with {@code reduce()}, the benefit of expressing {@code collect} in this abstract way is
+ * that it is directly amenable to parallelization: we can accumulate partial results in parallel
+ * and then combine them.  For example, to collect the String representations of the elements
+ * in a stream into an {@code ArrayList}, we could write the obvious sequential for-each form:
+ * <pre>{@code
+ *     ArrayList<String> strings = new ArrayList<>();
+ *     for (T element : stream) {
+ *         strings.add(element.toString());
+ *     }
+ * }</pre>
+ * Or we could use a parallelizable collect form:
+ * <pre>{@code
+ *     ArrayList<String> strings = stream.collect(() -> new ArrayList<>(),
+ *                                                (c, e) -> c.add(e.toString()),
+ *                                                (c1, c2) -> c1.addAll(c2));
+ * }</pre>
+ * or, noting that we have buried a mapping operation inside the accumulator function, more
+ * succinctly as:
+ * <pre>{@code
+ *     ArrayList<String> strings = stream.map(Object::toString)
+ *                                       .collect(ArrayList::new, ArrayList::add, ArrayList::addAll);
+ * }</pre>
+ * Here, our supplier is just the {@link java.util.ArrayList#ArrayList() ArrayList constructor}, the
+ * accumulator adds the stringified element to an {@code ArrayList}, and the combiner simply
+ * uses {@link java.util.ArrayList#addAll addAll} to copy the strings from one container into the other.
+ *
+ * <p>As with the regular reduction operation, the ability to parallelize only comes if an
+ * <a href="package-summary.html#Associativity">associativity</a> condition is met. The {@code combiner} is associative
+ * if for result containers {@code r1}, {@code r2}, and {@code r3}:
+ * <pre>{@code
+ *    combiner.accept(r1, r2);
+ *    combiner.accept(r1, r3);
+ * }</pre>
+ * is equivalent to
+ * <pre>{@code
+ *    combiner.accept(r2, r3);
+ *    combiner.accept(r1, r2);
+ * }</pre>
+ * where equivalence means that {@code r1} is left in the same state (according to the meaning
+ * of {@link java.lang.Object#equals equals} for the element types). Similarly, the {@code resultFactory}
+ * must act as an <em>identity</em> with respect to the {@code combiner} so that for any result
+ * container {@code r}:
+ * <pre>{@code
+ *     combiner.accept(r, resultFactory.get());
+ * }</pre>
+ * does not modify the state of {@code r} (again according to the meaning of
+ * {@link java.lang.Object#equals equals}). Finally, the {@code accumulator} and {@code combiner} must be
+ * compatible such that for a result container {@code r} and element {@code t}:
+ * <pre>{@code
+ *    r2 = resultFactory.get();
+ *    accumulator.accept(r2, t);
+ *    combiner.accept(r, r2);
+ * }</pre>
+ * is equivalent to:
+ * <pre>{@code
+ *    accumulator.accept(r,t);
+ * }</pre>
+ * where equivalence means that {@code r} is left in the same state (again according to the
+ * meaning of {@link java.lang.Object#equals equals}).
+ *
+ * <p> The three aspects of {@code collect}: supplier, accumulator, and combiner, are often very
+ * tightly coupled, and it is convenient to introduce the notion of a {@link java.util.stream.Collector} as
+ * being an object that embodies all three aspects. There is a {@link java.util.stream.Stream#collect(Collector) collect}
+ * method that simply takes a {@code Collector} and returns the resulting container.
+ * The above example for collecting strings into a {@code List} can be rewritten using a
+ * standard {@code Collector} as:
+ * <pre>{@code
+ *     ArrayList<String> strings = stream.map(Object::toString)
+ *                                       .collect(Collectors.toList());
+ * }</pre>
+ *
+ * <h3><a name="ConcurrentReduction">Reduction, Concurrency, and Ordering</a></h3>
+ *
+ * With some complex reduction operations, for example a collect that produces a
+ * {@code Map}, such as:
+ * <pre>{@code
+ *     Map<Buyer, List<Transaction>> salesByBuyer
+ *         = txns.parallelStream()
+ *               .collect(Collectors.groupingBy(Transaction::getBuyer));
+ * }</pre>
+ * (where {@link java.util.stream.Collectors#groupingBy} is a utility function
+ * that returns a {@link java.util.stream.Collector} for grouping sets of elements based on some key)
+ * it may actually be counterproductive to perform the operation in parallel.
+ * This is because the combining step (merging one {@code Map} into another by key)
+ * can be expensive for some {@code Map} implementations.
+ *
+ * <p>Suppose, however, that the result container used in this reduction
+ * was a concurrently modifiable collection -- such as a
+ * {@link java.util.concurrent.ConcurrentHashMap ConcurrentHashMap}. In that case,
+ * the parallel invocations of the accumulator could actually deposit their results
+ * concurrently into the same shared result container, eliminating the need for the combiner to
+ * merge distinct result containers. This potentially provides a boost
+ * to the parallel execution performance. We call this a <em>concurrent</em> reduction.
+ *
+ * <p>A {@link java.util.stream.Collector} that supports concurrent reduction is marked with the
+ * {@link java.util.stream.Collector.Characteristics#CONCURRENT} characteristic.
+ * Having a concurrent collector is a necessary condition for performing a
+ * concurrent reduction, but that alone is not sufficient. If you imagine multiple
+ * accumulators depositing results into a shared container, the order in which
+ * results are deposited is non-deterministic. Consequently, a concurrent reduction
+ * is only possible if ordering is not important for the stream being processed.
+ * The {@link java.util.stream.Stream#collect(Collector)}
+ * implementation will only perform a concurrent reduction if
+ * <ul>
+ * <li>The stream is parallel;</li>
+ * <li>The collector has the
+ * {@link java.util.stream.Collector.Characteristics#CONCURRENT} characteristic,
+ * and;</li>
+ * <li>Either the stream is unordered, or the collector has the
+ * {@link java.util.stream.Collector.Characteristics#UNORDERED} characteristic.
+ * </ul>
+ * For example:
+ * <pre>{@code
+ *     Map<Buyer, List<Transaction>> salesByBuyer
+ *         = txns.parallelStream()
+ *               .unordered()
+ *               .collect(groupingByConcurrent(Transaction::getBuyer));
+ * }</pre>
+ * (where {@link java.util.stream.Collectors#groupingByConcurrent} is the concurrent companion
+ * to {@code groupingBy}).
+ *
+ * <p>Note that if it is important that the elements for a given key appear in the
+ * order they appear in the source, then we cannot use a concurrent reduction,
+ * as ordering is one of the casualties of concurrent insertion.  We would then
+ * be constrained to implement either a sequential reduction or a merge-based
+ * parallel reduction.
+ *
+ * <h2><a name="Associativity">Associativity</a></h2>
+ *
+ * An operator or function {@code op} is <em>associative</em> if the following holds:
+ * <pre>{@code
+ *     (a op b) op c == a op (b op c)
+ * }</pre>
+ * The importance of this to parallel evaluation can be seen if we expand this to four terms:
+ * <pre>{@code
+ *     a op b op c op d == (a op b) op (c op d)
+ * }</pre>
+ * So we can evaluate {@code (a op b)} in parallel with {@code (c op d)} and then invoke {@code op} on
+ * the results.
+ * TODO what does associative mean for mutative combining functions?
+ * FIXME: we described mutative associativity above.
+ *
+ * <h2><a name="StreamSources">Stream sources</a></h2>
+ * TODO where does this section go?
+ *
+ * XXX - change to section to stream construction gradually introducing more
+ *       complex ways to construct
+ *     - construction from Collection
+ *     - construction from Iterator
+ *     - construction from array
+ *     - construction from generators
+ *     - construction from spliterator
+ *
+ * XXX - the following is quite low-level but important aspect of stream constriction
+ *
+ * <p>A pipeline is initially constructed from a spliterator (see {@link java.util.Spliterator}) supplied by a stream source.
+ * The spliterator covers elements of the source and provides element traversal operations
+ * for a possibly-parallel computation.  See methods on {@link java.util.stream.Streams} for construction
+ * of pipelines using spliterators.
+ *
+ * <p>A source may directly supply a spliterator.  If so, the spliterator is traversed, split, or queried
+ * for estimated size after, and never before, the terminal operation commences. It is strongly recommended
+ * that the spliterator report a characteristic of {@code IMMUTABLE} or {@code CONCURRENT}, or be
+ * <em>late-binding</em> and not bind to the elements it covers until traversed, split or queried for
+ * estimated size.
+ *
+ * <p>If a source cannot directly supply a recommended spliterator then it may indirectly supply a spliterator
+ * using a {@code Supplier}.  The spliterator is obtained from the supplier after, and never before, the terminal
+ * operation of the stream pipeline commences.
+ *
+ * <p>Such requirements significantly reduce the scope of potential interference to the interval starting
+ * with the commencing of the terminal operation and ending with the producing a result or side-effect.  See
+ * <a href="package-summary.html#Non-Interference">Non-Interference</a> for
+ * more details.
+ *
+ * XXX - move the following to the non-interference section
+ *
+ * <p>A source can be modified before the terminal operation commences and those modifications will be reflected in
+ * the covered elements.  Afterwards, and depending on the properties of the source, further modifications
+ * might not be reflected and the throwing of a {@code ConcurrentModificationException} may occur.
+ *
+ * <p>For example, consider the following code:
+ * <pre>{@code
+ *     List<String> l = new ArrayList(Arrays.asList("one", "two"));
+ *     Stream<String> sl = l.stream();
+ *     l.add("three");
+ *     String s = sl.collect(toStringJoiner(" ")).toString();
+ * }</pre>
+ * First a list is created consisting of two strings: "one"; and "two". Then a stream is created from that list.
+ * Next the list is modified by adding a third string: "three".  Finally the elements of the stream are collected
+ * and joined together.  Since the list was modified before the terminal {@code collect} operation commenced
+ * the result will be a string of "one two three". However, if the list is modified after the terminal operation
+ * commences, as in:
+ * <pre>{@code
+ *     List<String> l = new ArrayList(Arrays.asList("one", "two"));
+ *     Stream<String> sl = l.stream();
+ *     String s = sl.peek(s -> l.add("BAD LAMBDA")).collect(toStringJoiner(" ")).toString();
+ * }</pre>
+ * then a {@code ConcurrentModificationException} will be thrown since the {@code peek} operation will attempt
+ * to add the string "BAD LAMBDA" to the list after the terminal operation has commenced.
+ */
+
+package java.util.stream;