--- old/src/java.base/share/classes/java/nio/file/DirectoryStream.java 2019-02-27 18:10:40.000000000 -0800
+++ new/src/java.base/share/classes/java/nio/file/DirectoryStream.java 2019-02-27 18:10:40.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2007, 2019, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -34,10 +34,10 @@
* allows for the convenient use of the for-each construct to iterate over a
* directory.
*
- *
While {@code DirectoryStream} extends {@code Iterable}, it is not a
+ *
{@code DirectoryStream} extends {@code IterableOnce}. It is not a
* general-purpose {@code Iterable} as it supports only a single {@code
* Iterator}; invoking the {@link #iterator iterator} method to obtain a second
- * or subsequent iterator throws {@code IllegalStateException}.
+ * or subsequent iterator throws {@code IllegalStateException}.
*
*
An important property of the directory stream's {@code Iterator} is that
* its {@link Iterator#hasNext() hasNext} method is guaranteed to read-ahead by
@@ -117,7 +117,7 @@
*/
public interface DirectoryStream
- extends Closeable, Iterable {
+ extends Closeable, IterableOnce {
/**
* An interface that is implemented by objects that decide if a directory
* entry should be accepted or filtered. A {@code Filter} is passed as the
--- old/src/java.base/share/classes/java/util/Scanner.java 2019-02-27 18:10:41.000000000 -0800
+++ new/src/java.base/share/classes/java/util/Scanner.java 2019-02-27 18:10:41.000000000 -0800
@@ -307,7 +307,7 @@
*
* @since 1.5
*/
-public final class Scanner implements Iterator, Closeable {
+public final class Scanner implements Iterator, Closeable, IterableOnce {
// Internal buffer used to hold input
private CharBuffer buf;
@@ -372,6 +372,9 @@
// A holder of the last IOException encountered
private IOException lastException;
+ // Whether this Scanner, as IterableOnce, has been consumed
+ private boolean consumed = false;
+
// Number of times this scanner's state has been modified.
// Generally incremented on most public APIs and checked
// within spliterator implementations.
@@ -1480,6 +1483,24 @@
}
/**
+ * Returns this Scanner instance. This method exists to implement the
+ * {@link IterableOnce} interface, allowing a Scanner instance to be
+ * used in an enhanced-for ("for each") statement. This method can be
+ * called no more than once on any Scanner instance. The second and
+ * subsequent calls result in an exception.
+ *
+ * @throws IllegalStateException if this method had been called previously
+ * @return this Scanner instance
+ */
+ public Scanner iterator() {
+ if (consumed) {
+ throw new IllegalStateException();
+ }
+ consumed = true;
+ return this;
+ }
+
+ /**
* The remove operation is not supported by this implementation of
* {@code Iterator}.
*
--- old/src/java.base/share/classes/java/util/stream/Stream.java 2019-02-27 18:10:43.000000000 -0800
+++ new/src/java.base/share/classes/java/util/stream/Stream.java 2019-02-27 18:10:43.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -103,7 +103,11 @@
* computational operations which will be performed in aggregate on that source.
* However, if the provided stream operations do not offer the desired
* functionality, the {@link #iterator()} and {@link #spliterator()} operations
- * can be used to perform a controlled traversal.
+ * can be used to perform a controlled traversal. Stream implements the
+ * {@link IterableOnce} interface, allowing a stream instance to be used
+ * in an enhanced-for ("for each") statement. Note that this statement implicitly
+ * calls the {@code iterator()} method, which consumes the stream. The stream
+ * thus cannot be used for any subsequent operations.
*
* A stream pipeline, like the "widgets" example above, can be viewed as
* a query on the stream source. Unless the source was explicitly
@@ -164,7 +168,15 @@
* @see DoubleStream
* @see java.util.stream
*/
-public interface Stream extends BaseStream> {
+public interface Stream extends BaseStream>, IterableOnce {
+
+ // Need to re-abstract spliterator() to avoid inheriting the default
+ // method from Iterable.
+ /**
+ * {@inheritDoc}
+ * @return {@inheritDoc}
+ */
+ Spliterator spliterator();
/**
* Returns a stream consisting of the elements of this stream that match
--- /dev/null 2019-02-27 18:10:44.000000000 -0800
+++ new/src/java.base/share/classes/java/lang/IterableOnce.java 2019-02-27 18:10:44.000000000 -0800
@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.lang;
+
+import java.util.Iterator;
+
+/**
+ * An Iterable from which only a single Iterator can be obtained.
+ *
+ * @apiNote
+ * IterableOnce is functionally identical to Iterable. A class can
+ * implement IterableOnce in preference to Iterable in order to signal
+ * to applications that only a single Iterator can be obtained. It is
+ * recommended that attempts to call the iterator() method the second
+ * and subsequent time results in IllegalStateException.
+ *
+ * @param the type of elements returned by the iterator
+ */
+public interface IterableOnce extends Iterable {
+ /**
+ * Returns an iterator over elements of type {@code T}. This method
+ * can be called successfully only once. The second and subsequent
+ * invocations of this method throw IllegalStateException.
+ *
+ * @return an Iterator
+ * @throws IllegalStateException if this method has been called previously
+ */
+ Iterator iterator();
+}