changeset 5770:6792f105f861 it2-bootstrap

lots of javadocing and minor cleanups.
author mduigou
date Tue, 17 Jul 2012 13:39:54 -0700
parents 2c934b9d81d9
children 5d2046e61a6a
files make/netbeans/common/java-data-native.ent make/netbeans/common/java-data-no-native.ent src/share/classes/java/util/Arrays.java src/share/classes/java/util/MapIterator.java src/share/classes/java/util/Sized.java src/share/classes/java/util/Traversable.java src/share/classes/java/util/functions/FlatMapper.java src/share/classes/java/util/functions/Sink.java src/share/classes/java/util/streams/MapStreamOps.java src/share/classes/java/util/streams/SequentialMapPipeline.java src/share/classes/java/util/streams/SizedStreamable.java src/share/classes/java/util/streams/StatefulSink.java src/share/classes/java/util/streams/Stream.java src/share/classes/java/util/streams/StreamBuilder.java src/share/classes/java/util/streams/StreamBuilders.java src/share/classes/java/util/streams/ops/ElementwiseOp.java src/share/classes/java/util/streams/ops/MapOp.java src/share/classes/java/util/streams/ops/ParallelOp.java src/share/classes/java/util/streams/ops/SortedOp.java src/share/classes/java/util/streams/ops/StatefulOp.java
diffstat 20 files changed, 220 insertions(+), 90 deletions(-) [+]
line wrap: on
line diff
--- a/make/netbeans/common/java-data-native.ent	Thu Jul 12 18:53:05 2012 -0700
+++ b/make/netbeans/common/java-data-native.ent	Tue Jul 17 13:39:54 2012 -0700
@@ -39,18 +39,18 @@
 <!--        <classpath mode="boot">${bootstrap.jdk}/jre/lib/rt.jar</classpath> -->
         <built-to>${root}/build/${platform}-${arch}/classes</built-to>
         <javadoc-built-to>${root}/build/${platform}-${arch}/docs/api</javadoc-built-to>
-        <source-level>1.7</source-level>
+        <source-level>1.8</source-level>
     </compilation-unit>
     <compilation-unit>
         <package-root>${root}/test</package-root>
         <unit-tests/>
-        <source-level>1.7</source-level>
+        <source-level>1.8</source-level>
     </compilation-unit>
     <compilation-unit>
         <package-root>${root}/test-ng/tests</package-root>
         <unit-tests/>
         <classpath mode="compile">${root}/test-ng/lib/testng-6.5.2.jar</classpath>
         <built-to>${root}/test-ng/build/test-classes</built-to>
-        <source-level>1.7</source-level>
+        <source-level>1.8</source-level>
     </compilation-unit>
 </java-data>
--- a/make/netbeans/common/java-data-no-native.ent	Thu Jul 12 18:53:05 2012 -0700
+++ b/make/netbeans/common/java-data-no-native.ent	Tue Jul 17 13:39:54 2012 -0700
@@ -37,18 +37,18 @@
 <!--        <classpath mode="boot">${bootstrap.jdk}/jre/lib/rt.jar</classpath> -->
         <built-to>${root}/build/${platform}-${arch}/classes</built-to>
         <javadoc-built-to>${root}/build/${platform}-${arch}/docs/api</javadoc-built-to>
-        <source-level>1.7</source-level>
+        <source-level>1.8</source-level>
     </compilation-unit>
     <compilation-unit>
         <package-root>${root}/test</package-root>
         <unit-tests/>
-        <source-level>1.7</source-level>
+        <source-level>1.8</source-level>
     </compilation-unit>
     <compilation-unit>
         <package-root>${root}/test-ng/tests</package-root>
         <unit-tests/>
         <classpath mode="compile">${root}/test-ng/lib/testng-6.5.2.jar</classpath>
         <built-to>${root}/test-ng/build/test-classes</built-to>
-        <source-level>1.7</source-level>
+        <source-level>1.8</source-level>
     </compilation-unit>
 </java-data>
