2013-04-17 14:39:04 -04:00
|
|
|
/*
|
|
|
|
* 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;
|
|
|
|
|
2013-09-06 22:20:01 -07:00
|
|
|
import java.nio.charset.Charset;
|
|
|
|
import java.nio.file.Files;
|
|
|
|
import java.nio.file.Path;
|
|
|
|
import java.util.Collection;
|
2013-04-17 14:39:04 -04:00
|
|
|
import java.util.Iterator;
|
|
|
|
import java.util.Spliterator;
|
2013-09-06 22:20:01 -07:00
|
|
|
import java.util.concurrent.ConcurrentHashMap;
|
|
|
|
import java.util.function.IntConsumer;
|
|
|
|
import java.util.function.Predicate;
|
2013-04-17 14:39:04 -04:00
|
|
|
|
|
|
|
/**
|
2013-09-06 22:20:01 -07:00
|
|
|
* A sequence of elements supporting sequential and parallel aggregate
|
|
|
|
* operations. The following example illustrates an aggregate operation using
|
|
|
|
* {@link Stream} and {@link IntStream}:
|
2013-04-17 14:39:04 -04:00
|
|
|
*
|
2013-09-06 22:20:01 -07:00
|
|
|
* <pre>{@code
|
|
|
|
* int sum = widgets.stream()
|
|
|
|
* .filter(w -> w.getColor() == RED)
|
|
|
|
* .mapToInt(w -> w.getWeight())
|
|
|
|
* .sum();
|
|
|
|
* }</pre>
|
|
|
|
*
|
|
|
|
* In this example, {@code widgets} is a {@code Collection<Widget>}. We create
|
|
|
|
* a stream of {@code Widget} objects via {@link Collection#stream Collection.stream()},
|
|
|
|
* filter it to produce a stream containing only the red widgets, and then
|
|
|
|
* transform it into a stream of {@code int} values representing the weight of
|
|
|
|
* each red widget. Then this stream is summed to produce a total weight.
|
|
|
|
*
|
|
|
|
* <p>To perform a computation, stream
|
|
|
|
* <a href="package-summary.html#StreamOps">operations</a> are composed into a
|
|
|
|
* <em>stream pipeline</em>. A stream pipeline consists of a source (which
|
|
|
|
* might be an array, a collection, a generator function, an IO channel,
|
|
|
|
* etc), zero or more <em>intermediate operations</em> (which transform a
|
|
|
|
* stream into another stream, such as {@link Stream#filter(Predicate)}), and a
|
|
|
|
* <em>terminal operation</em> (which produces a result or side-effect, such
|
|
|
|
* as {@link IntStream#sum()} or {@link IntStream#forEach(IntConsumer)}).
|
|
|
|
* Streams are lazy; computation on the source data is only performed when the
|
|
|
|
* terminal operation is initiated, and source elements are consumed only
|
|
|
|
* as needed.
|
|
|
|
*
|
|
|
|
* <p>Collections and streams, while bearing some superficial similarities,
|
|
|
|
* have different goals. Collections are primarily concerned with the efficient
|
|
|
|
* management of, and access to, their elements. By contrast, streams do not
|
|
|
|
* provide a means to directly access or manipulate their elements, and are
|
|
|
|
* instead concerned with declaratively describing their source and the
|
|
|
|
* computational operations which will be performed in aggregate on that source.
|
|
|
|
* However, if the provided stream operations do not offer the desired
|
|
|
|
* functionality, the {@link #iterator()} and {@link #spliterator()} operations
|
|
|
|
* can be used to perform a controlled traversal.
|
|
|
|
*
|
|
|
|
* <p>A stream pipeline, like the "widgets" example above, can be viewed as
|
|
|
|
* a <em>query</em> on the stream source. Unless the source was explicitly
|
|
|
|
* designed for concurrent modification (such as a {@link ConcurrentHashMap}),
|
|
|
|
* unpredictable or erroneous behavior may result from modifying the stream
|
|
|
|
* source while it is being queried.
|
|
|
|
*
|
|
|
|
* <p>Most stream operations accept parameters that describe user-specified
|
|
|
|
* behavior, such as the lambda expression {@code w -> w.getWeight()} passed to
|
|
|
|
* {@code mapToInt} in the example above. Such parameters are always instances
|
|
|
|
* of a <a href="../function/package-summary.html">functional interface</a> such
|
|
|
|
* as {@link java.util.function.Function}, and are often lambda expressions or
|
|
|
|
* method references. These parameters can never be null, should not modify the
|
|
|
|
* stream source, and should be
|
|
|
|
* <a href="package-summary.html#NonInterference">effectively stateless</a>
|
|
|
|
* (their result should not depend on any state that might change during
|
|
|
|
* execution of the stream pipeline.)
|
|
|
|
*
|
|
|
|
* <p>A stream should be operated on (invoking an intermediate or terminal stream
|
|
|
|
* operation) only once. This rules out, for example, "forked" streams, where
|
|
|
|
* the same source feeds two or more pipelines, or multiple traversals of the
|
|
|
|
* same stream. A stream implementation may throw {@link IllegalStateException}
|
|
|
|
* if it detects that the stream is being reused. However, since some stream
|
|
|
|
* operations may return their receiver rather than a new stream object, it may
|
|
|
|
* not be possible to detect reuse in all cases.
|
|
|
|
*
|
|
|
|
* <p>Streams have a {@link #close()} method and implement {@link AutoCloseable},
|
|
|
|
* but nearly all stream instances do not actually need to be closed after use.
|
|
|
|
* Generally, only streams whose source is an IO channel (such as those returned
|
|
|
|
* by {@link Files#lines(Path, Charset)}) will require closing. Most streams
|
|
|
|
* are backed by collections, arrays, or generating functions, which require no
|
|
|
|
* special resource management. (If a stream does require closing, it can be
|
|
|
|
* declared as a resource in a {@code try}-with-resources statement.)
|
|
|
|
*
|
|
|
|
* <p>Stream pipelines may execute either sequentially or in
|
|
|
|
* <a href="package-summary.html#Parallelism">parallel</a>. This
|
|
|
|
* execution mode is a property of the stream. Streams are created
|
|
|
|
* with an initial choice of sequential or parallel execution. (For example,
|
|
|
|
* {@link Collection#stream() Collection.stream()} creates a sequential stream,
|
|
|
|
* and {@link Collection#parallelStream() Collection.parallelStream()} creates
|
|
|
|
* a parallel one.) This choice of execution mode may be modified by the
|
|
|
|
* {@link #sequential()} or {@link #parallel()} methods, and may be queried with
|
|
|
|
* the {@link #isParallel()} method.
|
|
|
|
*
|
|
|
|
* @param <T> the type of the stream elements
|
|
|
|
* @param <S> the type of of the stream implementing {@code BaseStream}
|
2013-04-17 14:39:04 -04:00
|
|
|
* @since 1.8
|
2013-09-06 22:20:01 -07:00
|
|
|
* @see <a href="package-summary.html">java.util.stream</a>
|
2013-04-17 14:39:04 -04:00
|
|
|
*/
|
2013-09-03 12:16:01 -07:00
|
|
|
public interface BaseStream<T, S extends BaseStream<T, S>>
|
|
|
|
extends AutoCloseable {
|
2013-04-17 14:39:04 -04:00
|
|
|
/**
|
|
|
|
* 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();
|
|
|
|
|
|
|
|
/**
|
2013-09-06 22:20:01 -07:00
|
|
|
* Returns whether this stream, if a terminal operation were to be executed,
|
|
|
|
* would execute in parallel. Calling this method after invoking an
|
|
|
|
* terminal stream operation method may yield unpredictable results.
|
2013-04-17 14:39:04 -04:00
|
|
|
*
|
|
|
|
* @return {@code true} if this stream would execute in parallel if executed
|
|
|
|
*/
|
|
|
|
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
|
2013-09-06 22:20:01 -07:00
|
|
|
* itself, either because the stream was already unordered, or because
|
|
|
|
* the underlying stream state was modified to be unordered.
|
2013-04-17 14:39:04 -04:00
|
|
|
*
|
|
|
|
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
|
|
|
|
* operation</a>.
|
|
|
|
*
|
|
|
|
* @return an unordered stream
|
|
|
|
*/
|
|
|
|
S unordered();
|
2013-09-03 12:16:01 -07:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns an equivalent stream with an additional close handler. Close
|
|
|
|
* handlers are run when the {@link #close()} method
|
|
|
|
* is called on the stream, and are executed in the order they were
|
|
|
|
* added. All close handlers are run, even if earlier close handlers throw
|
|
|
|
* exceptions. If any close handler throws an exception, the first
|
|
|
|
* exception thrown will be relayed to the caller of {@code close()}, with
|
|
|
|
* any remaining exceptions added to that exception as suppressed exceptions
|
|
|
|
* (unless one of the remaining exceptions is the same exception as the
|
|
|
|
* first exception, since an exception cannot suppress itself.) May
|
|
|
|
* return itself.
|
|
|
|
*
|
|
|
|
* <p>This is an <a href="package-summary.html#StreamOps">intermediate
|
|
|
|
* operation</a>.
|
|
|
|
*
|
|
|
|
* @param closeHandler A task to execute when the stream is closed
|
|
|
|
* @return a stream with a handler that is run if the stream is closed
|
|
|
|
*/
|
|
|
|
S onClose(Runnable closeHandler);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Closes this stream, causing all close handlers for this stream pipeline
|
|
|
|
* to be called.
|
|
|
|
*
|
|
|
|
* @see AutoCloseable#close()
|
|
|
|
*/
|
|
|
|
@Override
|
|
|
|
void close();
|
2013-04-17 14:39:04 -04:00
|
|
|
}
|