< prev index next >

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

Print this page
rev 53930 : 8148917: enhanced-for statement should allow streams
Reviewed-by: XXX
   1 /*
   2  * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any


  86  * the computation of the result.  For example, a stream implementation is free
  87  * to elide operations (or entire stages) from a stream pipeline -- and
  88  * therefore elide invocation of behavioral parameters -- if it can prove that
  89  * it would not affect the result of the computation.  This means that
  90  * side-effects of behavioral parameters may not always be executed and should
  91  * not be relied upon, unless otherwise specified (such as by the terminal
  92  * operations {@code forEach} and {@code forEachOrdered}). (For a specific
  93  * example of such an optimization, see the API note documented on the
  94  * {@link #count} operation.  For more detail, see the
  95  * <a href="package-summary.html#SideEffects">side-effects</a> section of the
  96  * stream package documentation.)
  97  *
  98  * <p>Collections and streams, while bearing some superficial similarities,
  99  * have different goals.  Collections are primarily concerned with the efficient
 100  * management of, and access to, their elements.  By contrast, streams do not
 101  * provide a means to directly access or manipulate their elements, and are
 102  * instead concerned with declaratively describing their source and the
 103  * computational operations which will be performed in aggregate on that source.
 104  * However, if the provided stream operations do not offer the desired
 105  * functionality, the {@link #iterator()} and {@link #spliterator()} operations
 106  * can be used to perform a controlled traversal.




 107  *
 108  * <p>A stream pipeline, like the "widgets" example above, can be viewed as
 109  * a <em>query</em> on the stream source.  Unless the source was explicitly
 110  * designed for concurrent modification (such as a {@link ConcurrentHashMap}),
 111  * unpredictable or erroneous behavior may result from modifying the stream
 112  * source while it is being queried.
 113  *
 114  * <p>Most stream operations accept parameters that describe user-specified
 115  * behavior, such as the lambda expression {@code w -> w.getWeight()} passed to
 116  * {@code mapToInt} in the example above.  To preserve correct behavior,
 117  * these <em>behavioral parameters</em>:
 118  * <ul>
 119  * <li>must be <a href="package-summary.html#NonInterference">non-interfering</a>
 120  * (they do not modify the stream source); and</li>
 121  * <li>in most cases must be <a href="package-summary.html#Statelessness">stateless</a>
 122  * (their result should not depend on any state that might change during execution
 123  * of the stream pipeline).</li>
 124  * </ul>
 125  *
 126  * <p>Such parameters are always instances of a


 147  * statement or similar control structure to ensure that it is closed promptly after its
 148  * operations have completed.
 149  *
 150  * <p>Stream pipelines may execute either sequentially or in
 151  * <a href="package-summary.html#Parallelism">parallel</a>.  This
 152  * execution mode is a property of the stream.  Streams are created
 153  * with an initial choice of sequential or parallel execution.  (For example,
 154  * {@link Collection#stream() Collection.stream()} creates a sequential stream,
 155  * and {@link Collection#parallelStream() Collection.parallelStream()} creates
 156  * a parallel one.)  This choice of execution mode may be modified by the
 157  * {@link #sequential()} or {@link #parallel()} methods, and may be queried with
 158  * the {@link #isParallel()} method.
 159  *
 160  * @param <T> the type of the stream elements
 161  * @since 1.8
 162  * @see IntStream
 163  * @see LongStream
 164  * @see DoubleStream
 165  * @see <a href="package-summary.html">java.util.stream</a>
 166  */
 167 public interface Stream<T> extends BaseStream<T, Stream<T>> {








 168 
 169     /**
 170      * Returns a stream consisting of the elements of this stream that match
 171      * the given predicate.
 172      *
 173      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
 174      * operation</a>.
 175      *
 176      * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
 177      *                  <a href="package-summary.html#Statelessness">stateless</a>
 178      *                  predicate to apply to each element to determine if it
 179      *                  should be included
 180      * @return the new stream
 181      */
 182     Stream<T> filter(Predicate<? super T> predicate);
 183 
 184     /**
 185      * Returns a stream consisting of the results of applying the given
 186      * function to the elements of this stream.
 187      *


   1 /*
   2  * Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any


  86  * the computation of the result.  For example, a stream implementation is free
  87  * to elide operations (or entire stages) from a stream pipeline -- and
  88  * therefore elide invocation of behavioral parameters -- if it can prove that
  89  * it would not affect the result of the computation.  This means that
  90  * side-effects of behavioral parameters may not always be executed and should
  91  * not be relied upon, unless otherwise specified (such as by the terminal
  92  * operations {@code forEach} and {@code forEachOrdered}). (For a specific
  93  * example of such an optimization, see the API note documented on the
  94  * {@link #count} operation.  For more detail, see the
  95  * <a href="package-summary.html#SideEffects">side-effects</a> section of the
  96  * stream package documentation.)
  97  *
  98  * <p>Collections and streams, while bearing some superficial similarities,
  99  * have different goals.  Collections are primarily concerned with the efficient
 100  * management of, and access to, their elements.  By contrast, streams do not
 101  * provide a means to directly access or manipulate their elements, and are
 102  * instead concerned with declaratively describing their source and the
 103  * computational operations which will be performed in aggregate on that source.
 104  * However, if the provided stream operations do not offer the desired
 105  * functionality, the {@link #iterator()} and {@link #spliterator()} operations
 106  * can be used to perform a controlled traversal. Stream implements the
 107  * {@link IterableOnce} interface, allowing a stream instance to be used
 108  * in an enhanced-for ("for each") statement. Note that this statement implicitly
 109  * calls the {@code iterator()} method, which consumes the stream. The stream
 110  * thus cannot be used for any subsequent operations.
 111  *
 112  * <p>A stream pipeline, like the "widgets" example above, can be viewed as
 113  * a <em>query</em> on the stream source.  Unless the source was explicitly
 114  * designed for concurrent modification (such as a {@link ConcurrentHashMap}),
 115  * unpredictable or erroneous behavior may result from modifying the stream
 116  * source while it is being queried.
 117  *
 118  * <p>Most stream operations accept parameters that describe user-specified
 119  * behavior, such as the lambda expression {@code w -> w.getWeight()} passed to
 120  * {@code mapToInt} in the example above.  To preserve correct behavior,
 121  * these <em>behavioral parameters</em>:
 122  * <ul>
 123  * <li>must be <a href="package-summary.html#NonInterference">non-interfering</a>
 124  * (they do not modify the stream source); and</li>
 125  * <li>in most cases must be <a href="package-summary.html#Statelessness">stateless</a>
 126  * (their result should not depend on any state that might change during execution
 127  * of the stream pipeline).</li>
 128  * </ul>
 129  *
 130  * <p>Such parameters are always instances of a


 151  * statement or similar control structure to ensure that it is closed promptly after its
 152  * operations have completed.
 153  *
 154  * <p>Stream pipelines may execute either sequentially or in
 155  * <a href="package-summary.html#Parallelism">parallel</a>.  This
 156  * execution mode is a property of the stream.  Streams are created
 157  * with an initial choice of sequential or parallel execution.  (For example,
 158  * {@link Collection#stream() Collection.stream()} creates a sequential stream,
 159  * and {@link Collection#parallelStream() Collection.parallelStream()} creates
 160  * a parallel one.)  This choice of execution mode may be modified by the
 161  * {@link #sequential()} or {@link #parallel()} methods, and may be queried with
 162  * the {@link #isParallel()} method.
 163  *
 164  * @param <T> the type of the stream elements
 165  * @since 1.8
 166  * @see IntStream
 167  * @see LongStream
 168  * @see DoubleStream
 169  * @see <a href="package-summary.html">java.util.stream</a>
 170  */
 171 public interface Stream<T> extends BaseStream<T, Stream<T>>, IterableOnce<T> {
 172 
 173     // Need to re-abstract spliterator() to avoid inheriting the default
 174     // method from Iterable.
 175     /**
 176      * {@inheritDoc}
 177      * @return {@inheritDoc}
 178      */
 179     Spliterator<T> spliterator();
 180 
 181     /**
 182      * Returns a stream consisting of the elements of this stream that match
 183      * the given predicate.
 184      *
 185      * <p>This is an <a href="package-summary.html#StreamOps">intermediate
 186      * operation</a>.
 187      *
 188      * @param predicate a <a href="package-summary.html#NonInterference">non-interfering</a>,
 189      *                  <a href="package-summary.html#Statelessness">stateless</a>
 190      *                  predicate to apply to each element to determine if it
 191      *                  should be included
 192      * @return the new stream
 193      */
 194     Stream<T> filter(Predicate<? super T> predicate);
 195 
 196     /**
 197      * Returns a stream consisting of the results of applying the given
 198      * function to the elements of this stream.
 199      *


< prev index next >