--- a/src/share/classes/java/util/Arrays.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/Arrays.java	Tue Jul 17 13:39:54 2012 -0700
@@ -3695,10 +3695,10 @@
         private int offset;
 
         private ArrayIterator(T[] array, int startOffset, int len) {
-            this.array = array;
+            this.array = Objects.requireNonNull(array);
             this.endOffset = startOffset + len;
             this.offset = startOffset;
-            
+
             assert (offset >= 0) && ((offset < array.length) || (offset == endOffset)): "offset not in array";
             assert (endOffset >= offset) && (endOffset <= array.length) : "end not in array";
         }
@@ -3713,7 +3713,7 @@
             if(!hasNext()) {
                 throw new NoSuchElementException();
             }
-            return array[offset++];            
+            return array[offset++];
         }
     }
 
@@ -3721,9 +3721,12 @@
         private final T[] array;
         private int curIndex;
         private final int endIndex;
-        private boolean started = false;
-
-        public ArraySpliterator(T[] array, int offset, int length) {
+
+        ArraySpliterator(T[] array) {
+            this(array, 0, array.length);
+        }
+
+        ArraySpliterator(T[] array, int offset, int length) {
             this.array = array;
             this.curIndex = offset;
             this.endIndex = offset+length;
@@ -3731,12 +3734,11 @@
 
         @Override
         public T next() {
-            if (curIndex >= endIndex)
+            if (curIndex >= endIndex) {
                 throw new NoSuchElementException();
-            else {
-                started = true;
-                return array[curIndex++];
             }
+
+            return array[curIndex++];
         }
 
         @Override
@@ -3756,8 +3758,9 @@
 
         @Override
         public void forEach(Sink<? super T> sink) {
-            while (curIndex < endIndex)
+            while (curIndex < endIndex) {
                 sink.accept(array[curIndex++]);
+            }
         }
 
         @Override
@@ -3774,16 +3777,16 @@
         private final int offset;
         private final int length;
 
-        public ArraySplittable(T[] array, int offset, int length) {
-            this.array = array;
+        ArraySplittable(T[] array) {
+            this(array, 0, array.length);
+        }
+
+        ArraySplittable(T[] array, int offset, int length) {
+            this.array = Objects.requireNonNull(array);
             this.offset = offset;
             this.length = length;
         }
 
-        public ArraySplittable(T[] array) {
-            this(array, 0, array.length);
-        }
-
         @Override
         public Spliterator<T> spliterator() {
             return new ArraySpliterator<>(array, offset, length);
@@ -3806,20 +3809,21 @@
         private final int length;
         private int index = 0;
 
-        private ArraySink(T[] array, int offset, int length) {
-            this.array = array;
+        ArraySink(T[] array) {
+            this(array, 0, array.length);
+        }
+
+        ArraySink(T[] array, int offset, int length) {
+            this.array = Objects.requireNonNull(array);
             this.offset = offset;
             this.length = length;
         }
 
-        private ArraySink(T[] array) {
-            this(array, 0, array.length);
-        }
-
         @Override
         public void accept(T t) {
-            if (index > length)
+            if (index > length) {
                 throw new IndexOutOfBoundsException(Integer.toString(index));
+            }
             array[offset + (index++)] = t;
         }
     }
--- a/src/share/classes/java/util/MapIterator.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/MapIterator.java	Tue Jul 17 13:39:54 2012 -0700
@@ -25,13 +25,39 @@
 package java.util;
 
 /**
- * BiIterator
+ * An {@link Iterator} extended two support key-value mappings.
  *
  * @author Brian Goetz
  */
 public interface MapIterator<K, V> extends Iterator<Mapping<K, V>> {
+    /**
+     * Advance the iterator and return the current key.
+     *
+     * @return The current key after advancing the iterator or the first key.
+     */
     K nextKey();
+
+    /**
+     * Advance the iterator and return the current value.
+     *
+     * @return The current key after advancing the iterator or the first key.
+     */
     V nextValue();
+
+    /**
+     * Return the current key.
+     *
+     * @return the current key.
+     */
     K curKey();
+
+    /**
+     * Return the current value;
+     *
+     * @return the current value.
+     */
     V curValue();
+
+    // ?!? mduigou It's kind of strange to be able to get current without a
+    // way to advance the iteration. It is intended that next() be used?
 }
--- a/src/share/classes/java/util/Sized.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/Sized.java	Tue Jul 17 13:39:54 2012 -0700
@@ -25,12 +25,25 @@
 package java.util;
 
 /**
- * Sized
+ * Implementing this interface allows an object to indicate that its elements
+ * may be efficiently counted. Counting is always less than O(n).
  *
  * @author Brian Goetz
  */
 public interface Sized {
+    // ?!? mduigou This was "long count()" How did this get back to int and size()?
+    /**
+     * A non-negative integer indicating a count of elements.
+     *
+     * @return non-negative integer indicating a count of elements.
+     */
     public int size();
 
+    /**
+     * Returns {@code true} if the size is zero. May be more efficient than
+     * calculating size.
+     *
+     * @return  {@code true} if the size is zero otherwise {@code false}.
+     */
     public boolean isEmpty() default { return size() != 0; }
 }
--- a/src/share/classes/java/util/Traversable.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/Traversable.java	Tue Jul 17 13:39:54 2012 -0700
@@ -27,10 +27,18 @@
 import java.util.functions.Sink;
 
 /**
- * Traversable
+ * Implementing this interface allows an object to indicate that it provides
+ * the {@code forEach} method for internal iteration.
+ *
+ * @param <T> type of elements to be traversed.
  *
  * @author Brian Goetz
  */
 public interface Traversable<T> extends Iterable<T> {
+    /**
+     * Each element of the object will be provided to the specified Sink.
+     *
+     * @param sink The Sink to which elements will be provided.
+     */
     public void forEach(Sink<? super T> sink);
 }
--- a/src/share/classes/java/util/functions/FlatMapper.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/functions/FlatMapper.java	Tue Jul 17 13:39:54 2012 -0700
@@ -25,10 +25,16 @@
 package java.util.functions;
 
 /**
- * FlatMapper
+ * Map an element and add results to a sink.
  *
  * @author Brian Goetz
  */
 public interface FlatMapper<T, R> {
+    /**
+     * Map {@code element} and add all of the results to {@code sink}.
+     *
+     * @param sink Destination for mapped elements.
+     * @param element The element to be mapped.
+     */
     void flatMapInto(Sink<? super R> sink, T element);
 }
--- a/src/share/classes/java/util/functions/Sink.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/functions/Sink.java	Tue Jul 17 13:39:54 2012 -0700
@@ -25,11 +25,18 @@
 package java.util.functions;
 
 /**
- * Sink
+ * A receiver of elements. The counterpart to {@code Stream}.
+ *
+ * @param <T> The type of elements accepted by this Sink.
  *
  * @author Brian Goetz
  */
 public interface Sink<T> {
+    /**
+     * Accept an element.
+     *
+     * @param t The element to be accepted.
+     */
     void accept(T t);
 
     public Sink<T> tee(Sink<? super T> other) default {
--- a/src/share/classes/java/util/streams/MapStreamOps.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/streams/MapStreamOps.java	Tue Jul 17 13:39:54 2012 -0700
@@ -31,9 +31,13 @@
 import java.util.functions.*;
 
 /**
- * SequentialMapStreamOps
+ * Operations upon MapStreams.
  *
- * @author Brian Goetz
+ * @param <K> Type of Mapping keys.
+ * @param <V> Type of Mapping values.
+
+ *
+ * @author Brian Goetzt
  */
 interface MapStreamOps<K, V> {
     Optional<Mapping<K,V>> findFirst();
--- a/src/share/classes/java/util/streams/SequentialMapPipeline.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/streams/SequentialMapPipeline.java	Tue Jul 17 13:39:54 2012 -0700
@@ -54,7 +54,7 @@
 
     @Override
     public MapIterator<K,V> iterator() {
-        throw new UnsupportedOperationException();
+        throw new UnsupportedOperationException("nyi");
     }
 
     @Override
@@ -146,7 +146,7 @@
 
     @Override
     public MapStream<K, V> filter(BiPredicate<? super K, ? super V> predicate) {
-        return null;
+        throw new UnsupportedOperationException("nyi");
     }
 
     @Override
@@ -161,51 +161,51 @@
 
     @Override
     public <U> MapStream<K, U> mapValues(BiMapper<? super K, ? super V, ? extends U> mapper) {
-        return null;
+        throw new UnsupportedOperationException("nyi");
     }
 
     @Override
     public <U> MapStream<K, U> mapValues(Mapper<? super V, ? extends U> mapper) {
-        return null;
+        throw new UnsupportedOperationException("nyi");
     }
 
     @Override
     public MapStream<V, K> swap() {
-        return null;
+        throw new UnsupportedOperationException("nyi");
     }
 
     @Override
     public MapStream<K, V> sorted(Comparator<? super K> comparator) {
-        return null;
+        throw new UnsupportedOperationException("nyi");
     }
 
     @Override
     public MapStream<K, V> mergeWith(MapStream<K, ? extends V> other) {
-        return null;
+        throw new UnsupportedOperationException("nyi");
     }
 
     @Override
     public boolean noneMatch(BiPredicate<? super K, ? super V> predicate) {
-        return false;
+        throw new UnsupportedOperationException("nyi");
     }
 
     @Override
     public boolean allMatch(BiPredicate<? super K, ? super V> predicate) {
-        return false;
+        throw new UnsupportedOperationException("nyi");
     }
 
     @Override
     public boolean anyMatch(BiPredicate<? super K, ? super V> predicate) {
-        return false;
+        throw new UnsupportedOperationException("nyi");
     }
 
     @Override
     public Optional<Mapping<K, V>> findAny() {
-        return null;
+        throw new UnsupportedOperationException("nyi");
     }
 
     @Override
     public Optional<Mapping<K, V>> findFirst() {
-        return null;
+        throw new UnsupportedOperationException("nyi");
     }
 }
--- a/src/share/classes/java/util/streams/SizedStreamable.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/streams/SizedStreamable.java	Tue Jul 17 13:39:54 2012 -0700
@@ -27,7 +27,7 @@
 import java.util.Sized;
 
 /**
- * SizedStreamable
+ * A Streamable that is also Sized.
  *
  * @author Brian Goetz
  */
--- a/src/share/classes/java/util/streams/StatefulSink.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/streams/StatefulSink.java	Tue Jul 17 13:39:54 2012 -0700
@@ -27,22 +27,29 @@
 import java.util.functions.Sink;
 
 /**
- * StatefulSink
+ * A Sink which accumulates state as elements are accepted.
+ *
+ * @param <T> The type of elements to be accepted.
+ * @param <V> The type of the terminal state.
  *
  * @author Brian Goetz
  */
 public interface StatefulSink<T, V> extends Sink<T> {
     /**
-     * Reset the sink state to receive a fresh data set.  This is used when a Sink is being reused by multiple
-     * calculations.
-     * @param size The size of the data to be pushed downstream, if known.  If unknown, will be -1.
+     * Reset the sink state to receive a fresh data set.  This is used when a
+     * Sink is being reused by multiple calculations.
+     * @param size The approximate size of the data to be pushed downstream, if
+     * known or -1 if size is unknown.
      */
     void begin(int size);
 
     /**
-     * Indicate that all data that is going to be pushed has been pushed.  Chained sinks should dump their
-     * contents downstream and clear any stored state; terminal sinks should return their terminal state and
-     * clear any stored state.
+     * Indicate that all element that is going to be pushed has been pushed.
+     * Chained sinks should dump their contents downstream and clear any stored
+     * state; terminal sinks should return their terminal state and clear any
+     * stored state.
+     *
+     * @return The terminal state of the sink. 
      */
     V end();
 }
--- a/src/share/classes/java/util/streams/Stream.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/streams/Stream.java	Tue Jul 17 13:39:54 2012 -0700
@@ -27,14 +27,35 @@
 import java.util.Iterator;
 
 /**
- * Stream
+ * A source of elements which may be iterated or mutated.
  *
  * @author Brian Goetz
  */
 public interface Stream<T> extends StreamOps<T>, Iterator<T> {
+    /**
+     * Stream elements are unique. No two elements contained in the stream
+     * are equivalent via {@code equals()}
+     */
     public static final int STATE_UNIQUE = 1;
+    /**
+     * Stream elements are sorted. Elements are {@code Comparable} and each
+     * element is greater or equal to the element which preceed it (if any) and
+     * less than or equal to the element which follows it (if any).
+     */
     public static final int STATE_SORTED = 2;
+
+    /*
+     * Stream size can be calculated in less than {@code O(n)} time.
+     */
     public static final int STATE_SIZED = 4;
+
+    /**
+     * Mask of state bits for defined states.
+     */
     public static final int STATE_MASK = 0x7;
+
+    /**
+     * Mask of undefined state bits.
+     */
     public static final int STATE_UNKNOWN_MASK_V1 = ~(STATE_UNIQUE | STATE_SORTED | STATE_SIZED);
 }
--- a/src/share/classes/java/util/streams/StreamBuilder.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/streams/StreamBuilder.java	Tue Jul 17 13:39:54 2012 -0700
@@ -33,11 +33,13 @@
  * @author Brian Goetz
  */
 public interface StreamBuilder<T> extends SizedStreamable<T>, Sink<T>, Sized /* , Fillable<T> */ {
-    public int getStreamState();
+    @Override
+    int getStreamState();
 
-    public void forEach(Sink<? super T> sink);
+    @Override
+    void forEach(Sink<? super T> sink);
 
-    public void clear();
+    void clear();
 
-    public Object[] toArray();
+    Object[] toArray();
 }
--- a/src/share/classes/java/util/streams/StreamBuilders.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/streams/StreamBuilders.java	Tue Jul 17 13:39:54 2012 -0700
@@ -31,7 +31,7 @@
 import java.util.functions.Sink;
 
 /**
- * StreamBuilders
+ * Utilities for building streams.
  *
  * @author Brian Goetz
  */
@@ -52,11 +52,11 @@
     }
 
     private static class FixedStreamBuilder<T> implements StreamBuilder<T> {
-        private final T[] array;
+        private final Object[] array;
         private int curSize;
 
         public FixedStreamBuilder(int size) {
-            array = (T[]) new Object[size];
+            array = new Object[size];
         }
 
         @Override
@@ -74,13 +74,14 @@
 
         @Override
         public void forEach(Sink<? super T> sink) {
-            for (int i=0; i<curSize; i++)
-                sink.accept(array[i]);
+            for (int i=0; i<curSize; i++) {
+                sink.accept((T) array[i]);
+            }
         }
 
         @Override
         public Iterator<T> iterator() {
-            return Arrays.iterator(array, 0, curSize);
+            return Arrays.iterator( (T[]) array, 0, curSize);
         }
 
         @Override
@@ -93,11 +94,14 @@
             return curSize;
         }
 
+        @Override
         public Object[] toArray() {
-            if (curSize == array.length)
+            if (curSize == array.length) {
                 return array;
-            else
+            }
+            else {
                 return Arrays.copyOf(array, curSize);
+            }
         }
     }
 
@@ -138,10 +142,12 @@
             return list.iterator();
         }
 
+        @Override
         public void clear() {
             list.clear();
         }
 
+        @Override
         public Object[] toArray() {
             return list.toArray();
         }
--- a/src/share/classes/java/util/streams/ops/ElementwiseOp.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/streams/ops/ElementwiseOp.java	Tue Jul 17 13:39:54 2012 -0700
@@ -28,18 +28,17 @@
 import java.util.functions.Sink;
 
 /**
- * LazyOp
+ * An operation performed upon elements.
  *
  * @author Brian Goetz
  */
 public interface ElementwiseOp<T,U> {
-    public int getStreamState(int upstreamState) default {
-        return 0;
-    }
 
-    public abstract boolean isStateful();
+    int getStreamState(int upstreamState);
 
-    public abstract Iterator<U> iterator(final Iterator<T> in);
+    boolean isStateful();
 
-    public abstract Sink<T> sink(Sink<? super U> sink);
+    Iterator<U> iterator(final Iterator<T> in);
+
+    Sink<T> sink(Sink<? super U> sink);
 }
--- a/src/share/classes/java/util/streams/ops/MapOp.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/streams/ops/MapOp.java	Tue Jul 17 13:39:54 2012 -0700
@@ -39,8 +39,7 @@
     public final Mapper<? super T, ? extends R> mapper;
 
     public MapOp(Mapper<? super T, ? extends R> mapper) {
-        Objects.requireNonNull(mapper);
-        this.mapper = mapper;
+        this.mapper = Objects.requireNonNull(mapper);
     }
 
     @Override
@@ -58,6 +57,7 @@
     public Sink<T> sink(final Sink<? super R> sink) {
         Objects.requireNonNull(sink);
         return new Sink<T>() {
+            @Override
             public void accept(T t) {
                 sink.accept(mapper.map(t));
             }
--- a/src/share/classes/java/util/streams/ops/ParallelOp.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/streams/ops/ParallelOp.java	Tue Jul 17 13:39:54 2012 -0700
@@ -35,12 +35,20 @@
  * @author Brian Goetz
  */
 public interface ParallelOp<T, U> {
-    public static interface ParallelOpHelper<T, V> {
+    public interface ParallelOpHelper<T, V> {
         public int suggestDepth(ParallelStreamable<V> source);
         public Sink<V> sink(Sink<T> sink);
         public Iterator<T> iterator();
         public<Z> Z invoke(ForkJoinTask<Z> task);
     }
 
+    /**
+     * Compute the result of the operation in parallel and return the result.
+     *
+     * @param <V>
+     * @param source element source
+     * @param helper 
+     * @return result of the operation.
+     */
     <V> U computeParallel(ParallelStreamable<V> source, ParallelOpHelper<T, V> helper);
 }
--- a/src/share/classes/java/util/streams/ops/SortedOp.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/streams/ops/SortedOp.java	Tue Jul 17 13:39:54 2012 -0700
@@ -27,29 +27,41 @@
 import java.util.*;
 import java.util.functions.Sink;
 import java.util.streams.ParallelStreamable;
-import java.util.streams.SequentialPipeline;
 import java.util.streams.StatefulSink;
-import java.util.streams.Streams;
+import java.util.streams.Stream;
+
 
 /**
- * SortedOp
+ * An operation which sorts elements.
  *
  * @author Brian Goetz
  */
 public class SortedOp<T> implements StatefulOp<T,T,Void> {
     private static final int DEFAULT_PRIORITY_QUEUE_SIZE = 16;
 
+    /**
+     * Comparator used for sorting.
+     */
     private final Comparator<? super T> comparator;
 
-    public SortedOp(Comparator<? super T> comparator) {
-        this.comparator = Objects.requireNonNull(comparator);
-    }
-
+    /**
+     * Sort using natural order of {@literal <T>} which must be
+     * {@code Comparable}.
+     */
     public SortedOp() {
         // Will throw CCE when we try to sort if T is not Comparable
         this((Comparator<? super T>) Comparators.naturalOrder());
     }
 
+    /**
+     * Sort using the provided comparator.
+     *
+     * @param comparator The comparator to be used to evaluate ordering.
+     */
+    public SortedOp(Comparator<? super T> comparator) {
+        this.comparator = Objects.requireNonNull(comparator);
+    }
+
     @Override
     public StatefulSink<T, Void> sink(final Sink<? super T> sink) {
         return new StatefulSink<T, Void>() {
@@ -61,8 +73,9 @@
 
             @Override
             public Void end() {
-                while (!pq.isEmpty())
+                while (!pq.isEmpty()) {
                     sink.accept(pq.remove());
+                }
                 return null;
             }
 
@@ -83,8 +96,9 @@
         Objects.requireNonNull(iterator);
         Objects.requireNonNull(comparator);
         final PriorityQueue<T> pq = new PriorityQueue<>(DEFAULT_PRIORITY_QUEUE_SIZE, comparator);
-        while (iterator.hasNext())
+        while (iterator.hasNext()) {
             pq.add(iterator.next());
+        }
         return new Iterator<T>() {
             @Override
             public boolean hasNext() {
@@ -97,4 +111,9 @@
             }
         };
     }
+
+    @Override
+    public int getStreamState(int upstreamState) {
+        return upstreamState | Stream.STATE_SORTED;
+    }
 }
--- a/src/share/classes/java/util/streams/ops/StatefulOp.java	Thu Jul 12 18:53:05 2012 -0700
+++ b/src/share/classes/java/util/streams/ops/StatefulOp.java	Tue Jul 17 13:39:54 2012 -0700
@@ -5,7 +5,7 @@
 import java.util.streams.*;
 
 /**
- * StatefulOp
+ * A stateful operation. State is accumulated as elements are processed.
  */
 public interface StatefulOp<T, U, V> extends ElementwiseOp<T,U>, ParallelOp<T, ParallelStreamable<U>> {