changeset 7491:8875666d12a8

Javadoc for stateful ops
author briangoetz
date Wed, 20 Feb 2013 23:13:38 -0500
parents 70bc1cf8584a
children 440c59e7eed0
files src/share/classes/java/util/stream/DistinctOp.java src/share/classes/java/util/stream/SliceOp.java src/share/classes/java/util/stream/SortedOp.java
diffstat 3 files changed, 58 insertions(+), 17 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/stream/DistinctOp.java	Wed Feb 20 20:37:46 2013 -0500
+++ b/src/share/classes/java/util/stream/DistinctOp.java	Wed Feb 20 23:13:38 2013 -0500
@@ -32,10 +32,8 @@
 import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
- * An stateful operation which eliminates duplicates from the stream.
- *
- * @param <T> Type of elements to be processed.
- *
+ * A {@link StatefulOp} that eliminates duplicates from a stream.
+ * @param <T> The input and output type of the stream pipeline
  * @since 1.8
  */
 class DistinctOp<T> implements StatefulOp<T> {
@@ -152,6 +150,11 @@
         }
     }
 
+    /**
+     * A abstract {@code Sink} implementation that does duplicate removal
+     * @param <S> Input element type to the stream pipeline
+     * @param <T> Output element type from the stream pipeline
+     */
     private static abstract class AbstractUniqOrderedSink<T, S extends AbstractUniqOrderedSink<T, S>>
             implements OpUtils.AccumulatingSink<T, Set<T>, S> {
         Set<T> set;
@@ -184,10 +187,11 @@
         }
     }
 
-    // Keep the type system happy
+    /** Concrete implementation of AbstractUniqOrderedSink */
     private static class UniqOrderedSink<T>
             extends AbstractUniqOrderedSink<T, UniqOrderedSink<T>> { }
 
