Mercurial > hg > openjdk > lambda > jdk
changeset 7547:9ccdccc3c754
Format JavaDoc to 80 character width limit
line wrap: on
line diff
--- a/src/share/classes/java/util/stream/AbstractShortCircuitTask.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/AbstractShortCircuitTask.java Thu Feb 28 18:35:14 2013 +0100 @@ -29,23 +29,29 @@ /** * Abstract class for fork-join tasks used to implement short-circuiting - * stream ops, which can produce a result without processing all elements of the stream. + * stream ops, which can produce a result without processing all elements of the + * stream. * * @param <P_IN> Type of elements input to the pipeline * @param <P_OUT> Type of elements output from the pipeline - * @param <R> Type of intermediate result, may be different from operation result type + * @param <R> Type of intermediate result, may be different from operation + * result type * @param <T> Type of child and sibling tasks * @since 1.8 */ abstract class AbstractShortCircuitTask<P_IN, P_OUT, R, T extends AbstractShortCircuitTask<P_IN, P_OUT, R, T>> extends AbstractTask<P_IN, P_OUT, R, T> { - /** The result for this computation; this is shared among all tasks and set exactly once */ + /** + * The result for this computation; this is shared among all tasks and set + * exactly once + */ protected final AtomicReference<R> sharedResult; /** - * Indicates whether this task has been canceled. Tasks may cancel other tasks in the computation - * under various conditions, such as in a find-first operation, a task that finds a value will cancel - * all tasks that are later in the encounter order. + * Indicates whether this task has been canceled. Tasks may cancel other + * tasks in the computation under various conditions, such as in a + * find-first operation, a task that finds a value will cancel all tasks + * that are later in the encounter order. */ protected volatile boolean canceled; @@ -62,8 +68,9 @@ } /** - * Return the value indicating the computation completed with no task finding a short-circuitable result. - * For example, for a "find" operation, this might be null or an empty {@code Optional}. + * Return the value indicating the computation completed with no task + * finding a short-circuitable result. For example, for a "find" operation, + * this might be null or an empty {@code Optional}. */ protected abstract R getEmptyResult(); @@ -84,9 +91,11 @@ } /** - * Declare that a globally valid result has been found. If another task has not already found the answer, - * the result is installed in {@code sharedResult}. The {@code compute()} method will check {@code sharedResult} - * before proceeding with computation, so this causes the computation to terminate early. + * Declare that a globally valid result has been found. If another task has + * not already found the answer, the result is installed in + * {@code sharedResult}. The {@code compute()} method will check + * {@code sharedResult} before proceeding with computation, so this causes + * the computation to terminate early. */ protected void shortCircuit(R result) { if (result != null) @@ -94,7 +103,8 @@ } /** - * Set a local result for this task. If this task is the root, set the shared result instead (if not already set). + * Set a local result for this task. If this task is the root, set the + * shared result instead (if not already set). */ @Override protected void setLocalResult(R localResult) { @@ -112,7 +122,10 @@ return getLocalResult(); } - /** Retrieve the local result for this task. If this task is the root, retrieves the shared result instead. */ + /** + * Retrieve the local result for this task. If this task is the root, + * retrieves the shared result instead. + */ @Override public R getLocalResult() { if (isRoot()) { @@ -129,8 +142,8 @@ } /** - * Query whether this task is canceled. A task is considered canceled if it or any of its parents - * have been canceled. + * Query whether this task is canceled. A task is considered canceled if it + * or any of its parents have been canceled. */ protected boolean taskCanceled() { boolean cancel = canceled; @@ -141,8 +154,9 @@ } /** - * Cancel all tasks which succeed this one in the encounter order. This includes canceling all the current - * task's later siblings, as well as the later siblings of all its parents. + * Cancel all tasks which succeed this one in the encounter order. This + * includes canceling all the current task's later siblings, as well as the + * later siblings of all its parents. */ protected void cancelLaterNodes() { T parent = getParent(); @@ -155,9 +169,9 @@ } /** - * Returns whether this node is a "leftmost" node -- whether the path from the root to this node involves - * only traversing leftmost child links. For a leaf node, this means it is the first leaf node in the - * encounter order. + * Returns whether this node is a "leftmost" node -- whether the path from + * the root to this node involves only traversing leftmost child links. For + * a leaf node, this means it is the first leaf node in the encounter order. */ protected boolean isLeftmostNode() { T node = (T) this;
--- a/src/share/classes/java/util/stream/AbstractTask.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/AbstractTask.java Thu Feb 28 18:35:14 2013 +0100 @@ -31,24 +31,27 @@ /** * Abstract base class for most fork-join tasks used to implement stream ops. * Manages splitting logic, tracking of child tasks, and intermediate results. - * Each task is associated with a {@link Spliterator} that describes a portion of the - * input. Tasks may be leaf nodes (which will traverse the elements of the {@code Spliterator}) - * or internal nodes (which split the {@code Spliterator} into multiple child tasks). + * Each task is associated with a {@link Spliterator} that describes a portion + * of the input. Tasks may be leaf nodes (which will traverse the elements of + * the {@code Spliterator}) or internal nodes (which split the + * {@code Spliterator} into multiple child tasks). * - * <p>This class is based on {@link CountedCompleter}, a form of fork-join task where each - * task has a semaphore-like count of uncompleted children, and the task is implicitly - * completed and notified when its last child completes Internal node tasks will likely - * override the {@code onCompletion} method from {@code CountedCompleter} to merge the - * results from child tasks into the current task's result. + * <p>This class is based on {@link CountedCompleter}, a form of fork-join task + * where each task has a semaphore-like count of uncompleted children, and the + * task is implicitly completed and notified when its last child completes. + * Internal node tasks will likely override the {@code onCompletion} method from + * {@code CountedCompleter} to merge the results from child tasks into the + * current task's result. * * <p>Splitting and setting up the child task links is done by {@code compute()} - * for internal nodes. At {@code compute()} time for leaf nodes, it is guaranteed - * that the parent's child-related fields (including sibling links for the parent's children) - * will be set up for all children. + * for internal nodes. At {@code compute()} time for leaf nodes, it is + * guaranteed that the parent's child-related fields (including sibling links + * for the parent's children) will be set up for all children. * - * <p>For example, a task that performs a reduce would override {@code doLeaf()} to perform a reduction - * on that leaf node's chunk using the {@code Spliterator}, and override {@code onCompletion()} - * to merge the results of the child tasks for internal nodes: + * <p>For example, a task that performs a reduce would override {@code doLeaf()} + * to perform a reduction on that leaf node's chunk using the + * {@code Spliterator}, and override {@code onCompletion()} to merge the results + * of the child tasks for internal nodes: * * <pre> * protected S doLeaf() { @@ -70,7 +73,8 @@ * * @param <P_IN> Type of elements input to the pipeline * @param <P_OUT> Type of elements output from the pipeline - * @param <R> Type of intermediate result, which may be different from operation result type + * @param <R> Type of intermediate result, which may be different from operation + * result type * @param <T> Type of child and sibling tasks * @since 1.8 */ @@ -80,7 +84,10 @@ /** The pipeline helper, common to all tasks in a computation */ protected final PipelineHelper<P_IN, P_OUT> helper; - /** The spliterator for the portion of the input associated with the subtree rooted at this task */ + /** + * The spliterator for the portion of the input associated with the subtree + * rooted at this task + */ protected Spliterator<P_IN> spliterator; /** Target leaf size */ @@ -89,8 +96,11 @@ /** How many children does this task have? */ protected int numChildren; - /** This task's first child. Children are stored in a linked list, using the {@code nextSibling} field - * as the link to the next child. */ + /** + * This task's first child. Children are stored in a linked list, using + * the {@code nextSibling} field + * as the link to the next child. + */ protected T children; /** Next sibling of this task */ @@ -112,8 +122,8 @@ /** * Constructor for non-root nodes * @param parent This node's parent task - * @param spliterator Spliterator describing the subtree rooted at this node, - * obtained by splitting the parent spliterator + * @param spliterator Spliterator describing the subtree rooted at this + * node, obtained by splitting the parent spliterator */ protected AbstractTask(T parent, Spliterator<P_IN> spliterator) { super(parent); @@ -122,13 +132,16 @@ this.targetSize = parent.targetSize; } - /** Construct a new node of type T whose parent is the receiver; must call - * the AbstractTask(T, Spliterator) constructor with the receiver and the provided Spliterator. */ + /** + * Construct a new node of type T whose parent is the receiver; must call + * the AbstractTask(T, Spliterator) constructor with the receiver and the + * provided Spliterator. + */ protected abstract T makeChild(Spliterator<P_IN> spliterator); /** - * Compute the result associated with a leaf node. Will be called by {@code compute()} and - * the result passed to @{code setLocalResult()} + * Compute the result associated with a leaf node. Will be called by + * {@code compute()} and the result passed to @{code setLocalResult()} */ protected abstract R doLeaf(); @@ -139,8 +152,8 @@ } /** - * Suggest whether it is adviseable to split the provided spliterator based on - * target size and other considerations, such as pool state + * Suggest whether it is adviseable to split the provided spliterator based + * on target size and other considerations, such as pool state */ public static<P_IN, P_OUT> boolean suggestSplit(PipelineHelper<P_IN, P_OUT> helper, Spliterator spliterator, @@ -151,7 +164,8 @@ } /** - * Suggest whether it is adviseable to split this task based on target size and other considerations + * Suggest whether it is adviseable to split this task based on target size + * and other considerations */ public boolean suggestSplit() { return suggestSplit(helper, spliterator, targetSize); @@ -178,14 +192,18 @@ } /** - * Associate the result with the task, can be retrieved with {@link #getLocalResult} + * Associate the result with the task, can be retrieved with + * {@link #getLocalResult} */ protected void setLocalResult(R localResult) { this.localResult = localResult; } - /** Is this task a leaf node? (Only valid after {@link #compute} has been called on this node). - * If the node is not a leaf node, then children will be non-null and numChildren will be positive. */ + /** + * Is this task a leaf node? (Only valid after {@link #compute} has been + * called on this node). If the node is not a leaf node, then children will + * be non-null and numChildren will be positive. + */ protected boolean isLeaf() { return children == null; } @@ -219,20 +237,22 @@ } /** - * Decide whether or not to split a task further or compute it directly. - * If computing directly, call {@code doLeaf} and pass the result to + * Decide whether or not to split a task further or compute it directly. If + * computing directly, call {@code doLeaf} and pass the result to * {@code setRawResult}. If splitting, set up the child-related fields, - * create the child tasks, fork the leftmost (prefix) child tasks, - * and compute the rightmost (remaining) child tasks. + * create the child tasks, fork the leftmost (prefix) child tasks, and + * compute the rightmost (remaining) child tasks. * - * <p>Computing will continue for rightmost tasks while a task - * can be computed as determined by {@link #canCompute()} and that - * task should and can be split into left and right tasks. + * <p> + * Computing will continue for rightmost tasks while a task can be computed + * as determined by {@link #canCompute()} and that task should and can be + * split into left and right tasks. * - * <p>The rightmost tasks are computed in a loop rather than recursively to - * avoid potential stack overflows when computing with a right-balanced tree, - * such as that produced when splitting with a {@link Spliterator} created - * from an {@link java.util.Iterator}. + * <p> + * The rightmost tasks are computed in a loop rather than recursively to + * avoid potential stack overflows when computing with a right-balanced + * tree, such as that produced when splitting with a {@link Spliterator} + * created from an {@link java.util.Iterator}. * * @param task the task to be computed. */ @@ -260,8 +280,9 @@ /** * @inheritDoc - * Clears spliterator and children fields. - * Overriders MUST call {@code super.onCompletion} as the last thing they do if they want these cleared + * Clears spliterator and children fields. Overriders MUST call + * {@code super.onCompletion} as the last thing they do if they want these + * cleared */ @Override public void onCompletion(CountedCompleter<?> caller) { @@ -273,9 +294,10 @@ * Determine if the task can be computed. * * @return true if this task can be computed to either calculate the leaf - * via {@link #doLeaf()} or split, otherwise false if this task cannot be - * computed, for example if this task has been cancelled and/or a result - * for the computation has been found by another task. + * via {@link #doLeaf()} or split, otherwise false if this task + * cannot be computed, for example if this task has been cancelled + * and/or a result for the computation has been found by another + * task. */ protected boolean canCompute() { return true;
--- a/src/share/classes/java/util/stream/BaseStream.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/BaseStream.java Thu Feb 28 18:35:14 2013 +0100 @@ -28,8 +28,8 @@ import java.util.Spliterator; /** - * Base interface for stream types such as {@link Stream}, {@link IntStream}, etc. Contains methods common to all - * stream types. + * Base interface for stream types such as {@link Stream}, {@link IntStream}, + * etc. Contains methods common to all stream types. * * @param <T> Type of stream elements. * @since 1.8 @@ -59,26 +59,30 @@ boolean isParallel(); /** - * Return the composition of stream flags of the stream source and all intermediate operations. + * Return the composition of stream flags of the stream source and all + * intermediate operations. * - * @return the composition of stream flags of the stream source and all intermediate operations + * @return the composition of stream flags of the stream source and all + * intermediate operations * @see StreamOpFlag */ int getStreamFlags(); /** - * Produce a stream which has the same contents as this stream, but is a sequential stream. If this stream is - * already sequential, may return itself. This is - * a <a href="package-summary.html#StreamOps">stateful intermediate operation</a>. + * Produce a stream which has the same contents as this stream, but is a + * sequential stream. If this stream is already sequential, may return + * itself. This is a + * <a href="package-summary.html#StreamOps">stateful intermediate operation</a>. * * @return a sequential stream */ S sequential(); /** - * Produce a stream which has the same contents as this stream, but is a parallel stream. If this stream is - * already parallel, may return itself. This is - * a <a href="package-summary.html#StreamOps">stateful intermediate operation</a>. + * Produce a stream which has the same contents as this stream, but is a + * parallel stream. If this stream is already parallel, may return itself. + * This is a + * <a href="package-summary.html#StreamOps">stateful intermediate operation</a>. * * @return a parallel stream */
--- a/src/share/classes/java/util/stream/FindOp.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/FindOp.java Thu Feb 28 18:35:14 2013 +0100 @@ -30,8 +30,9 @@ import java.util.function.Supplier; /** - * A short-circuiting {@code TerminalOp} that searches for an element in a stream pipeline, and terminates when - * it finds one. Implements both find-first (find the first element in the encounter order) and find-any (find + * A short-circuiting {@code TerminalOp} that searches for an element in a + * stream pipeline, and terminates when it finds one. Implements both + * find-first (find the first element in the encounter order) and find-any (find * any element, may not be the first in encounter order.) * * @param <T> The output type of the stream pipeline @@ -42,7 +43,9 @@ /** * Construct a {@code FindOp} for streams of objects - * @param mustFindFirst Whether the {@code FindOp} must produce the first element in the encounter order + * + * @param mustFindFirst Whether the {@code FindOp} must produce the first + * element in the encounter order * @param <T> The type of elements of the stream * @return A {@code FindOp} implementing the find operation */ @@ -52,7 +55,9 @@ /** * Construct a {@code FindOp} for streams of ints - * @param mustFindFirst Whether the {@code FindOp} must produce the first element in the encounter order + * + * @param mustFindFirst Whether the {@code FindOp} must produce the first + * element in the encounter order * @return A {@code FindOp} implementing the find operation */ public static FindOp<Integer, OptionalInt> makeInt(boolean mustFindFirst) { @@ -61,7 +66,9 @@ /** * Construct a {@code FindOp} for streams of longs - * @param mustFindFirst Whether the {@code FindOp} must produce the first element in the encounter order + * + * @param mustFindFirst Whether the {@code FindOp} must produce the first + * element in the encounter order * @return A {@code FindOp} implementing the find operation */ public static FindOp<Long, OptionalLong> makeLong(boolean mustFindFirst) { @@ -70,7 +77,9 @@ /** * Construct a {@code FindOp} for streams of doubles - * @param mustFindFirst Whether the {@code FindOp} must produce the first element in the encounter order + * + * @param mustFindFirst Whether the {@code FindOp} must produce the first + * element in the encounter order * @return A {@code FindOp} implementing the find operation */ public static FindOp<Double, OptionalDouble> makeDouble(boolean mustFindFirst) { @@ -78,8 +87,8 @@ } /** - * Implementation of @{code TerminalSink} that implements the find functionality, requesting cancellation - * when something has been found + * Implementation of @{code TerminalSink} that implements the find + * functionality, requesting cancellation when something has been found * * @param <T> The type of input element * @param <O> The result type, typically an optional type @@ -162,11 +171,15 @@ /** * Construct a {@code FindOp} - * @param mustFindFirst If true, must find the first element in encounter order, otherwise can find any element + * + * @param mustFindFirst If true, must find the first element in encounter + * order, otherwise can find any element * @param shape Stream shape of elements to search * @param emptyValue Result value corresponding to "found nothing" - * @param presentPredicate {@code Predicate} on result value corresponding to "found something" - * @param sinkSupplier Factory for a {@code TerminalSink} implementing the matching functionality + * @param presentPredicate {@code Predicate} on result value corresponding + * to "found something" + * @param sinkSupplier Factory for a {@code TerminalSink} implementing the + * matching functionality */ private FindOp(boolean mustFindFirst, StreamShape shape,
--- a/src/share/classes/java/util/stream/ForEachOp.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/ForEachOp.java Thu Feb 28 18:35:14 2013 +0100 @@ -33,9 +33,10 @@ import java.util.Objects; /** - * A {@code TerminalOp} that evaluates a stream pipeline and sends the output into a {@code TerminalSink}. - * Elements will be passed to the {@code TerminalSink} in whatever thread and whatever order they become available, - * independent of the stream's encounter order. + * A {@code TerminalOp} that evaluates a stream pipeline and sends the output + * into a {@code TerminalSink}. Elements will be passed to the + * {@code TerminalSink} in whatever thread and whatever order they become + * available, independent of the stream's encounter order. * @param <T> The output type of the stream pipeline * @since 1.8 */ @@ -44,7 +45,9 @@ protected final StreamShape shape; /** - * Construct a {@code ForEachOp} that sends the stream output to the provided {@code TerminalSink} + * Construct a {@code ForEachOp} that sends the stream output to the + * provided {@code TerminalSink} + * * @param sink The {@code TerminalSink} to send stream output to * @param shape The output shape of the stream pipeline */ @@ -60,19 +63,23 @@ return null; } - /** Specialization of {@code TerminalSink} and {@code Sink.OfInt} with void result */ + /** Specialization of {@code TerminalSink} and {@code Sink.OfInt} with + * void result */ interface OfInt extends VoidTerminalSink<Integer>, Sink.OfInt { } - /** Specialization of {@code TerminalSink} and {@code Sink.OfLong} with void result */ + /** Specialization of {@code TerminalSink} and {@code Sink.OfLong} with + * void result */ interface OfLong extends VoidTerminalSink<Long>, Sink.OfLong { } - /** Specialization of {@code TerminalSink} and {@code Sink.OfDouble} with void result */ + /** Specialization of {@code TerminalSink} and {@code Sink.OfDouble} + * with void result */ interface OfDouble extends VoidTerminalSink<Double>, Sink.OfDouble { } } /** - * Construct a {@code ForEachOp} that reads from a {@code Stream} and sends the stream output to - * the provided {@code Consumer} + * Construct a {@code ForEachOp} that reads from a {@code Stream} and sends + * the stream output to the provided {@code Consumer} + * * @param consumer The {@code Consumer} to send stream output to */ public static <T> TerminalOp<T, Void> makeRef(final Consumer<? super T> consumer) { @@ -80,8 +87,9 @@ } /** - * Construct a {@code ForEachOp} that reads from an {@code IntStream} and sends the stream output to - * the provided {@code IntConsumer} + * Construct a {@code ForEachOp} that reads from an {@code IntStream} and + * sends the stream output to the provided {@code IntConsumer} + * * @param consumer The {@code IntConsumer} to send stream output to */ public static TerminalOp<Integer, Void> makeInt(final IntConsumer consumer) { @@ -89,8 +97,9 @@ } /** - * Construct a {@code ForEachOp} that reads from a {@code LongStream} and sends the stream output to - * the provided {@code LongConsumer} + * Construct a {@code ForEachOp} that reads from a {@code LongStream} and + * sends the stream output to the provided {@code LongConsumer} + * * @param consumer The {@code LongConsumer} to send stream output to */ public static TerminalOp<Long, Void> makeLong(final LongConsumer consumer) { @@ -98,8 +107,9 @@ } /** - * Construct a {@code ForEachOp} that reads from a {@code DoubleStream} and sends the stream output to - * the provided {@code DoubleConsumer} + * Construct a {@code ForEachOp} that reads from a {@code DoubleStream} and + * sends the stream output to the provided {@code DoubleConsumer} + * * @param consumer The {@code DoubleConsumer} to send stream output to */ public static TerminalOp<Double, Void> makeDouble(final DoubleConsumer consumer) {
--- a/src/share/classes/java/util/stream/ForEachUntilOp.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/ForEachUntilOp.java Thu Feb 28 18:35:14 2013 +0100 @@ -32,19 +32,23 @@ import java.util.function.LongConsumer; /** - * A {@code TerminalOp} that evaluates a stream pipeline and sends the output into a {@code TerminalSink}, attempting - * to stop early if some external termination condition is reached. + * A {@code TerminalOp} that evaluates a stream pipeline and sends the output + * into a {@code TerminalSink}, attempting to stop early if some external + * termination condition is reached. * * @apiNote - * The termination condition is an externally-imposed criteria, and is useful for problems like "find the best - * answer that can be found in ten seconds", "search until you find an answer at least as good as X", etc. It is not - * designed to provide content-based cancellation, such as "process elements until you find one which matches - * a given criteria." + * The termination condition is an externally-imposed criteria, and is useful + * for problems like "find the best answer that can be found in ten seconds", + * "search until you find an answer at least as good as X", etc. It is not + * designed to provide content-based cancellation, such as "process elements + * until you find one which matches a given criteria." * - * <p>There is no guarantee that additional elements will not be processed after the termination criteria has - * transpired. For example, a termination criteria of {@code resultSet.size() > TARGET} does not guarantee that the - * result set will receive no more than {@code TARGET} elements, but instead that @{code ForEachUntilOp} will attempt - * to stop after {@code TARGET} elements have been placed in the result set. + * <p>There is no guarantee that additional elements will not be processed after + * the termination criteria has transpired. For example, a termination criteria + * of {@code resultSet.size() > TARGET} does not guarantee that the result set + * will receive no more than {@code TARGET} elements, but instead that + * @{code ForEachUntilOp} will attempt to stop after {@code TARGET} elements + * have been placed in the result set. * * @param <T> The output type of the stream pipeline * @since 1.8 @@ -56,13 +60,16 @@ } /** - * Construct a {@code ForEachUntilOp} that reads from a {@code Stream} and sends the stream output to - * the provided {@code Consumer}, until the specified {@code BooleanProvider} indicates that no more input - * should be sent + * Construct a {@code ForEachUntilOp} that reads from a {@code Stream} and + * sends the stream output to the provided {@code Consumer}, until the + * specified {@code BooleanProvider} indicates that no more input should be + * sent + * * @param consumer The {@code Consumer} to send stream output to - * @param until A {@code BooleanSupplier} that indicates whether the termination criteria has occurred. Once - * it returns @{code true} the first time, it must continue to return {@code true} for all future - * invocations + * @param until A {@code BooleanSupplier} that indicates whether the + * termination criteria has occurred. Once it returns @{code true} + * the first time, it must continue to return {@code true} for all + * future invocations * @param <T> The type of the stream elements */ public static <T> ForEachUntilOp<T> make(final Consumer<? super T> consumer, BooleanSupplier until) { @@ -81,13 +88,16 @@ } /** - * Construct a {@code ForEachUntilOp} that reads from an {@code IntStream} and sends the stream output to - * the provided {@code Consumer}, until the specified {@code BooleanProvider} indicates that no more input - * should be sent + * Construct a {@code ForEachUntilOp} that reads from an {@code IntStream} + * and sends the stream output to the provided {@code Consumer}, until the + * specified {@code BooleanProvider} indicates that no more input should be + * sent + * * @param consumer The {@code Consumer} to send stream output to - * @param until A {@code BooleanSupplier} that indicates whether the termination criteria has occurred. Once - * it returns @{code true} the first time, it must continue to return {@code true} for all future - * invocations + * @param until A {@code BooleanSupplier} that indicates whether the + * termination criteria has occurred. Once it returns @{code true} + * the first time, it must continue to return {@code true} for all + * future invocations */ public static ForEachUntilOp<Integer> make(final IntConsumer consumer, BooleanSupplier until) { Objects.requireNonNull(consumer); @@ -105,13 +115,16 @@ } /** - * Construct a {@code ForEachUntilOp} that reads from a {@code LongStream} and sends the stream output to - * the provided {@code Consumer}, until the specified {@code BooleanProvider} indicates that no more input - * should be sent + * Construct a {@code ForEachUntilOp} that reads from a {@code LongStream} + * and sends the stream output to the provided {@code Consumer}, until the + * specified {@code BooleanProvider} indicates that no more input should be + * sent + * * @param consumer The {@code Consumer} to send stream output to - * @param until A {@code BooleanSupplier} that indicates whether the termination criteria has occurred. Once - * it returns @{code true} the first time, it must continue to return {@code true} for all future - * invocations + * @param until A {@code BooleanSupplier} that indicates whether the + * termination criteria has occurred. Once it returns + * @{code true} the first time, it must continue to return + * {@code true} for all future invocations */ public static ForEachUntilOp<Long> make(final LongConsumer consumer, BooleanSupplier until) { Objects.requireNonNull(consumer); @@ -129,13 +142,16 @@ } /** - * Construct a {@code ForEachUntilOp} that reads from a {@code DoubleStream} and sends the stream output to - * the provided {@code Consumer}, until the specified {@code BooleanProvider} indicates that no more input - * should be sent + * Construct a {@code ForEachUntilOp} that reads from a {@code DoubleStream} + * and sends the stream output to the provided {@code Consumer}, until the + * specified {@code BooleanProvider} indicates that no more input should be + * sent + * * @param consumer The {@code Consumer} to send stream output to - * @param until A {@code BooleanSupplier} that indicates whether the termination criteria has occurred. Once - * it returns @{code true} the first time, it must continue to return {@code true} for all future - * invocations + * @param until A {@code BooleanSupplier} that indicates whether the + * termination criteria has occurred. Once it returns @{code true} + * the first time, it must continue to return {@code true} for all + * future invocations */ public static ForEachUntilOp<Double> make(final DoubleConsumer consumer, BooleanSupplier until) { Objects.requireNonNull(consumer);
--- a/src/share/classes/java/util/stream/IntermediateOp.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/IntermediateOp.java Thu Feb 28 18:35:14 2013 +0100 @@ -25,41 +25,53 @@ package java.util.stream; /** - * An operation in a stream pipeline that takes a stream as input and produces a stream, possibly of a different - * type, as output. An intermediate operation has an input type and an output type (and, an associated input - * shape and output shape). An intermediate operation also has a set of <em>operation flags</em> that describes - * how it transforms characteristics of the stream (such as sortedness or size; see {@link StreamOpFlag}). + * An operation in a stream pipeline that takes a stream as input and produces + * a stream, possibly of a different type, as output. An intermediate operation + * has an input type and an output type (and, an associated input shape and + * output shape). An intermediate operation also has a set of <em>operation + * flags</em> that describes how it transforms characteristics of the stream + * (such as sortedness or size; see {@link StreamOpFlag}). * - * <p>Intermediate operations are implemented in terms of <em>sink transforms</em>; given a {@code Sink} for the - * output type of the operation, produce a {@code Sink} for the input type of the operation, which, when fed with - * values, has the effect of implementing the desired operation on the input values and feeding them to the output - * sink. + * <p>Intermediate operations are implemented in terms of <em>sink transforms + * </em>; given a {@code Sink} for the output type of the operation, produce a + * {@code Sink} for the input type of the operation, which, when fed with + * values, has the effect of implementing the desired operation on the input + * values and feeding them to the output sink. * - * <p>Some intermediate operations are <em>stateful</em>. This means that the sinks they produce as a result of - * the above wrapping may maintain state from processing earlier elements. Stateful intermediate operations must - * implement the {@link StatefulOp} interface. Statefulness has an effect on how the operation can be parallelized. - * Stateless operations parallelize trivially because they are homomorphisms under concatenation: + * <p>Some intermediate operations are <em>stateful</em>. This means that the + * sinks they produce as a result of the above wrapping may maintain state from + * processing earlier elements. Stateful intermediate operations must implement + * the {@link StatefulOp} interface. Statefulness has an effect on how the + * operation can be parallelized. Stateless operations parallelize trivially + * because they are homomorphisms under concatenation: * * <pre> * statelessOp(a || b) = statelessOp(a) || statelessOp(b) * </pre> * - * where {@code ||} denotes concatenation. Stateful operations may still be parallelizable, but are not amenable to - * the automatic parallelization of stateless operations. Accordingly, a stateful operation must provide its - * own parallel execution implementation ({@link StatefulOp#evaluateParallel(PipelineHelper)}). + * where {@code ||} denotes concatenation. Stateful operations may still be + * parallelizable, but are not amenable to the automatic parallelization of + * stateless operations. Accordingly, a stateful operation must provide its own + * parallel execution implementation + * ({@link StatefulOp#evaluateParallel(PipelineHelper)}). * * @apiNote * As an example, consider the stream pipeline: * <pre> - * int oldestBob = people.stream().filter(p -> p.getFirstName.equals("Bob")).map(p -> p.getAge()).max(); + * int oldestBob = people.stream(). + * filter(p -> p.getFirstName.equals("Bob")). + * map(p -> p.getAge()).max(); * </pre> * - * <p>This pipeline has two intermediate operations, filter and map. The filtering operation has input and output types - * of {@code Person} (with input and output shape of {@code REFERENCE}), and the mapping operation has an input - * type of {@code Person} and an output type of {@code Integer} (with shape {@code INT_VALUE}.) When we construct - * a sink chain, the mapping operation will be asked to transform a {@code Sink.OfInt} which computes the maximum - * value into a {@code Sink} which accepts {@code Person} objects, and whose behavior is to take the supplied - * {@code Person}, call {@code getAge()} on it, and pass the resulting value to the downstream sink. This sink + * <p>This pipeline has two intermediate operations, filter and map. The + * filtering operation has input and output types of {@code Person} (with input + * and output shape of {@code REFERENCE}), and the mapping operation has an + * input type of {@code Person} and an output type of {@code Integer} (with + * shape {@code INT_VALUE}.) When we construct a sink chain, the mapping + * operation will be asked to transform a {@code Sink.OfInt} which computes the + * maximum value into a {@code Sink} which accepts {@code Person} objects, and + * whose behavior is to take the supplied {@code Person}, call {@code getAge()} + * on it, and pass the resulting value to the downstream sink. This sink * transform might be implement as: * * <pre> @@ -102,8 +114,9 @@ default int getOpFlags() { return 0; } /** - * Return whether this operation is stateful or not. If it is stateful, then the method - * {@link #evaluateParallel(PipelineHelper)} must be overridden. + * Return whether this operation is stateful or not. If it is stateful, + * then the method {@link #evaluateParallel(PipelineHelper)} must be + * overridden. * * @implSpec The default implementation returns {@code false}. * @@ -112,27 +125,34 @@ default boolean isStateful() { return false; } /** - * Accept a {@code Sink} which will receive the results of this operation, and return a {@code Sink} - * which accepts elements of the input type of this operation and which performs the operation, passing - * the results to the provided {@code Sink}. + * Accept a {@code Sink} which will receive the results of this operation, + * and return a {@code Sink} which accepts elements of the input type of + * this operation and which performs the operation, passing the results to + * the provided {@code Sink}. * - * <p>The implementation may use the {@code flags} parameter to optimize the sink wrapping. For example, if - * the input is already {@code DISTINCT}, the implementation for the {@code Stream#distinct()} method could - * just return the sink it was passed. + * <p>The implementation may use the {@code flags} parameter to optimize the + * sink wrapping. For example, if the input is already {@code DISTINCT}, + * the implementation for the {@code Stream#distinct()} method could just + * return the sink it was passed. * - * @param flags The combined stream and operation flags up to, but not including, this operation. + * @param flags The combined stream and operation flags up to, but not + * including, this operation. * @param sink elements will be sent to this sink after the processing. * @return a sink which will accept elements and perform the operation upon - * each element, passing the results (if any) to the provided {@code Sink}. + * each element, passing the results (if any) to the provided + * {@code Sink}. */ Sink<E_IN> wrapSink(int flags, Sink<E_OUT> sink); /** - * Perform a parallel evaluation of the operation using the specified {@code PipelineHelper}, which describes - * the stream source and upstream intermediate operations. Only called on stateful operations. - * If {@link #isStateful()} returns true then implementations must override the default implementation. + * Perform a parallel evaluation of the operation using the specified + * {@code PipelineHelper}, which describes the stream source and upstream + * intermediate operations. Only called on stateful operations. If + * {@link #isStateful()} returns true then implementations must override the + * default implementation. * - * @implSpec The default implementation throws an {@link UnsupportedOperationException} + * @implSpec The default implementation throws an + * {@link UnsupportedOperationException} * * @param helper the pipeline helper * @param <P_IN> the type of elements in the pipeline source
--- a/src/share/classes/java/util/stream/MatchOp.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/MatchOp.java Thu Feb 28 18:35:14 2013 +0100 @@ -32,8 +32,9 @@ import java.util.function.Supplier; /** - * A short-circuiting {@code TerminalOp} that evaluates a predicate on the elements of a stream pipeline - * and determines whether all, any, or none of the elements match a given {@code Predicate}. + * A short-circuiting {@code TerminalOp} that evaluates a predicate on the + * elements of a stream pipeline and determines whether all, any, or none of the + * elements match a given {@code Predicate}. * * @param <T> The output type of the stream pipeline * @since 1.8 @@ -45,10 +46,11 @@ /** * Construct a {@code MatchOp} + * * @param shape The output shape of the stream pipeline * @param matchKind The kind of quantified match (all, any, none) - * @param sinkSupplier {@code Supplier} for a {@code Sink} of the appropriate shape which implements the - * matching operation + * @param sinkSupplier {@code Supplier} for a {@code Sink} of the appropriate + * shape which implements the matching operation */ private MatchOp(StreamShape shape, MatchKind matchKind, Supplier<BooleanTerminalSink<T>> sinkSupplier) { this.inputShape = shape; @@ -59,8 +61,9 @@ // Boolean specific terminal sink to avoid the boxing costs when returning results /** - * Base class for match sink variants. Subclasses implement the shape-specific functionality and implement - * {@code TerminalSink}. + * Base class for match sink variants. Subclasses implement the + * shape-specific functionality and implement {@code TerminalSink}. + * * @param <T> The output type of the stream pipeline */ private static abstract class BooleanTerminalSink<T> implements Sink<T> { @@ -82,7 +85,9 @@ } /** - * Construct a {@code MatchOp} for the given predicate and quantified match criteria + * Construct a {@code MatchOp} for the given predicate and quantified match + * criteria + * * @param predicate The {@code Predicate} to apply to stream elements * @param matchKind The kind of quantified match (all, any, none) * @param <T> The type of stream elements @@ -114,7 +119,9 @@ } /** - * Construct a {@code MatchOp} for the given predicate and quantified match criteria for an {@code IntStream} + * Construct a {@code MatchOp} for the given predicate and quantified match + * criteria for an {@code IntStream} + * * @param predicate The {@code Predicate} to apply to stream elements * @param matchKind The kind of quantified match (all, any, none) * @return A {@code MatchOp} implementing the desired quantified match criteria @@ -142,7 +149,9 @@ } /** - * Construct a {@code MatchOp} for the given predicate and quantified match criteria for a {@code LongStream} + * Construct a {@code MatchOp} for the given predicate and quantified match + * criteria for a {@code LongStream} + * * @param predicate The {@code Predicate} to apply to stream elements * @param matchKind The kind of quantified match (all, any, none) * @return A {@code MatchOp} implementing the desired quantified match criteria @@ -171,7 +180,9 @@ } /** - * Construct a {@code MatchOp} for the given predicate and quantified match criteria for a {@code DoubleStream} + * Construct a {@code MatchOp} for the given predicate and quantified match + * criteria for a {@code DoubleStream} + * * @param predicate The {@code Predicate} to apply to stream elements * @param matchKind The kind of quantified match (all, any, none) * @return A {@code MatchOp} implementing the desired quantified match criteria @@ -226,7 +237,9 @@ } /** - * ForkJoinTask implementation to implement a parallel short-circuiting quantified match + * ForkJoinTask implementation to implement a parallel short-circuiting + * quantified match + * * @param <S> The type of source elements for the pipeline * @param <T> The type of output elements for the pipeline */ @@ -263,7 +276,8 @@ } /** - * Enum describing quantified match options -- all match, any match, none match + * Enum describing quantified match options -- all match, any match, none + * match */ enum MatchKind { /** Do all elements match the predicate? */
--- a/src/share/classes/java/util/stream/Node.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/Node.java Thu Feb 28 18:35:14 2013 +0100 @@ -32,21 +32,28 @@ import java.util.function.LongConsumer; /** - * An immutable container for describing an ordered sequence of elements of some type {@code T}. + * An immutable container for describing an ordered sequence of elements of some + * type {@code T}. * - * <p>A {@code Node} contains a fixed number of elements, which can be accessed via the {@link #count}, - * {@link #spliterator}, {@link #forEach}, {@link #asArray}, or {@link #copyInto} methods. - * A {@code Node} may have zero or more child {@code Node}s; if it has no children (accessed via {@link #getChildCount} - * and {@link #getChild(int)}, it is considered <em>flat</em> or a <em>leaf</em>; if it has children, it is considered - * an <em>internal</em> node. The size of an internal node is the sum of sizes of its children. + * <p>A {@code Node} contains a fixed number of elements, which can be accessed + * via the {@link #count}, {@link #spliterator}, {@link #forEach}, + * {@link #asArray}, or {@link #copyInto} methods. A {@code Node} may have zero + * or more child {@code Node}s; if it has no children (accessed via + * {@link #getChildCount} and {@link #getChild(int)}, it is considered <em>flat + * </em> or a <em>leaf</em>; if it has children, it is considered an + * <em>internal</em> node. The size of an internal node is the sum of sizes of + * its children. * * @apiNote - * <p>A {@code Node} typically does not store the elements directly, but instead mediates access to one or more - * existing (effectively immutable) data structures such as a {@code Collection}, array, or a set of other - * {@code Node}s. {@code Node}s directly representing existing data structures are considered <em>flat</em> - * (have no children); commonly {@code Node}s are formed into a tree whose shape corresponds to the computation - * tree that produced the elements that are contained in the leaf nodes. The use of {@code Node} within the - * stream framework is largely to avoid copying data unnecessarily during parallel operations. + * <p>A {@code Node} typically does not store the elements directly, but instead + * mediates access to one or more existing (effectively immutable) data + * structures such as a {@code Collection}, array, or a set of other + * {@code Node}s. {@code Node}s directly representing existing data structures + * are considered <em>flat</em> (have no children); commonly {@code Node}s are + * formed into a tree whose shape corresponds to the computation tree that + * produced the elements that are contained in the leaf nodes. The use of + * {@code Node} within the stream framework is largely to avoid copying data + * unnecessarily during parallel operations. * * @param <T> the type of elements. * @since 1.8 @@ -54,16 +61,20 @@ interface Node<T> { /** - * Return a {@link Spliterator} describing the elements contained in this {@code Node}. + * Return a {@link Spliterator} describing the elements contained in this + * {@code Node}. * - * @return a {@code Spliterator describing the elements contained in this {@code Node}. + * @return a {@code Spliterator describing the elements contained in this + * {@code Node}. */ Spliterator<T> spliterator(); /** - * Traverse the elements of this node, and invoke the provided {@code Consumer} with each element. + * Traverse the elements of this node, and invoke the provided + * {@code Consumer} with each element. * - * @param consumer A {@code Consumer} that is to be invoked with each element in this {@code Node} + * @param consumer A {@code Consumer} that is to be invoked with each + * element in this {@code Node} */ void forEach(Consumer<? super T> consumer); @@ -80,10 +91,12 @@ /** * Retrieve the child {@code Node} at a given index. * - * @implSpec The default implementation throws {@code IndexOutOfBoundsException} + * @implSpec The default implementation throws + * {@code IndexOutOfBoundsException} * @param i the index to the child node * @return the child node - * @throws IndexOutOfBoundsException if the index is less than 0 or greater than or equal to the + * @throws IndexOutOfBoundsException if the index is less than 0 or greater + * than or equal to the * number of child nodes. */ default Node<T> getChild(int i) { @@ -93,28 +106,33 @@ /** * View this node as an array. * - * <p>Depending on the underlying implementation this may return a reference to an internal array rather than - * a copy. It is the callers responsibility to decide if either this node or the array is - * utilized as the primary reference for the data.</p> + * <p>Depending on the underlying implementation this may return a reference + * to an internal array rather than a copy. It is the callers + * responsibility to decide if either this node or the array is utilized as + * the primary reference for the data.</p> * * @return an array containing the contents of this {@code Node} */ T[] asArray(IntFunction<T[]> generator); /** - * Copy the content of this {@code Node} into an array, starting at a given offset into the array. It is the - * caller's responsibility to ensure there is sufficient room in the array. + * Copy the content of this {@code Node} into an array, starting at a given + * offset into the array. It is the caller's responsibility to ensure there + * is sufficient room in the array. * - * @param array the array into which to copy the contents of this {@code Node} + * @param array the array into which to copy the contents of this + * {@code Node} * @param offset the starting offset within the array - * @throws IndexOutOfBoundsException if copying would cause access of data outside array bounds + * @throws IndexOutOfBoundsException if copying would cause access of data + * outside array bounds * @throws NullPointerException if {@code array} is {@code null} */ void copyInto(T[] array, int offset); /** * Get the {@code StreamShape} associated with this {@code Node}. - * @implSpec The default in {@code Node} returns {@code StreamShape.REFERENCE} + * @implSpec The default in {@code Node} returns + * {@code StreamShape.REFERENCE} * @return the stream shape associated with this node */ default StreamShape getShape() { @@ -129,15 +147,15 @@ long count(); /** - * A mutable builder for a {@code Node} that implements {@link Sink}, which builds a flat node containing the - * elements that have been pushed to it. + * A mutable builder for a {@code Node} that implements {@link Sink}, which + * builds a flat node containing the elements that have been pushed to it. * */ interface Builder<T> extends Sink<T> { /** - * Build the node. Should be called after all elements have been pushed and signalled with - * an invocation of {@link Sink#end()}. + * Build the node. Should be called after all elements have been pushed + * and signalled with an invocation of {@link Sink#end()}. * * @return the resulting {@code Node} */ @@ -167,16 +185,18 @@ /** * {@inheritDoc} - * @return A {@link Spliterator.OfInt} describing the elements of this node + * @return A {@link Spliterator.OfInt} describing the elements of this + * node */ @Override Spliterator.OfInt spliterator(); /** * {@inheritDoc} - * @param consumer A {@code Consumer} that is to be invoked with each element in this {@code Node}. If this - * is an {@code IntConsumer}, it is cast to {@code IntConsumer} so the elements may be - * processed without boxing. + * @param consumer A {@code Consumer} that is to be invoked with each + * element in this {@code Node}. If this is an + * {@code IntConsumer}, it is cast to {@code IntConsumer} so the + * elements may be processed without boxing. */ @Override default void forEach(Consumer<? super Integer> consumer) { @@ -191,18 +211,21 @@ } /** - * Traverse the elements of this node, and invoke the provided {@code IntConsumer} with each element. + * Traverse the elements of this node, and invoke the provided + * {@code IntConsumer} with each element. * - * @param consumer A {@code IntConsumer} that is to be invoked with each element in this {@code Node} + * @param consumer A {@code IntConsumer} that is to be invoked with each + * element in this {@code Node} */ void forEach(IntConsumer consumer); /** * {@inheritDoc} - * @implSpec the default implementation invokes the generator to create an instance of an Integer[] - * array with a length of {@link #count()} and then invokes {@link #copyInto(Integer[], int)} with that - * Integer[] array at an offset of 0. - * This is not efficient and it is recommended to invoke {@link #asIntArray()}. + * @implSpec the default implementation invokes the generator to create + * an instance of an Integer[] array with a length of {@link #count()} + * and then invokes {@link #copyInto(Integer[], int)} with that + * Integer[] array at an offset of 0. This is not efficient and it is + * recommended to invoke {@link #asIntArray()}. */ @Override default Integer[] asArray(IntFunction<Integer[]> generator) { @@ -213,9 +236,10 @@ /** * {@inheritDoc} - * @implSpec the default implementation invokes {@link #asIntArray()} to obtain an int[] array then - * and copies the elements from that int[] array into the boxed Integer[] array. - * This is not efficient and it is recommended to invoke {@link #copyInto(int[], int)}. + * @implSpec the default implementation invokes {@link #asIntArray()} to + * obtain an int[] array then and copies the elements from that int[] + * array into the boxed Integer[] array. This is not efficient and it + * is recommended to invoke {@link #copyInto(int[], int)}. */ @Override default void copyInto(Integer[] boxed, int offset) { @@ -236,28 +260,32 @@ /** * View this node as an int[] array. * - * <p>Depending on the underlying implementation this may return a reference to an internal array rather than - * a copy. It is the callers responsibility to decide if either this node or the array is - * utilized as the primary reference for the data.</p> + * <p>Depending on the underlying implementation this may return a + * reference to an internal array rather than a copy. It is the callers + * responsibility to decide if either this node or the array is utilized + * as the primary reference for the data.</p> * * @return an array containing the contents of this {@code Node} */ int[] asIntArray(); /** - * Copy the content of this {@code Node} into an int[] array, starting at a given offset into the array. - * It is the caller's responsibility to ensure there is sufficient room in the array. + * Copy the content of this {@code Node} into an int[] array, starting + * at a given offset into the array. It is the caller's responsibility + * to ensure there is sufficient room in the array. * * @param array the array into which to copy the contents of this {@code Node} * @param offset the starting offset within the array - * @throws IndexOutOfBoundsException if copying would cause access of data outside array bounds + * @throws IndexOutOfBoundsException if copying would cause access of + * data outside array bounds * @throws NullPointerException if {@code array} is {@code null} */ void copyInto(int[] array, int offset); /** * {@inheritDoc} - * @implSpec The default in {@code Node.OfInt} returns {@code StreamShape.INT_VALUE} + * @implSpec The default in {@code Node.OfInt} returns + * {@code StreamShape.INT_VALUE} */ default StreamShape getShape() { return StreamShape.INT_VALUE; @@ -269,16 +297,18 @@ /** * {@inheritDoc} - * @return A {@link Spliterator.OfLong} describing the elements of this node + * @return A {@link Spliterator.OfLong} describing the elements of this + * node */ @Override Spliterator.OfLong spliterator(); /** * {@inheritDoc} - * @param consumer A {@code Consumer} that is to be invoked with each element in this {@code Node}. If this - * is an {@code LongConsumer}, it is cast to {@code LongConsumer} so the elements may be - * processed without boxing. + * @param consumer A {@code Consumer} that is to be invoked with each + * element in this {@code Node}. If this is an + * {@code LongConsumer}, it is cast to {@code LongConsumer} so + * the elements may be processed without boxing. */ @Override default void forEach(Consumer<? super Long> consumer) { @@ -293,18 +323,21 @@ } /** - * Traverse the elements of this node, and invoke the provided {@code LongConsumer} with each element. + * Traverse the elements of this node, and invoke the provided + * {@code LongConsumer} with each element. * - * @param consumer A {@code LongConsumer} that is to be invoked with each element in this {@code Node} + * @param consumer A {@code LongConsumer} that is to be invoked with + * each element in this {@code Node} */ void forEach(LongConsumer consumer); /** * {@inheritDoc} - * @implSpec the default implementation invokes the generator to create an instance of a Long[] - * array with a length of {@link #count()} and then invokes {@link #copyInto(Long[], int)} with that - * Long[] array at an offset of 0. - * This is not efficient and it is recommended to invoke {@link #asLongArray()}. + * @implSpec the default implementation invokes the generator to create + * an instance of a Long[] array with a length of {@link #count()} and + * then invokes {@link #copyInto(Long[], int)} with that Long[] array at + * an offset of 0. This is not efficient and it is recommended to + * invoke {@link #asLongArray()}. */ @Override default Long[] asArray(IntFunction<Long[]> generator) { @@ -315,9 +348,10 @@ /** * {@inheritDoc} - * @implSpec the default implementation invokes {@link #asLongArray()} to obtain a long[] array then - * and copies the elements from that long[] array into the boxed Long[] array. - * This is not efficient and it is recommended to invoke {@link #copyInto(long[], int)}. + * @implSpec the default implementation invokes {@link #asLongArray()} + * to obtain a long[] array then and copies the elements from that + * long[] array into the boxed Long[] array. This is not efficient and + * it is recommended to invoke {@link #copyInto(long[], int)}. */ @Override default void copyInto(Long[] boxed, int offset) { @@ -338,28 +372,33 @@ /** * View this node as a long[] array. * - * <p>Depending on the underlying implementation this may return a reference to an internal array rather than - * a copy. It is the callers responsibility to decide if either this node or the array is - * utilized as the primary reference for the data.</p> + * <p>Depending on the underlying implementation this may return a + * reference to an internal array rather than a copy. It is the callers + * responsibility to decide if either this node or the array is utilized + * as the primary reference for the data.</p> * * @return an array containing the contents of this {@code Node} */ long[] asLongArray(); /** - * Copy the content of this {@code Node} into a long[] array, starting at a given offset into the array. - * It is the caller's responsibility to ensure there is sufficient room in the array. + * Copy the content of this {@code Node} into a long[] array, starting + * at a given offset into the array. It is the caller's responsibility + * to ensure there is sufficient room in the array. * - * @param array the array into which to copy the contents of this {@code Node} + * @param array the array into which to copy the contents of this + * {@code Node} * @param offset the starting offset within the array - * @throws IndexOutOfBoundsException if copying would cause access of data outside array bounds + * @throws IndexOutOfBoundsException if copying would cause access of + * data outside array bounds * @throws NullPointerException if {@code array} is {@code null} */ void copyInto(long[] array, int offset); /** * {@inheritDoc} - * @implSpec The default in {@code Node.OfLong} returns {@code StreamShape.LONG_VALUE} + * @implSpec The default in {@code Node.OfLong} returns + * {@code StreamShape.LONG_VALUE} */ default StreamShape getShape() { return StreamShape.LONG_VALUE; @@ -371,16 +410,18 @@ /** * {@inheritDoc} - * @return A {@link Spliterator.OfDouble} describing the elements of this node + * @return A {@link Spliterator.OfDouble} describing the elements of + * this node */ @Override Spliterator.OfDouble spliterator(); /** * {@inheritDoc} - * @param consumer A {@code Consumer} that is to be invoked with each element in this {@code Node}. If this - * is an {@code DoubleConsumer}, it is cast to {@code DoubleConsumer} so the elements may be - * processed without boxing. + * @param consumer A {@code Consumer} that is to be invoked with each + * element in this {@code Node}. If this is an + * {@code DoubleConsumer}, it is cast to {@code DoubleConsumer} + * so the elements may be processed without boxing. */ @Override default void forEach(Consumer<? super Double> consumer) { @@ -395,9 +436,11 @@ } /** - * Traverse the elements of this node, and invoke the provided {@code DoubleConsumer} with each element. + * Traverse the elements of this node, and invoke the provided + * {@code DoubleConsumer} with each element. * - * @param consumer A {@code DoubleConsumer} that is to be invoked with each element in this {@code Node} + * @param consumer A {@code DoubleConsumer} that is to be invoked with + * each element in this {@code Node} */ void forEach(DoubleConsumer consumer); @@ -405,10 +448,11 @@ /** * {@inheritDoc} - * @implSpec the default implementation invokes the generator to create an instance of a Double[] - * array with a length of {@link #count()} and then invokes {@link #copyInto(Double[], int)} with that - * Double[] array at an offset of 0. - * This is not efficient and it is recommended to invoke {@link #asDoubleArray()}. + * @implSpec the default implementation invokes the generator to create + * an instance of a Double[] array with a length of {@link #count()} and + * then invokes {@link #copyInto(Double[], int)} with that Double[] + * array at an offset of 0. This is not efficient and it is recommended + * to invoke {@link #asDoubleArray()}. */ @Override default Double[] asArray(IntFunction<Double[]> generator) { @@ -419,9 +463,10 @@ /** * {@inheritDoc} - * @implSpec the default implementation invokes {@link #asDoubleArray()} to obtain a double[] array then - * and copies the elements from that double[] array into the boxed Double[] array. - * This is not efficient and it is recommended to invoke {@link #copyInto(double[], int)}. + * @implSpec the default implementation invokes {@link #asDoubleArray()} + * to obtain a double[] array then and copies the elements from that + * double[] array into the boxed Double[] array. This is not efficient + * and it is recommended to invoke {@link #copyInto(double[], int)}. */ @Override default void copyInto(Double[] boxed, int offset) { @@ -442,28 +487,33 @@ /** * View this node as a double[] array. * - * <p>Depending on the underlying implementation this may return a reference to an internal array rather than - * a copy. It is the callers responsibility to decide if either this node or the array is - * utilized as the primary reference for the data.</p> + * <p>Depending on the underlying implementation this may return a + * reference to an internal array rather than a copy. It is the callers + * responsibility to decide if either this node or the array is utilized + * as the primary reference for the data.</p> * * @return an array containing the contents of this {@code Node} */ double[] asDoubleArray(); /** - * Copy the content of this {@code Node} into a double[] array, starting at a given offset into the array. - * It is the caller's responsibility to ensure there is sufficient room in the array. + * Copy the content of this {@code Node} into a double[] array, starting + * at a given offset into the array. It is the caller's responsibility + * to ensure there is sufficient room in the array. * - * @param array the array into which to copy the contents of this {@code Node} + * @param array the array into which to copy the contents of this + * {@code Node} * @param offset the starting offset within the array - * @throws IndexOutOfBoundsException if copying would cause access of data outside array bounds + * @throws IndexOutOfBoundsException if copying would cause access of + * data outside array bounds * @throws NullPointerException if {@code array} is {@code null} */ void copyInto(double[] array, int offset); /** * {@inheritDoc} - * @implSpec The default in {@code Node.OfDouble} returns {@code StreamShape.DOUBLE_VALUE} + * @implSpec The default in {@code Node.OfDouble} returns + * {@code StreamShape.DOUBLE_VALUE} */ default StreamShape getShape() { return StreamShape.DOUBLE_VALUE;
--- a/src/share/classes/java/util/stream/PipelineHelper.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/PipelineHelper.java Thu Feb 28 18:35:14 2013 +0100 @@ -28,21 +28,26 @@ import java.util.function.IntFunction; /** - * Helper class for executing <a href="package-summary.html#StreamPipelines">stream pipelines</a>, capturing - * all of the information about a stream pipeline (source, output shape, stream flags, parallelism, etc) - * in one place. + * Helper class for executing + * <a href="package-summary.html#StreamPipelines">stream pipelines</a>, + * capturing all of the information about a stream pipeline (source, output + * shape, stream flags, parallelism, etc) in one place. * * @apiNote - * A stream pipeline consists of a source, zero or more intermediate operations, and a terminal operation. - * Execution of the stream pipeline begins when the terminal operation is executed. - * A {@code PipelineHelper} describes the portion of a stream pipeline including its source, some or all of its - * intermediate operations, and certain information about the terminal (or stateful) operation which follows - * the last intermediate operation described by this {@code PipelineHelper}. The - * {@code PipelineHelper} is passed to the {@link TerminalOp#evaluateParallel(PipelineHelper)}, - * {@link TerminalOp#evaluateSequential(PipelineHelper)}, and {@link StatefulOp#evaluateParallel(PipelineHelper)}, - * methods, which can use the {@code PipelineHelper} to access the source {@code Spliterator} for the pipeline, - * information about the pipeline such as input shape, output shape, stream flags, and size, and use the helper - * methods such as {@link #into(Sink, Spliterator)}, {@link #intoWrapped(Sink, Spliterator)}, + * A stream pipeline consists of a source, zero or more intermediate operations, + * and a terminal operation. Execution of the stream pipeline begins when the + * terminal operation is executed. A {@code PipelineHelper} describes the + * portion of a stream pipeline including its source, some or all of its + * intermediate operations, and certain information about the terminal (or + * stateful) operation which follows the last intermediate operation described + * by this {@code PipelineHelper}. The {@code PipelineHelper} is passed to the + * {@link TerminalOp#evaluateParallel(PipelineHelper)}, + * {@link TerminalOp#evaluateSequential(PipelineHelper)}, and + * {@link StatefulOp#evaluateParallel(PipelineHelper)}, methods, which can use + * the {@code PipelineHelper} to access the source {@code Spliterator} for the + * pipeline, information about the pipeline such as input shape, output shape, + * stream flags, and size, and use the helper methods such as + * {@link #into(Sink, Spliterator)}, {@link #intoWrapped(Sink, Spliterator)}, * and {@link #wrapSink(Sink)} to execute pipeline operations. * * @param <P_IN> Type of input elements to the pipeline @@ -64,10 +69,12 @@ StreamShape getOutputShape(); /** - * Get the combined stream and operation flags for the output of the pipeline. This will incorporate - * stream flags from the stream source, all the intermediate operations and the terminal operation. + * Get the combined stream and operation flags for the output of the + * pipeline. This will incorporate stream flags from the stream source, all + * the intermediate operations and the terminal operation. * - * @return the combined stream and operation flags for the output of the pipeline + * @return the combined stream and operation flags for the output of the + * pipeline * @see StreamOpFlag */ int getStreamAndOpFlags(); @@ -91,31 +98,37 @@ boolean isParallel(); /** - * Get the {@code Spliterator} for the source of the pipeline. This {@code Spliterator} reflects - * only the source elements, not the actions of any of the intermediate stages. + * Get the {@code Spliterator} for the source of the pipeline. This + * {@code Spliterator} reflects only the source elements, not the actions of + * any of the intermediate stages. * * @return the source spliterator */ Spliterator<P_IN> sourceSpliterator(); /** - * Returns the exact output size of the portion of the output resulting from applying the pipeline stages - * described by this {@code PipelineHelper} to the the portion of the input described by the provided - * {@code Spliterator}, if known. If not known or known infinite, will return {@code -1}. + * Returns the exact output size of the portion of the output resulting from + * applying the pipeline stages described by this {@code PipelineHelper} to + * the the portion of the input described by the provided + * {@code Spliterator}, if known. If not known or known infinite, will + * return {@code -1}. * * @apiNote - * The exact output size is known if the {@code Spliterator} has the {@code SIZED} characteristic, - * and the operation flags {@link StreamOpFlag#SIZED} is known on the combined stream and operation + * The exact output size is known if the {@code Spliterator} has the + * {@code SIZED} characteristic, and the operation flags + * {@link StreamOpFlag#SIZED} is known on the combined stream and operation * flags. * - * @param spliterator the spliterator describing the relevant portion of the source data + * @param spliterator the spliterator describing the relevant portion of the + * source data * @return the exact size if known, or -1 if infinite or unknown */ long exactOutputSizeIfKnown(Spliterator<P_IN> spliterator); /** - * Apply the pipeline stages described by this {@code PipelineHelper} to the provided {@code Spliterator} and - * send the results to the provided {@code Sink}. + * Apply the pipeline stages described by this {@code PipelineHelper} to the + * provided {@code Spliterator} and send the results to the provided + * {@code Sink}. * * @implSpec * The implementation behaves as if: @@ -124,19 +137,21 @@ * </pre> * * @param sink the {@code Sink} to receive the results - * @param spliterator the spliterator describing the portion of the source input to process + * @param spliterator the spliterator describing the portion of the source + * input to process */ <S extends Sink<P_OUT>> S into(S sink, Spliterator<P_IN> spliterator); /** - * Push elements obtained from the {@code Spliterator} into the provided {@code Sink}. If the stream - * pipeline is known to have short-circuiting stages in it (see {@link StreamOpFlag#SHORT_CIRCUIT}), then the - * elements are delivered as per {@link #intoWrappedWithCancel(Sink, Spliterator)}. + * Push elements obtained from the {@code Spliterator} into the provided + * {@code Sink}. If the stream pipeline is known to have short-circuiting + * stages in it (see {@link StreamOpFlag#SHORT_CIRCUIT}), then the elements + * are delivered as per {@link #intoWrappedWithCancel(Sink, Spliterator)}. * * @implSpec - * This method conforms to the {@code Sink} protocol of calling {@code Sink.begin} before pushing - * elements, via {@code Sink.accept}, and calling {@code Sink.end} after all elements have - * been pushed. + * This method conforms to the {@code Sink} protocol of calling + * {@code Sink.begin} before pushing elements, via {@code Sink.accept}, and + * calling {@code Sink.end} after all elements have been pushed. * * @param wrappedSink the destination {@code Sink} * @param spliterator the source {@code Spliterator} @@ -144,13 +159,15 @@ void intoWrapped(Sink<P_IN> wrappedSink, Spliterator<P_IN> spliterator); /** - * Push elements obtained from the {@code Spliterator} into the provided {@code Sink}, checking - * {@link Sink#cancellationRequested()} after each element, and stopping if cancellation is requested. + * Push elements obtained from the {@code Spliterator} into the provided + * {@code Sink}, checking {@link Sink#cancellationRequested()} after each + * element, and stopping if cancellation is requested. * * @implSpec - * This method conforms to the {@code Sink} protocol of calling {@code Sink.begin} before pushing - * elements, via {@code Sink.accept}, and calling {@code Sink.end} after all elements have - * been pushed or if cancellation is requested. + * This method conforms to the {@code Sink} protocol of calling + * {@code Sink.begin} before pushing elements, via {@code Sink.accept}, and + * calling {@code Sink.end} after all elements have been pushed or if + * cancellation is requested. * * @param wrappedSink the destination {@code Sink} * @param spliterator the source {@code Spliterator} @@ -158,41 +175,49 @@ void intoWrappedWithCancel(Sink<P_IN> wrappedSink, Spliterator<P_IN> spliterator); /** - * Take a {@code Sink} that accepts elements of the output type of the {@code PipelineHelper}, and wrap it with - * a {@code Sink} that accepts elements of the input type and implements all the intermediate operations described - * by this {@code PipelineHelper}, delivering the result into the provided {@code Sink}. + * Take a {@code Sink} that accepts elements of the output type of the + * {@code PipelineHelper}, and wrap it with a {@code Sink} that accepts + * elements of the input type and implements all the intermediate operations + * described by this {@code PipelineHelper}, delivering the result into the + * provided {@code Sink}. * * @param sink the {@code Sink} to receive the results - * @return a {@code Sink} that implements the pipeline stages and sends results to the provided {@code Sink} + * @return a {@code Sink} that implements the pipeline stages and sends + * results to the provided {@code Sink} */ Sink<P_IN> wrapSink(Sink<P_OUT> sink); /** - * Construct a @{link Node.Builder} compatible with the output shape of this {@code PipelineHelper} + * Construct a @{link Node.Builder} compatible with the output shape of this + * {@code PipelineHelper} * - * @param exactSizeIfKnown if >=0 then a builder will be created that has a fixed capacity of exactly - * sizeIfKnown elements; if < 0 then the builder has variable capacity. - * A fixed capacity builder will fail if an element is added and the builder has reached - * capacity. - * @return A {@code Node.Builder} compatible with the output shape of this {@code PipelineHelper} + * @param exactSizeIfKnown if >=0 then a builder will be created that has a + * fixed capacity of exactly sizeIfKnown elements; if < 0 then the + * builder has variable capacity. A fixed capacity builder will fail + * if an element is added and the builder has reached capacity. + * @return A {@code Node.Builder} compatible with the output shape of this + * {@code PipelineHelper} */ Node.Builder<P_OUT> makeNodeBuilder(long exactSizeIfKnown); /** - * Collect all output elements resulting from applying the pipeline stages to the source {@code Spliterator} - * into a {@code Node}. + * Collect all output elements resulting from applying the pipeline stages + * to the source {@code Spliterator} into a {@code Node}. * * @implSpec - * If the pipeline has no intermediate operations and the source is backed by a {@code Node} then - * that {@code Node} will be returned or flattened and then returned. This reduces copying for a pipeline - * consisting of a stateful operation followed by a terminal operation that returns an array, such as: + * If the pipeline has no intermediate operations and the source is backed + * by a {@code Node} then that {@code Node} will be returned or flattened + * and then returned. This reduces copying for a pipeline consisting of a + * stateful operation followed by a terminal operation that returns an + * array, such as: * <pre>{@code * stream.sorted().toArray(); * }</pre> * - * @param flatten if true and the pipeline is a parallel pipeline then the {@code Node} returned - * will contain no children, otherwise the {@code Node} may represent the root in a - * tree that reflects the shape of the computation tree. + * @param flatten if true and the pipeline is a parallel pipeline then the + * {@code Node} returned will contain no children, otherwise the + * {@code Node} may represent the root in a tree that reflects the + * shape of the computation tree. * @return the {@code Node} containing all output elements */ Node<P_OUT> collectOutput(boolean flatten); @@ -205,24 +230,28 @@ IntFunction<P_OUT[]> arrayGenerator(); /** - * Collect all output elements resulting from the applying the pipeline stages, plus an additional final stage - * that is an intermediate operation, to the source {@code Spliterator} into a {code Node}. - * The order of output elements will respect the encounter order of the source stream, and all computation will - * happen in the invoking thread. + * Collect all output elements resulting from the applying the pipeline + * stages, plus an additional final stage that is an intermediate operation, + * to the source {@code Spliterator} into a {code Node}. The order of + * output elements will respect the encounter order of the source stream, + * and all computation will happen in the invoking thread. * <p> - * Implementations of {@link StatefulOp#evaluateParallel(PipelineHelper)} can defer to this method if - * a sequential implementation is acceptable. + * Implementations of {@link StatefulOp#evaluateParallel(PipelineHelper)} + * can defer to this method if a sequential implementation is acceptable. * * @implSpec - * If the intermediate operation injects {@link StreamOpFlag#SHORT_CIRCUIT} then this implementation must - * stop collecting output elements when the sink returned from {@link IntermediateOp#wrapSink(int, Sink)} - * reports it is cancelled. + * If the intermediate operation injects {@link StreamOpFlag#SHORT_CIRCUIT} + * then this implementation must stop collecting output elements when the + * sink returned from {@link IntermediateOp#wrapSink(int, Sink)} reports it + * is cancelled. + * <p> + * If the intermediate operation preserves or injects + * {@link StreamOpFlag#SIZED} and the output size of the pipeline is known + * then this implementation may apply size optimizations since the output + * size is known. * - * If the intermediate operation preserves or injects {@link StreamOpFlag#SIZED} and the output size of the - * pipeline is known then this implementation may apply size optimizations since the output size is known. - * - * @param op An {@code IntermediateOp} representing the final stage in the pipeline, typically - * a {@code StatefulOp} + * @param op An {@code IntermediateOp} representing the final stage in the + * pipeline, typically a {@code StatefulOp} * @return A {@code Node} containing the output of the stream pipeline */ default Node<P_OUT> evaluateSequential(IntermediateOp<P_OUT, P_OUT> op) {
--- a/src/share/classes/java/util/stream/Sink.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/Sink.java Thu Feb 28 18:35:14 2013 +0100 @@ -31,19 +31,23 @@ import java.util.function.LongConsumer; /** - * An extension of {@link Consumer} used to conduct values through the stages of a stream pipeline, with additional - * methods to manage size information, control flow, etc. Before calling the {@code accept()} method on a - * {@code Sink} for the first time, you must first call the {@code begin()} method to inform it that data is coming - * (optionally informing the sink how much data is coming), and after all data has been sent, you must call the - * {@code end()} method. After calling {@code end()}, you should not call {@code accept()} without again - * calling {@code begin()}. {@code Sink} also offers a mechanism by which the sink can cooperatively signal that - * it does not wish to receive any more data (the {@code cancellationRequested()} method), which a source can poll - * before sending more data to the {@code Sink}. + * An extension of {@link Consumer} used to conduct values through the stages of + * a stream pipeline, with additional methods to manage size information, + * control flow, etc. Before calling the {@code accept()} method on a + * {@code Sink} for the first time, you must first call the {@code begin()} + * method to inform it that data is coming (optionally informing the sink how + * much data is coming), and after all data has been sent, you must call the + * {@code end()} method. After calling {@code end()}, you should not call + * {@code accept()} without again calling {@code begin()}. {@code Sink} also + * offers a mechanism by which the sink can cooperatively signal that it does + * not wish to receive any more data (the {@code cancellationRequested()} + * method), which a source can poll before sending more data to the {@code Sink}. * * @apiNote * - * A stream pipeline consists of a source, zero or more intermediate stages (such as filtering or mapping), and a - * terminal stage, such as reduction or for-each. For concreteness, consider the pipeline: + * A stream pipeline consists of a source, zero or more intermediate stages + * (such as filtering or mapping), and a terminal stage, such as reduction or + * for-each. For concreteness, consider the pipeline: * * <pre> * int longestStringLengthStartingWithA @@ -53,29 +57,38 @@ * .max(); * </pre> * - * Here, we have three stages, filtering, mapping, and reducing. The filtering stage consumes strings and emits - * a subset of those strings; the mapping stage consumes strings and emits ints; the reduction stage consumes those - * ints and computes the maximal value. + * Here, we have three stages, filtering, mapping, and reducing. The filtering + * stage consumes strings and emits a subset of those strings; the mapping stage + * consumes strings and emits ints; the reduction stage consumes those ints and + * computes the maximal value. * - * A {@code Sink} instance is used to represent each stage of this pipeline, whether the stage accepts objects, - * ints, longs, or doubles. Sink has entry points for {@code accept(Object)}, {@code accept(int)}, etc, so that we - * do not need a specialized interface for each primitive specialization. (It might be called a "kitchen sink" - * for this omnivorous tendency.) The entry point to the pipeline is the {@code Sink} for the filtering stage, - * which sends some elements "downstream" -- into the {@code Sink} for the mapping stage, which in turn sends integral - * values downstream into the {@code Sink} for the reduction stage. The {@code Sink} implementations associated - * with a given stage is expected to know the data type for the next stage, and call the correct {@code accept} method - * on its downstream {@code Sink}. Similarly, each stage must implement the correct {@code accept} method - * corresponding to the data type it accepts. + * A {@code Sink} instance is used to represent each stage of this pipeline, + * whether the stage accepts objects, ints, longs, or doubles. Sink has entry + * points for {@code accept(Object)}, {@code accept(int)}, etc, so that we do + * not need a specialized interface for each primitive specialization. (It + * might be called a "kitchen sink" for this omnivorous tendency.) The entry + * point to the pipeline is the {@code Sink} for the filtering stage, which + * sends some elements "downstream" -- into the {@code Sink} for the mapping + * stage, which in turn sends integral values downstream into the {@code Sink} + * for the reduction stage. The {@code Sink} implementations associated with a + * given stage is expected to know the data type for the next stage, and call + * the correct {@code accept} method on its downstream {@code Sink}. Similarly, + * each stage must implement the correct {@code accept} method corresponding to + * the data type it accepts. * - * The specialized subtypes such as {@link Sink.OfInt} bridge {@code accept(Object)} to call the appropriate - * primitive specialization of {@code accept}, implement the appropriate primitive specialization of {@code Consumer}, - * and reabstract the appropriate primitive specialization of {@code accept}. + * The specialized subtypes such as {@link Sink.OfInt} bridge + * {@code accept(Object)} to call the appropriate primitive specialization of + * {@code accept}, implement the appropriate primitive specialization of + * {@code Consumer}, and reabstract the appropriate primitive specialization of + * {@code accept}. * - * The chaining subtypes such as {@link ChainedInt} not only implement {@code Sink.OfInt}, but also maintain a - * {@code downstream} field which represents the downstream {@code Sink}, and implement the methods {@code begin()}, - * {@code end()}, and {@code cancellationRequested()} to delegate to the downstream {@code Sink}. - * Most implementations of intermediate operations will use these chaining wrappers. For example, the mapping stage - * in the above example would look like: + * The chaining subtypes such as {@link ChainedInt} not only implement + * {@code Sink.OfInt}, but also maintain a {@code downstream} field which + * represents the downstream {@code Sink}, and implement the methods + * {@code begin()}, {@code end()}, and {@code cancellationRequested()} to + * delegate to the downstream {@code Sink}. Most implementations of + * intermediate operations will use these chaining wrappers. For example, the + * mapping stage in the above example would look like: * * <pre> * IntSink is = new Sink.ChainedReference<U>(sink) { @@ -85,11 +98,12 @@ * }; * </pre> * - * Here, we implement {@code Sink.ChanedReference<U>}, meaning that we expect to receive elements of type {@code U} - * as input, and pass the downstream sink to the constructor. Because the next stage expects to receive integers, - * we must call the {@code accept(int)} method when emitting values to the downstream. The {@code accept()} method - * applies the mapping function from {@code U} to {@code int} and passes the resulting value to the downstream - * {@code Sink}. + * Here, we implement {@code Sink.ChanedReference<U>}, meaning that we expect to + * receive elements of type {@code U} as input, and pass the downstream sink to + * the constructor. Because the next stage expects to receive integers, we must + * call the {@code accept(int)} method when emitting values to the downstream. + * The {@code accept()} method applies the mapping function from {@code U} to + * {@code int} and passes the resulting value to the downstream {@code Sink}. * * @param <T> Type of elements for value streams * @since 1.8 @@ -105,16 +119,16 @@ default void begin(long size) {} /** - * Indicate that all elements have been pushed. If the {@code Sink} buffers any - * results from previous values, they should dump their contents downstream and - * clear any stored state. + * Indicate that all elements have been pushed. If the {@code Sink} buffers + * any results from previous values, they should dump their contents + * downstream and clear any stored state. */ default void end() {} /** - * Used to communicate to upstream sources that this {@code Sink} does not wish to receive - * any more data - * @return + * Used to communicate to upstream sources that this {@code Sink} does not + * wish to receive any more data + * @return If cancellation is requested */ default boolean cancellationRequested() { return false; @@ -151,8 +165,9 @@ } /** - * {@code Sink} that implements {@code Sink<Integer>}, reabstracts {@code accept(int)}, - * and wires {@code accept(Integer)} to bridge to {@code accept(int)}. + * {@code Sink} that implements {@code Sink<Integer>}, reabstracts + * {@code accept(int)}, and wires {@code accept(Integer)} to bridge to + * {@code accept(int)}. */ @FunctionalInterface interface OfInt extends Sink<Integer>, IntConsumer { @@ -168,8 +183,9 @@ } /** - * {@code Sink} that implements {@code Sink<Long>}, reabstracts {@code accept(long)}, - * and wires {@code accept(Long)} to bridge to {@code accept(long)}. + * {@code Sink} that implements {@code Sink<Long>}, reabstracts + * {@code accept(long)}, and wires {@code accept(Long)} to bridge to + * {@code accept(long)}. */ @FunctionalInterface interface OfLong extends Sink<Long>, LongConsumer { @@ -185,8 +201,9 @@ } /** - * {@code Sink} that implements {@code Sink<Double>}, reabstracts {@code accept(double)}, - * and wires {@code accept(Double)} to bridge to {@code accept(double)}. + * {@code Sink} that implements {@code Sink<Double>}, reabstracts + * {@code accept(double)}, and wires {@code accept(Double)} to bridge to + * {@code accept(double)}. */ @FunctionalInterface interface OfDouble extends Sink<Double>, DoubleConsumer { @@ -202,10 +219,11 @@ } /** - * {@code Sink} implementation designed for creating chains of sinks. The {@code begin} and - * {@code end}, and {@code cancellationRequested} methods are wired to chain to the downstream - * {@code Sink}. This implementation takes a downstream {@code Sink} of unknown input shape - * and produces a {@code Sink<T>}. The implementation of the {@code accept()} method must + * {@code Sink} implementation designed for creating chains of sinks. The + * {@code begin} and {@code end}, and {@code cancellationRequested} methods + * are wired to chain to the downstream {@code Sink}. This implementation + * takes a downstream {@code Sink} of unknown input shape and produces a + * {@code Sink<T>}. The implementation of the {@code accept()} method must * call the correct {@code accept()} method on the downstream {@code Sink}. */ static abstract class ChainedReference<T> implements Sink<T> { @@ -232,11 +250,13 @@ } /** - * {@code Sink} implementation designed for creating chains of sinks. The {@code begin} and - * {@code end}, and {@code cancellationRequested} methods are wired to chain to the downstream - * {@code Sink}. This implementation takes a downstream {@code Sink} of unknown input shape - * and produces a {@code Sink.OfInt}. The implementation of the {@code accept()} method must - * call the correct {@code accept()} method on the downstream {@code Sink}. + * {@code Sink} implementation designed for creating chains of sinks. The + * {@code begin} and {@code end}, and {@code cancellationRequested} methods + * are wired to chain to the downstream {@code Sink}. This implementation + * takes a downstream {@code Sink} of unknown input shape and produces a + * {@code Sink.OfInt}. The implementation of the {@code accept()} method + * must call the correct {@code accept()} method on the downstream + * {@code Sink}. */ static abstract class ChainedInt implements Sink.OfInt { protected final Sink downstream; @@ -262,11 +282,13 @@ } /** - * {@code Sink} implementation designed for creating chains of sinks. The {@code begin} and - * {@code end}, and {@code cancellationRequested} methods are wired to chain to the downstream - * {@code Sink}. This implementation takes a downstream {@code Sink} of unknown input shape - * and produces a {@code Sink.OfLong}. The implementation of the {@code accept()} method must - * call the correct {@code accept()} method on the downstream {@code Sink}. + * {@code Sink} implementation designed for creating chains of sinks. The + * {@code begin} and {@code end}, and {@code cancellationRequested} methods + * are wired to chain to the downstream {@code Sink}. This implementation + * takes a downstream {@code Sink} of unknown input shape and produces a + * {@code Sink.OfLong}. The implementation of the {@code accept()} method + * must call the correct {@code accept()} method on the downstream + * {@code Sink}. */ static abstract class ChainedLong implements Sink.OfLong { protected final Sink downstream; @@ -292,11 +314,13 @@ } /** - * {@code Sink} implementation designed for creating chains of sinks. The {@code begin} and - * {@code end}, and {@code cancellationRequested} methods are wired to chain to the downstream - * {@code Sink}. This implementation takes a downstream {@code Sink} of unknown input shape - * and produces a {@code Sink.OfDouble}. The implementation of the {@code accept()} method must - * call the correct {@code accept()} method on the downstream {@code Sink}. + * {@code Sink} implementation designed for creating chains of sinks. The + * {@code begin} and {@code end}, and {@code cancellationRequested} methods + * are wired to chain to the downstream {@code Sink}. This implementation + * takes a downstream {@code Sink} of unknown input shape and produces a + * {@code Sink.OfDouble}. The implementation of the {@code accept()} method + * must call the correct {@code accept()} method on the downstream + * {@code Sink}. */ static abstract class ChainedDouble implements Sink.OfDouble { protected final Sink downstream;
--- a/src/share/classes/java/util/stream/StatefulOp.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/StatefulOp.java Thu Feb 28 18:35:14 2013 +0100 @@ -1,18 +1,22 @@ package java.util.stream; /** - * A stateful intermediate stream operation ({@link IntermediateOp}). <em>Stateful</em> means that state - * is accumulated as elements are processed. Examples of stateful operations are sorting, extracting a subsequence - * of the input, or removing duplicates. Statefulness has an effect on how the operation can be parallelized. - * Stateless operations parallelize trivially because they are homomorphisms under concatenation: + * A stateful intermediate stream operation ({@link IntermediateOp}). + * <em>Stateful</em> means that state is accumulated as elements are processed. + * Examples of stateful operations are sorting, extracting a subsequence of the + * input, or removing duplicates. Statefulness has an effect on how the + * operation can be parallelized. Stateless operations parallelize trivially + * because they are homomorphisms under concatenation: * * <pre> * statelessOp(a || b) = statelessOp(a) || statelessOp(b) * </pre> * - * where {@code ||} denotes concatenation. Stateful operations may still be parallelizable, but are not amenable to - * the automatic parallelization of stateless operations. Accordingly, a stateful operation must provide its - * own parallel execution implementation ({@link #evaluateParallel(PipelineHelper)}). + * where {@code ||} denotes concatenation. Stateful operations may still be + * parallelizable, but are not amenable to the automatic parallelization of + * stateless operations. Accordingly, a stateful operation must provide its + * own parallel execution implementation + * ({@link #evaluateParallel(PipelineHelper)}). * * @param <E> Type of input and output elements. * @@ -35,8 +39,9 @@ /** * {@inheritDoc} * - * An implementation of this method must be provided, but it is acceptable if the implementation is sequential. - * A generic sequential implementation is available as + * An implementation of this method must be provided, but it is acceptable + * if the implementation is sequential. A generic sequential implementation + * is available as * {@link PipelineHelper#evaluateSequential(IntermediateOp)}. */ <P_IN> Node<E> evaluateParallel(PipelineHelper<P_IN, E> helper);
--- a/src/share/classes/java/util/stream/StreamOpFlag.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/StreamOpFlag.java Thu Feb 28 18:35:14 2013 +0100 @@ -28,13 +28,16 @@ import java.util.Map; /** - * Flags corresponding to characteristics of streams and operations. Flags are utilized by the stream - * framework to control, specialize or optimize computation. + * Flags corresponding to characteristics of streams and operations. Flags are + * utilized by the stream framework to control, specialize or optimize + * computation. * * <p> - * Stream flags may be used to describe characteristics of several different entities associated with streams: - * stream sources, intermediate operations, and terminal operations. Not all stream flags are meaningful for all - * entities; the following table summarizes which flags are meaningful in what contexts: + * Stream flags may be used to describe characteristics of several different + * entities associated with streams: stream sources, intermediate operations, + * and terminal operations. Not all stream flags are meaningful for all + * entities; the following table summarizes which flags are meaningful in what + * contexts: * <pre> * DISTINCT SORTED ORDERED SIZED SHORT_CIRCUIT PARALLEL * Stream source Y Y Y Y N Y @@ -42,83 +45,104 @@ * Terminal operation N N PC N PI N * </pre> * - * <p>In the above table, "PCI" means "may preserve, clear, or inject"; "PC" means "may preserve or clear", - * "PI" means "may preserve or inject", and "N" means "not valid". + * <p>In the above table, "PCI" means "may preserve, clear, or inject"; "PC" + * means "may preserve or clear", "PI" means "may preserve or inject", and "N" + * means "not valid". * - * <p>Stream flags are represented by unioned bit sets, so that a single word may describe all the - * characteristics of a given stream entity, and that, for example, the flags for a stream source can be - * efficiently combined with the flags for later operations on that stream. + * <p>Stream flags are represented by unioned bit sets, so that a single word + * may describe all the characteristics of a given stream entity, and that, for + * example, the flags for a stream source can be efficiently combined with the + * flags for later operations on that stream. * - * <p>The bit masks {@link #STREAM_MASK}, {@link #OP_MASK}, and {@link #TERMINAL_OP_MASK} can be ANDed with - * a bit set of stream flags to produce a mask containing only the valid flags for that entity type. + * <p>The bit masks {@link #STREAM_MASK}, {@link #OP_MASK}, and + * {@link #TERMINAL_OP_MASK} can be ANDed with a bit set of stream flags to + * produce a mask containing only the valid flags for that entity type. * - * <p>When describing a stream source, one only need describe what characteristics that stream has; when describing - * a stream operation, one need describe whether the operation preserves, injects, or clears that characteristic. - * Accordingly, two bits are used for each flag, so as to allow representing not only the presence of of a - * characteristic, but how an operation modifies that characteristic. There are two common forms in which - * flag bits are combined into an {@code int} bit set. <em>Stream flags</em> are a unioned bit set constructed by - * ORing the enum characteristic values of {@link #set()} (or, more commonly, ORing the corresponding static named - * constants prefixed with {@code IS_}). <em>Operation flags</em> are a unioned bit set constructed by - * ORing the enum characteristic values of {@link #set()} or {@link #clear()} (to inject, or clear, respectively, - * the corresponding flag), or more commonly ORing the corresponding named constants prefixed with {@code IS_} - * or {@code NOT_}. Flags that are not marked with {@code IS_} or {@code NOT_} are implicitly treated as preserved. - * Care must be taken when combining bitsets that the correct combining operations are applied in the correct order. + * <p>When describing a stream source, one only need describe what + * characteristics that stream has; when describing a stream operation, one need + * describe whether the operation preserves, injects, or clears that + * characteristic. Accordingly, two bits are used for each flag, so as to allow + * representing not only the presence of of a characteristic, but how an + * operation modifies that characteristic. There are two common forms in which + * flag bits are combined into an {@code int} bit set. <em>Stream flags</em> + * are a unioned bit set constructed by ORing the enum characteristic values of + * {@link #set()} (or, more commonly, ORing the corresponding static named + * constants prefixed with {@code IS_}). <em>Operation flags</em> are a unioned + * bit set constructed by ORing the enum characteristic values of {@link #set()} + * or {@link #clear()} (to inject, or clear, respectively, the corresponding + * flag), or more commonly ORing the corresponding named constants prefixed with + * {@code IS_} or {@code NOT_}. Flags that are not marked with {@code IS_} or + * {@code NOT_} are implicitly treated as preserved. Care must be taken when + * combining bitsets that the correct combining operations are applied in the + * correct order. * * <p> - * With the exception of {@link #PARALLEL}, stream characteristics can be derived from the equivalent - * {@link java.util.Spliterator} characteristics: {@link java.util.Spliterator#DISTINCT}, - * {@link java.util.Spliterator#SORTED}, {@link java.util.Spliterator#ORDERED}, and - * {@link java.util.Spliterator#SIZED}. A spliterator characteristics bit set can be converted to stream flags - * using the method {@link #fromCharacteristics(int)} and converted back using {@link #toCharacteristics(int)}. - * (The bit set {@link #SPLITERATOR_CHARACTERISTICS_MASK} is used to AND with a bit set to produce a valid - * spliterator characteristics bit set that can be converted to stream flags.) + * With the exception of {@link #PARALLEL}, stream characteristics can be + * derived from the equivalent {@link java.util.Spliterator} characteristics: + * {@link java.util.Spliterator#DISTINCT}, {@link java.util.Spliterator#SORTED}, + * {@link java.util.Spliterator#ORDERED}, and + * {@link java.util.Spliterator#SIZED}. A spliterator characteristics bit set + * can be converted to stream flags using the method + * {@link #fromCharacteristics(int)} and converted back using + * {@link #toCharacteristics(int)}. (The bit set + * {@link #SPLITERATOR_CHARACTERISTICS_MASK} is used to AND with a bit set to + * produce a valid spliterator characteristics bit set that can be converted to + * stream flags.) * * <p> - * The source of a stream encapsulates a spliterator. The characteristics of that source - * spliterator when transformed to stream flags will be a proper subset of stream flags of that stream. + * The source of a stream encapsulates a spliterator. The characteristics of + * that source spliterator when transformed to stream flags will be a proper + * subset of stream flags of that stream. * For example: * <pre> {@code * Spliterator s = ...; * Stream stream = Streams.stream(s); - * flagsFromSpliterator = fromCharacteristics(s.characteristics()); - * assert(flagsFromSpliterator & stream.getStreamFlags() == flagsFromSpliterator); + * flagsFromSplitr = fromCharacteristics(s.characteristics()); + * assert(flagsFromSplitr & stream.getStreamFlags() == flagsFromSplitr); * }</pre> * * <p> - * An intermediate operation, performed on an input stream to create a new output stream, - * may preserve, clear or inject stream or operation characteristics. - * Similarly, a terminal operation, performed on an input stream to produce an output result - * may preserve, clear or inject stream or operation characteristics. - * Preservation means that if that characteristic is present on the input, then it is - * also present on the output. Clearing means that the characteristic is not present on the output regardless - * of the input. Injection means that the characteristic is present on the output regardless of the input. - * If a characteristic is not cleared or injected then it is implicitly preserved. + * An intermediate operation, performed on an input stream to create a new + * output stream, may preserve, clear or inject stream or operation + * characteristics. Similarly, a terminal operation, performed on an input + * stream to produce an output result may preserve, clear or inject stream or + * operation characteristics. Preservation means that if that characteristic + * is present on the input, then it is also present on the output. Clearing + * means that the characteristic is not present on the output regardless of the + * input. Injection means that the characteristic is present on the output + * regardless of the input. If a characteristic is not cleared or injected then + * it is implicitly preserved. * * <p> - * A pipeline consists of a stream source encapsulating a spliterator, one or more intermediate operations, - * and finally a terminal operation that produces a result. At each stage of the pipeline, a combined - * stream and operation flags can be calculated, using {@link #combineOpFlags(int, int)}. - * Such flags ensure that preservation, clearing and injecting information is retained at each stage. + * A pipeline consists of a stream source encapsulating a spliterator, one or + * more intermediate operations, and finally a terminal operation that produces + * a result. At each stage of the pipeline, a combined stream and operation + * flags can be calculated, using {@link #combineOpFlags(int, int)}. Such flags + * ensure that preservation, clearing and injecting information is retained at + * each stage. * - * The combined stream and operation flags for the source stage of the pipeline is calculated as - * follows: + * The combined stream and operation flags for the source stage of the pipeline + * is calculated as follows: * <pre> {@code * int flagsForSourceStage = combineOpFlags(sourceFlags, INITIAL_OPS_VALUE); * }</pre> * - * The combined stream and operation flags of each subsequent intermediate operation stage in the pipeline is - * calculated as follows: + * The combined stream and operation flags of each subsequent intermediate + * operation stage in the pipeline is calculated as follows: * <pre> {@code * int flagsForThisStage = combineOpFlags(flagsForPreviousStage, thisOpFlags); * }</pre> * - * Finally the flags output from the last intermediate operation of the pipeline are combined with the operation flags - * of the terminal operation to produce the flags output from the pipeline. + * Finally the flags output from the last intermediate operation of the pipeline + * are combined with the operation flags of the terminal operation to produce + * the flags output from the pipeline. * - * <p>Those flags can then be used to apply optimizations. For example, if {@code SIZED.isKnown(flags)} returns true - * then the stream size remains constant throughout the pipeline, this information can be utilized to pre-allocate data - * structures and combined with {@link java.util.Spliterator#SUBSIZED} that information can be utilized to perform - * concurrent in-place updates into a shared array. + * <p>Those flags can then be used to apply optimizations. For example, if + * {@code SIZED.isKnown(flags)} returns true then the stream size remains + * constant throughout the pipeline, this information can be utilized to + * pre-allocate data structures and combined with + * {@link java.util.Spliterator#SUBSIZED} that information can be utilized to + * perform concurrent in-place updates into a shared array. * * For specific details see the {@link AbstractPipeline} constructors. * @@ -130,15 +154,16 @@ enum StreamOpFlag { /* - * Each characteristic takes up 2 bits in a bit set to accommodate preserving, clearing and - * setting/injecting information. + * Each characteristic takes up 2 bits in a bit set to accommodate + * preserving, clearing and setting/injecting information. * - * This applies to stream flags, intermediate/terminal operation flags, and combined stream and - * operation flags. Even though the former only requires 1 bit of information per characteristic, - * is it more efficient when combining flags to align set and inject bits. + * This applies to stream flags, intermediate/terminal operation flags, and + * combined stream and operation flags. Even though the former only requires + * 1 bit of information per characteristic, is it more efficient when + * combining flags to align set and inject bits. * - * Characteristics belong to certain types, see the Type enum. Bit masks for the types are - * constructed as per the following table: + * Characteristics belong to certain types, see the Type enum. Bit masks for + * the types are constructed as per the following table: * * DISTINCT SORTED ORDERED SIZED SHORT_CIRCUIT PARALLEL * SPLITERATOR 01 01 01 01 00 00 @@ -151,7 +176,8 @@ * 10 = clear * 11 = preserve * - * Construction of the columns is performed using a simple builder for non-zero values. + * Construction of the columns is performed using a simple builder for + * non-zero values. */ @@ -163,8 +189,8 @@ * Characteristic value signifying that, for each pair of * encountered elements in a stream {@code x, y}, {@code !x.equals(y)}. * <p> - * A stream may have this value or an intermediate operation can preserve, clear or inject - * this value. + * A stream may have this value or an intermediate operation can preserve, + * clear or inject this value. */ // 0, 0x00000001 // Matches Spliterator.DISTINCT @@ -175,8 +201,8 @@ * Characteristic value signifying that encounter order follows a * defined sort order. * <p> - * A stream can have this value or an intermediate operation can preserve, clear or inject - * this value. + * A stream can have this value or an intermediate operation can preserve, + * clear or inject this value. */ // 1, 0x00000004 // Matches Spliterator.SORTED @@ -187,8 +213,9 @@ * Characteristic value signifying that an encounter order is * defined for stream elements. * <p> - * A stream can have this value, an intermediate operation can preserve, clear or inject - * this value, or a terminal operation can preserve or clear this value. + * A stream can have this value, an intermediate operation can preserve, + * clear or inject this value, or a terminal operation can preserve or clear + * this value. */ // 2, 0x00000010 // Matches Spliterator.ORDERED @@ -202,8 +229,8 @@ * size of the source spliterator input to the first stream * in the pipeline. * <p> - * A stream can have this value or an intermediate operation can preserve or clear - * this value. + * A stream can have this value or an intermediate operation can preserve or + * clear this value. */ // 3, 0x00000040 // Matches Spliterator.SIZED @@ -211,8 +238,8 @@ set(Type.SPLITERATOR).set(Type.STREAM).clear(Type.OP)), // The following Spliterator characteristics are not currently used but a - // gap in the bit set is deliberately retained to enable corresponding stream - // flags if//when required without modification to other flag values. + // gap in the bit set is deliberately retained to enable corresponding + // stream flags if//when required without modification to other flag values. // // 4, 0x00000100 INFINITE(4, ... // 5, 0x00000400 NONNULL(5, ... @@ -231,7 +258,8 @@ // /** - * Characteristic value signifying that an operation may short-circuit the stream. + * Characteristic value signifying that an operation may short-circuit the + * stream. * <p> * An intermediate operation can preserve or inject this value, * or a terminal operation can preserve or inject this value. @@ -242,11 +270,11 @@ /** - * Characteristic value signifying that the stream is to be evaluated in parallel rather than - * sequentially. + * Characteristic value signifying that the stream is to be evaluated in + * parallel rather than sequentially. * <p> - * A stream can have this value or an intermediate operation can preserve or clear - * this value. + * A stream can have this value or an intermediate operation can preserve or + * clear this value. */ // 13, 0x04000000 PARALLEL(13, @@ -275,8 +303,8 @@ TERMINAL_OP, /** - * The flag is associated with terminal operation flags that are propagated upstream - * across the last stateful operation boundary + * The flag is associated with terminal operation flags that are + * propagated upstream across the last stateful operation boundary */ UPSTREAM_TERMINAL_OP } @@ -388,7 +416,8 @@ * Check if this flag is set on stream flags, injected on operation flags, * and injected on combined stream and operation flags. * - * @param flags the stream flags, operation flags, or combined stream and operation flags + * @param flags the stream flags, operation flags, or combined stream and + * operation flags * @return true if this flag is known, otherwise false. */ boolean isKnown(int flags) { @@ -396,7 +425,8 @@ } /** - * Check if this flag is cleared on operation flags or combined stream and operation flags. + * Check if this flag is cleared on operation flags or combined stream and + * operation flags. * * @param flags the operation flags or combined stream and operations flags. * @return true if this flag is preserved, otherwise false. @@ -475,7 +505,8 @@ private static final int FLAG_MASK_NOT = STREAM_MASK << 1; /** - * The initial value to be combined with the stream flags of the first stream in the pipeline. + * The initial value to be combined with the stream flags of the first + * stream in the pipeline. */ static final int INITIAL_OPS_VALUE = FLAG_MASK_IS | FLAG_MASK_NOT; @@ -541,8 +572,8 @@ } /** - * Combine stream or operation flags with previously combined stream and operation flags to - * produce updated combined stream and operation flags. + * Combine stream or operation flags with previously combined stream and + * operation flags to produce updated combined stream and operation flags. * <p> * A flag set on stream flags or injected on operation flags, * and injected combined stream and operation flags, @@ -559,13 +590,13 @@ * will be injected on the updated combined stream and operation flags. * </p> * <p> - * A flag not set on the stream flags or cleared/preserved on operation flags, - * and injected on the combined stream and operation flags, + * A flag not set on the stream flags or cleared/preserved on operation + * flags, and injected on the combined stream and operation flags, * will be injected on the updated combined stream and operation flags. * </p> * <p> - * A flag not set on the stream flags or cleared/preserved on operation flags, - * and cleared on the combined stream and operation flags, + * A flag not set on the stream flags or cleared/preserved on operation + * flags, and cleared on the combined stream and operation flags, * will be cleared on the updated combined stream and operation flags. * </p> * <p> @@ -586,7 +617,7 @@ * * @param newStreamOrOpFlags the stream or operation flags. * @param prevCombOpFlags previously combined stream and operation flags. - * The value {#link INITIAL_OPS_VALUE} must be used as the seed value. + * The value {#link INITIAL_OPS_VALUE} must be used as the seed value. * @return the updated combined stream and operation flags. */ static int combineOpFlags(int newStreamOrOpFlags, int prevCombOpFlags) { @@ -600,7 +631,8 @@ /** * Convert combined stream and operation flags to stream flags. * - * <p> Each flag injected on the combined stream and operation flags will be set on the stream flags. + * <p>Each flag injected on the combined stream and operation flags will be + * set on the stream flags. * * @param combOpFlags the combined stream and operation flags. * @return the stream flags.
--- a/src/share/classes/java/util/stream/StreamShape.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/StreamShape.java Thu Feb 28 18:35:14 2013 +0100 @@ -27,32 +27,49 @@ import java.util.function.ToIntFunction; /** - * An enum describing the known shape specializations for stream abstractions. Each will correspond to - * a specific subinterface of {@link BaseStream} (e.g., {@code REFERENCE} corresponds to {@code Stream}, - * {@code INT_VALUE} corresponds to {@code IntStream}). Each may also correspond to specializations of - * value-handling abstractions such as {@code Spliterator}, {@code Consumer}, etc. + * An enum describing the known shape specializations for stream abstractions. + * Each will correspond to a specific subinterface of {@link BaseStream} + * (e.g., {@code REFERENCE} corresponds to {@code Stream}, {@code INT_VALUE} + * corresponds to {@code IntStream}). Each may also correspond to + * specializations of value-handling abstractions such as {@code Spliterator}, + * {@code Consumer}, etc. * * @apiNote - * This enum is used by implementations to determine compatibility between streams and operations (i.e., if the - * output shape of a stream is compatible with the input shape of the next operation). It is also used to reduce - * the code bloat associated with having multiple specialized stream types for primitives by allowing some code - * to be largely shape-independent. + * This enum is used by implementations to determine compatibility between + * streams and operations (i.e., if the output shape of a stream is compatible + * with the input shape of the next operation). It is also used to reduce the + * code bloat associated with having multiple specialized stream types for + * primitives by allowing some code to be largely shape-independent. * - * <p>Some APIs require you to specify both a generic type and a stream shape for input or output elements, such as - * {@link IntermediateOp} which has both generic type parameters for its input and output types, and getters for - * the input and output shape. When representing primitive streams in this way, the generic type parameter should - * correspond to the wrapper type for that primitive type. Accordingly, the {@code IntermediateOp} implementing - * {@link Stream#map(ToIntFunction)} would have an output type parameter of {@code Integer} and an output - * shape of @{code INT_VALUE}. + * <p>Some APIs require you to specify both a generic type and a stream shape + * for input or output elements, such as {@link IntermediateOp} which has both + * generic type parameters for its input and output types, and getters for the + * input and output shape. When representing primitive streams in this way, the + * generic type parameter should correspond to the wrapper type for that + * primitive type. Accordingly, the {@code IntermediateOp} implementing + * {@link Stream#map(ToIntFunction)} would have an output type parameter of + * {@code Integer} and an output shape of @{code INT_VALUE}. * @since 1.8 */ enum StreamShape { - /** The shape specialization corresponding to {@code Stream} and elements that are object references */ + /** + * The shape specialization corresponding to {@code Stream} and elements + * that are object references + */ REFERENCE, - /** The shape specialization corresponding to {@code IntStream} and elements that are {@code int} values */ + /** + * The shape specialization corresponding to {@code IntStream} and elements + * that are {@code int} values + */ INT_VALUE, - /** The shape specialization corresponding to {@code LongStream} and elements that are {@code long} values */ + /** + * The shape specialization corresponding to {@code LongStream} and elements + * that are {@code long} values + */ LONG_VALUE, - /** The shape specialization corresponding to {@code DoubleStream} and elements that are {@code double} values */ + /** + * The shape specialization corresponding to {@code DoubleStream} and + * elements that are {@code double} values + */ DOUBLE_VALUE }
--- a/src/share/classes/java/util/stream/TerminalOp.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/TerminalOp.java Thu Feb 28 18:35:14 2013 +0100 @@ -25,13 +25,16 @@ package java.util.stream; /** - * An operation in a stream pipeline that takes a stream as input and produces a result or side-effect. - * A {@code TerminalOp} has an input type and stream shape, and a result type. A {@code TerminalOp} also - * has a set of <em>operation flags</em> that describes how the operation processes elements of the stream - * (such as short-circuiting or respecting encounter order; see {@link StreamOpFlag}). + * An operation in a stream pipeline that takes a stream as input and produces + * a result or side-effect. A {@code TerminalOp} has an input type and stream + * shape, and a result type. A {@code TerminalOp} also has a set of + * <em>operation flags</em> that describes how the operation processes elements + * of the stream (such as short-circuiting or respecting encounter order; see + * {@link StreamOpFlag}). * - * <p>A {@code TerminalOp} must provide a sequential and parallel implementation of the operation relative - * to a given stream source and set of intermediate operations. + * <p>A {@code TerminalOp} must provide a sequential and parallel implementation + * of the operation relative to a given stream source and set of intermediate + * operations. * * @param <E_IN> The type of input elements * @param <R> The type of the result @@ -42,15 +45,18 @@ interface TerminalOp<E_IN, R> { /** * Get the shape of the input type of this operation + * * @implSpec The default returns {@code StreamShape.REFERENCE} * @return Shape of the input type of this operation */ default StreamShape inputShape() { return StreamShape.REFERENCE; } /** - * Get the properties of the operation. Terminal operations may set a limited subset of the stream - * flags defined in {@link StreamOpFlag}, and these flags are combined with the previously combined stream and + * Get the properties of the operation. Terminal operations may set a + * limited subset of the stream flags defined in {@link StreamOpFlag}, and + * these flags are combined with the previously combined stream and * intermediate operation flags for the pipeline. + * * @implSpec The default implementation returns zero * @return the properties of the operation * @see {@link StreamOpFlag} @@ -58,10 +64,12 @@ default int getOpFlags() { return 0; } /** - * Perform a parallel evaluation of the operation using the specified {@code PipelineHelper}, which describes - * the stream source and upstream intermediate operations. - * @implSpec The default performs a sequential evaluation of the operation using the - * specified {@code PipelineHelper} + * Perform a parallel evaluation of the operation using the specified + * {@code PipelineHelper}, which describes the stream source and upstream + * intermediate operations. + * + * @implSpec The default performs a sequential evaluation of the operation + * using the specified {@code PipelineHelper} * * @param helper the pipeline helper * @param <P_IN> the type of elements in the pipeline source @@ -74,8 +82,9 @@ } /** - * Perform a sequential evaluation of the operation using the specified {@code PipelineHelper}, which describes - * the stream source and upstream intermediate operations. + * Perform a sequential evaluation of the operation using the specified + * {@code PipelineHelper}, which describes the stream source and upstream + * intermediate operations. * * @param helper the pipeline helper * @param <P_IN> the type of elements in the pipeline source
--- a/src/share/classes/java/util/stream/Tripwire.java Thu Feb 28 17:35:49 2013 +0100 +++ b/src/share/classes/java/util/stream/Tripwire.java Thu Feb 28 18:35:14 2013 +0100 @@ -28,10 +28,11 @@ import java.util.logging.Logger; /** - * Utility class for detecting inadvertent uses of boxing in {@code java.util.stream} classes. The - * detection is turned on or off based on whether the system property - * {@code org.openjdk.java.util.stream.tripwire} is considered {@code true} according to - * {@link Boolean#getBoolean(String)}. Turned off for production. + * Utility class for detecting inadvertent uses of boxing in + * {@code java.util.stream} classes. The detection is turned on or off based on + * whether the system property {@code org.openjdk.java.util.stream.tripwire} is + * considered {@code true} according to {@link Boolean#getBoolean(String)}. + * Turned off for production. * * @apiNote * Typical usage would be for boxing code to do: @@ -50,8 +51,10 @@ // = Boolean.getBoolean(TRIPWIRE_PROPERTY); /** - * Produce a log warning, using {@code Logger.getLogger(className)}, using the supplied message. The - * class name of {@code trippingClass} will be used as the first parameter to the message. + * Produce a log warning, using {@code Logger.getLogger(className)}, using + * the supplied message. The class name of {@code trippingClass} will be + * used as the first parameter to the message. + * * @param trippingClass Name of the class generating the message * @param msg A message format string of the type expected by {@link Logger} */