From d19ea66b189699e914622c19a444de7ff906fa8b Mon Sep 17 00:00:00 2001 From: Chris Povirk Date: Fri, 4 Oct 2024 09:30:09 -0400 Subject: [PATCH 1/3] Annotate `Gatherer` APIs. --- .../classes/java/util/stream/Gatherer.java | 40 ++++++++++--------- .../classes/java/util/stream/Gatherers.java | 14 ++++--- .../classes/java/util/stream/Stream.java | 2 +- 3 files changed, 32 insertions(+), 24 deletions(-) diff --git a/src/java.base/share/classes/java/util/stream/Gatherer.java b/src/java.base/share/classes/java/util/stream/Gatherer.java index 40c3c682e73..d8492306b6f 100644 --- a/src/java.base/share/classes/java/util/stream/Gatherer.java +++ b/src/java.base/share/classes/java/util/stream/Gatherer.java @@ -24,6 +24,9 @@ */ package java.util.stream; +import org.jspecify.annotations.NullMarked; +import org.jspecify.annotations.Nullable; + import jdk.internal.javac.PreviewFeature; import jdk.internal.vm.annotation.ForceInline; @@ -197,8 +200,9 @@ * @param the type of output elements from the gatherer operation * @since 22 */ +@NullMarked @PreviewFeature(feature = PreviewFeature.Feature.STREAM_GATHERERS) -public interface Gatherer { +public interface Gatherer { /** * A function that produces an instance of the intermediate state used for * this gathering operation. @@ -328,8 +332,8 @@ static BiConsumer> defaultFinisher() { * @throws NullPointerException if the argument is {@code null} * @return the new {@code Gatherer} */ - static Gatherer ofSequential( - Integrator integrator) { + static Gatherer ofSequential( + Integrator<@Nullable Void, T, R> integrator) { return of( defaultInitializer(), integrator, @@ -349,9 +353,9 @@ static Gatherer ofSequential( * @throws NullPointerException if any argument is {@code null} * @return the new {@code Gatherer} */ - static Gatherer ofSequential( - Integrator integrator, - BiConsumer> finisher) { + static Gatherer ofSequential( + Integrator<@Nullable Void, T, R> integrator, + BiConsumer<@Nullable Void, Downstream> finisher) { return of( defaultInitializer(), integrator, @@ -372,7 +376,7 @@ static Gatherer ofSequential( * @throws NullPointerException if any argument is {@code null} * @return the new {@code Gatherer} */ - static Gatherer ofSequential( + static Gatherer ofSequential( Supplier initializer, Integrator integrator) { return of( @@ -396,7 +400,7 @@ static Gatherer ofSequential( * @throws NullPointerException if any argument is {@code null} * @return the new {@code Gatherer} */ - static Gatherer ofSequential( + static Gatherer ofSequential( Supplier initializer, Integrator integrator, BiConsumer> finisher) { @@ -418,7 +422,7 @@ static Gatherer ofSequential( * @throws NullPointerException if any argument is {@code null} * @return the new {@code Gatherer} */ - static Gatherer of(Integrator integrator) { + static Gatherer of(Integrator<@Nullable Void, T, R> integrator) { return of( defaultInitializer(), integrator, @@ -438,9 +442,9 @@ static Gatherer of(Integrator integrator) { * @throws NullPointerException if any argument is {@code null} * @return the new {@code Gatherer} */ - static Gatherer of( - Integrator integrator, - BiConsumer> finisher) { + static Gatherer of( + Integrator<@Nullable Void, T, R> integrator, + BiConsumer<@Nullable Void, Downstream> finisher) { return of( defaultInitializer(), integrator, @@ -464,7 +468,7 @@ static Gatherer of( * @throws NullPointerException if any argument is {@code null} * @return the new {@code Gatherer} */ - static Gatherer of( + static Gatherer of( Supplier initializer, Integrator integrator, BinaryOperator combiner, @@ -485,7 +489,7 @@ static Gatherer of( */ @FunctionalInterface @PreviewFeature(feature = PreviewFeature.Feature.STREAM_GATHERERS) - interface Downstream { + interface Downstream { /** * Pushes, if possible, the provided element downstream -- to the next @@ -528,7 +532,7 @@ interface Downstream { */ @FunctionalInterface @PreviewFeature(feature = PreviewFeature.Feature.STREAM_GATHERERS) - interface Integrator { + interface Integrator { /** * Performs an action given: the current state, the next element, and * a downstream object; potentially inspecting and/or updating @@ -554,7 +558,7 @@ interface Integrator { * @param the type of results this integrator can produce */ @ForceInline - static Integrator of(Integrator integrator) { + static Integrator of(Integrator integrator) { return integrator; } @@ -569,7 +573,7 @@ static Integrator of(Integrator integrator) { * @param the type of results this integrator can produce */ @ForceInline - static Greedy ofGreedy(Greedy greedy) { + static Greedy ofGreedy(Greedy greedy) { return greedy; } @@ -588,6 +592,6 @@ static Greedy ofGreedy(Greedy greedy) { */ @FunctionalInterface @PreviewFeature(feature = PreviewFeature.Feature.STREAM_GATHERERS) - interface Greedy extends Integrator { } + interface Greedy extends Integrator { } } } diff --git a/src/java.base/share/classes/java/util/stream/Gatherers.java b/src/java.base/share/classes/java/util/stream/Gatherers.java index c201ee54609..8a0681ec0c5 100644 --- a/src/java.base/share/classes/java/util/stream/Gatherers.java +++ b/src/java.base/share/classes/java/util/stream/Gatherers.java @@ -24,6 +24,9 @@ */ package java.util.stream; +import org.jspecify.annotations.NullMarked; +import org.jspecify.annotations.Nullable; + import jdk.internal.access.SharedSecrets; import jdk.internal.javac.PreviewFeature; import jdk.internal.vm.annotation.ForceInline; @@ -50,6 +53,7 @@ * * @since 22 */ +@NullMarked @PreviewFeature(feature = PreviewFeature.Feature.STREAM_GATHERERS) public final class Gatherers { private Gatherers() { } // This class is not intended to be instantiated @@ -85,7 +89,7 @@ private Gatherers() { } // This class is not intended to be instantiated * @return a new gatherer which groups elements into fixed-size windows * @throws IllegalArgumentException when {@code windowSize} is less than 1 */ - public static Gatherer> windowFixed(int windowSize) { + public static Gatherer> windowFixed(int windowSize) { if (windowSize < 1) throw new IllegalArgumentException("'windowSize' must be greater than zero"); @@ -174,7 +178,7 @@ void finish(Downstream> downstream) { * @return a new gatherer which groups elements into sliding windows * @throws IllegalArgumentException when windowSize is less than 1 */ - public static Gatherer> windowSliding(int windowSize) { + public static Gatherer> windowSliding(int windowSize) { if (windowSize < 1) throw new IllegalArgumentException("'windowSize' must be greater than zero"); @@ -261,7 +265,7 @@ void finish(Downstream> downstream) { * @return a new Gatherer * @throws NullPointerException if any of the parameters are {@code null} */ - public static Gatherer fold( + public static Gatherer fold( Supplier initial, BiFunction folder) { Objects.requireNonNull(initial, "'initial' must not be null"); @@ -308,7 +312,7 @@ class State { * @return a new Gatherer which performs a prefix scan * @throws NullPointerException if any of the parameters are {@code null} */ - public static Gatherer scan( + public static Gatherer scan( Supplier initial, BiFunction scanner) { Objects.requireNonNull(initial, "'initial' must not be null"); @@ -348,7 +352,7 @@ boolean integrate(T element, Downstream downstream) { * @throws IllegalArgumentException if {@code maxConcurrency} is less than 1 * @throws NullPointerException if {@code mapper} is {@code null} */ - public static Gatherer mapConcurrent( + public static Gatherer mapConcurrent( final int maxConcurrency, final Function mapper) { if (maxConcurrency < 1) diff --git a/src/java.base/share/classes/java/util/stream/Stream.java b/src/java.base/share/classes/java/util/stream/Stream.java index 70e7539ba2a..ae352c8b6ac 100644 --- a/src/java.base/share/classes/java/util/stream/Stream.java +++ b/src/java.base/share/classes/java/util/stream/Stream.java @@ -1105,7 +1105,7 @@ default Stream dropWhile(Predicate predicate) { * @since 22 */ @PreviewFeature(feature = PreviewFeature.Feature.STREAM_GATHERERS) - default Stream gather(Gatherer gatherer) { + default Stream gather(Gatherer gatherer) { return StreamSupport.stream(spliterator(), isParallel()) .gather(gatherer) .onClose(this::close); From 98d5c8652b814f16e8a1b075355adb86e075ef66 Mon Sep 17 00:00:00 2001 From: Chris Povirk Date: Mon, 7 Oct 2024 12:37:23 -0400 Subject: [PATCH 2/3] Permit a nullable type argument for the parameter of `andThen`. --- src/java.base/share/classes/java/util/stream/Gatherer.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/java.base/share/classes/java/util/stream/Gatherer.java b/src/java.base/share/classes/java/util/stream/Gatherer.java index d8492306b6f..7de107d9d22 100644 --- a/src/java.base/share/classes/java/util/stream/Gatherer.java +++ b/src/java.base/share/classes/java/util/stream/Gatherer.java @@ -271,7 +271,7 @@ default BiConsumer> finisher() { * @return returns a composed Gatherer which connects the output of this * Gatherer as input that Gatherer */ - default Gatherer andThen(Gatherer that) { + default Gatherer andThen(Gatherer that) { Objects.requireNonNull(that); return Gatherers.Composite.of(this, that); } From d4eb45206923a6f4515244c53f5f5d64f2ab7633 Mon Sep 17 00:00:00 2001 From: Chris Povirk Date: Mon, 7 Oct 2024 12:40:27 -0400 Subject: [PATCH 3/3] Annotate `Gatherer.default*`. --- src/java.base/share/classes/java/util/stream/Gatherer.java | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/java.base/share/classes/java/util/stream/Gatherer.java b/src/java.base/share/classes/java/util/stream/Gatherer.java index 7de107d9d22..1229f4aacad 100644 --- a/src/java.base/share/classes/java/util/stream/Gatherer.java +++ b/src/java.base/share/classes/java/util/stream/Gatherer.java @@ -286,7 +286,7 @@ default BiConsumer> finisher() { * @return the instance of the default initializer * @param the type of the state of the returned initializer */ - static Supplier defaultInitializer() { + static Supplier<@Nullable A> defaultInitializer() { return Gatherers.Value.DEFAULT.initializer(); } @@ -301,7 +301,7 @@ static Supplier defaultInitializer() { * @return the instance of the default combiner * @param the type of the state of the returned combiner */ - static BinaryOperator defaultCombiner() { + static BinaryOperator defaultCombiner() { return Gatherers.Value.DEFAULT.combiner(); } @@ -318,7 +318,7 @@ static BinaryOperator defaultCombiner() { * @param the type of the state of the returned finisher * @param the type of the Downstream of the returned finisher */ - static BiConsumer> defaultFinisher() { + static BiConsumer> defaultFinisher() { return Gatherers.Value.DEFAULT.finisher(); }