+    /** Concrete implementation of AbstractUniqOrderedSink optimized for the case where input is already sorted */
     private static class UniqOrderedSortedSink<T>
             extends AbstractUniqOrderedSink<T, UniqOrderedSortedSink<T>> {
         boolean seenNull;
--- a/src/share/classes/java/util/stream/SliceOp.java	Wed Feb 20 20:37:46 2013 -0500
+++ b/src/share/classes/java/util/stream/SliceOp.java	Wed Feb 20 23:13:38 2013 -0500
@@ -30,16 +30,29 @@
 import java.util.concurrent.CountedCompleter;
 
 /**
- * SliceOp
- *
+ * A {@link StatefulOp} that transforms a stream into a subsequence of itself.
+ * @param <T> The input and output type of the stream pipeline
  * @since 1.8
  */
 class SliceOp<T> implements StatefulOp<T> {
+    /** The number of elements to skip */
     protected final long skip;
-    protected final long limit; // -1 means infinite
+
+    /** The maximum size of the resulting stream, or -1 if no limit is to be imposed */
+    protected final long limit;
+
+    /** The stream shape of the input and output streams */
     protected final StreamShape shape;
+
+    /** The sink transform for this operation */
     protected final AbstractPipeline.SinkWrapper sinkWrapper;
 
+    /**
+     * Construct a {@code SliceOp}, which may be a skip-only, limit-only, or skip-and-limit.
+     * @param skip The number of elements to skip.  Must be >= 0.
+     * @param limit The maximum size of the resulting stream, or -1 if no limit is to be imposed
+     * @param shape The stream shape of the input and output streams
+     */
     public SliceOp(long skip, long limit, StreamShape shape) {
         if (skip < 0)
             throw new IllegalArgumentException("Skip must be non-negative: " + skip);
@@ -56,10 +69,7 @@
         }
     }
 
-    public SliceOp(long skip, StreamShape shape) {
-        this(skip, -1, shape);
-    }
-
+    /** Sink transform function for reference streams */
     private<T> Sink<T> wrapSinkRef(int flags, Sink sink) {
         return new Sink.ChainedReference<T>(sink) {
             long n = skip;
@@ -85,6 +95,7 @@
         };
     }
 
+    /** Sink transform function for int streams */
     private Sink<Integer> wrapSinkInt(int flags, Sink sink) {
         return new Sink.ChainedInt(sink) {
             long n = skip;
@@ -110,6 +121,7 @@
         };
     }
 
+    /** Sink transform function for long streams */
     private Sink<Long> wrapSinkLong(int flags, Sink sink) {
         return new Sink.ChainedLong(sink) {
             long n = skip;
@@ -135,6 +147,7 @@
         };
     }
 
+    /** Sink transform function for double streams */
     private Sink<Double> wrapSinkDouble(int flags, Sink sink) {
         return new Sink.ChainedDouble(sink) {
             long n = skip;
@@ -219,6 +232,12 @@
         return String.format("SliceOp[skip=%d,limit=%d]", skip, limit);
     }
 
+    /**
+     * {@code ForkJoinTask} implementing slice computation
+     *
+     * @param <S> Input element type to the stream pipeline
+     * @param <T> Output element type from the stream pipeline
+     */
     private static class SliceTask<S, T> extends AbstractShortCircuitTask<S, T, Node<T>, SliceTask<S, T>> {
         private final SliceOp<T> op;
         private final long targetOffset, targetSize;
--- a/src/share/classes/java/util/stream/SortedOp.java	Wed Feb 20 20:37:46 2013 -0500
+++ b/src/share/classes/java/util/stream/SortedOp.java	Wed Feb 20 23:13:38 2013 -0500
@@ -29,23 +29,25 @@
 import java.util.Comparator;
 import java.util.Comparators;
 import java.util.Objects;
+import java.util.concurrent.ForkJoinTask;
 
 
 /**
- * An operation which sorts elements.
+ * A {@link StatefulOp} that sorts the elements of stream.
  *
  * @param <T> Type of elements to be sorted.
  *
  * @since 1.8
  */
-// @@@ If terminal op is not ORDERED then is there any point sorting
 abstract class SortedOp<T> implements StatefulOp<T> {
+    /** The stream shape of the input and output stream */
     private final StreamShape shape;
 
     protected SortedOp(StreamShape shape) {
         this.shape = shape;
     }
 
+    /** Specialized subtype for sorting reference streams */
     public static class OfRef<T> extends SortedOp<T> {
         /** Comparator used for sorting */
         private final Comparator<? super T> comparator;
@@ -94,6 +96,7 @@
         }
     }
 
+    /** Specialized subtype for sorting int streams */
     public static class OfInt extends SortedOp<Integer> {
         public OfInt() {
             super(StreamShape.INT_VALUE);
@@ -122,6 +125,7 @@
         }
     }
 
+    /** Specialized subtype for sorting long streams */
     public static class OfLong extends SortedOp<Long> {
         public OfLong() {
             super(StreamShape.LONG_VALUE);
@@ -150,6 +154,7 @@
         }
     }
 
+    /** Specialized subtype for sorting double streams */
     public static class OfDouble extends SortedOp<Double> {
         public OfDouble() {
             super(StreamShape.DOUBLE_VALUE);
@@ -193,6 +198,7 @@
         return shape;
     }
 
+    /** {@link ForkJoinTask} for implementing sort on SIZED reference streams */
     private static class SizedRefSortingSink<T> extends Sink.ChainedReference<T> {
         private final Comparator<? super T> comparator;
         T[] array;
@@ -230,6 +236,7 @@
         }
     }
 
+    /** {@link Sink} for implementing sort on reference streams */
     private static class RefSortingSink<T> extends Sink.ChainedReference<T> {
         private final Comparator<? super T> comparator;
         ArrayList<T> list;
@@ -259,6 +266,7 @@
         }
     }
 
+    /** {@link Sink} for implementing sort on SIZED int streams */
     private static class SizedIntSortingSink extends Sink.ChainedInt {
         int[] array;
         int offset;
@@ -290,10 +298,13 @@
         }
     }
 
+    /** {@link Sink} for implementing sort on int streams */
     private static class IntSortingSink extends Sink.ChainedInt {
         SpinedBuffer.OfInt b;
 
-        public IntSortingSink(Sink sink) {super(sink);}
+        public IntSortingSink(Sink sink) {
+            super(sink);
+        }
 
         @Override
         public void begin(long size) {
@@ -316,6 +327,7 @@
         }
     }
 
+    /** {@link Sink} for implementing sort on SIZED long streams */
     private static class SizedLongSortingSink extends Sink.ChainedLong {
         long[] array;
         int offset;
@@ -347,10 +359,13 @@
         }
     }
 
+    /** {@link Sink} for implementing sort on long streams */
     private static class LongSortingSink extends Sink.ChainedLong {
         SpinedBuffer.OfLong b;
 
-        public LongSortingSink(Sink sink) {super(sink);}
+        public LongSortingSink(Sink sink) {
+            super(sink);
+        }
 
         @Override
         public void begin(long size) {
@@ -373,6 +388,7 @@
         }
     }
 
+    /** {@link Sink} for implementing sort on SIZED double streams */
     private static class SizedDoubleSortingSink extends Sink.ChainedDouble {
         double[] array;
         int offset;
@@ -404,10 +420,12 @@
         }
     }
 
+    /** {@link Sink} for implementing sort on double streams */
     private static class DoubleSortingSink extends Sink.ChainedDouble {
         SpinedBuffer.OfDouble b;
 
-        public DoubleSortingSink(Sink sink) {super(sink);}
+        public DoubleSortingSink(Sink sink) {
+            super(sink);}
 
         @Override
         public void begin(long size) {