From a61e00fc62e9b57c4fb6db8cb6c2592a0dde9f89 Mon Sep 17 00:00:00 2001 From: Daniel Kec Date: Thu, 13 Jan 2022 11:36:43 +0100 Subject: [PATCH] Jakarta EE 9.1 Alignment (#171) * Jakarta EE 9.1 Alignment #169 --- api/package-lock.json | 84 ++--- api/pom.xml | 139 +------ .../streams/operators/CompletionRunner.java | 11 +- .../operators/CompletionSubscriber.java | 38 +- .../operators/ConnectingOperators.java | 70 ++-- .../streams/operators/ConsumingOperators.java | 68 ++-- .../operators/ErrorHandlingOperators.java | 74 ++-- .../streams/operators/FilteringOperators.java | 46 ++- .../streams/operators/PeekingOperators.java | 53 +-- .../streams/operators/ProcessorBuilder.java | 55 ++- .../streams/operators/ProducesResult.java | 5 +- .../streams/operators/PublisherBuilder.java | 62 +++- .../streams/operators/ReactiveStreams.java | 172 +++++---- .../operators/ReactiveStreamsFactory.java | 164 +++++---- .../streams/operators/SubscriberBuilder.java | 22 +- .../operators/TransformingOperators.java | 63 ++-- .../streams/operators/package-info.java | 26 +- .../reactive/streams/operators/spi/Graph.java | 6 +- .../operators/spi/ReactiveStreamsEngine.java | 55 +-- .../spi/ReactiveStreamsFactoryResolver.java | 40 +- .../reactive/streams/operators/spi/Stage.java | 205 +++++------ .../spi/SubscriberWithCompletionStage.java | 11 +- .../streams/operators/spi/package-info.java | 10 +- .../main/javadoc/licenses/Draft/license.html | 27 -- .../main/javadoc/licenses/Final/license.html | 72 ---- api/src/main/resources/META-INF/NOTICE | 19 + core/pom.xml | 94 +---- .../operators/core/CompletionRunnerImpl.java | 8 +- .../streams/operators/core/GraphImpl.java | 13 +- .../operators/core/InternalStages.java | 22 +- .../operators/core/ProcessorBuilderImpl.java | 44 ++- .../operators/core/PublisherBuilderImpl.java | 46 +-- .../core/ReactiveStreamsEngineResolver.java | 40 +- .../core/ReactiveStreamsFactoryImpl.java | 33 +- .../core/ReactiveStreamsGraphBuilder.java | 23 +- .../streams/operators/core/Reductions.java | 47 ++- .../streams/operators/core/Stages.java | 17 +- .../operators/core/SubscriberBuilderImpl.java | 9 +- .../streams/operators/core/package-info.java | 20 +- mp_checkstyle_rules.xml | 93 ----- pom.xml | 302 +-------------- spec/pom.xml | 97 +---- spec/src/main/asciidoc/release_notes.asciidoc | 8 +- .../src/main/resources/META-INF}/LICENSE | 0 spec/src/main/resources/META-INF/NOTICE | 19 + tck/pom.xml | 104 +----- .../tck/DefaultReactiveStreamsFactory.java | 13 +- .../operators/tck/ReactiveStreamsTck.java | 28 +- ...bstractReactiveStreamsApiVerification.java | 12 +- .../tck/api/CompletionRunnerVerification.java | 25 +- .../api/CompletionSubscriberVerification.java | 18 +- .../streams/operators/tck/api/Mocks.java | 87 +++-- .../tck/api/ProcessorBuilderVerification.java | 72 ++-- .../tck/api/PublisherBuilderVerification.java | 77 ++-- .../api/ReactiveStreamsApiVerification.java | 19 +- .../tck/api/ReactiveStreamsVerification.java | 22 +- .../api/SubscriberBuilderVerification.java | 20 +- .../ReactiveStreamsArquillianTck.java | 54 +-- .../tck/arquillian/ReactiveStreamsCdiTck.java | 8 +- .../tck/spi/AbstractStageVerification.java | 35 +- .../tck/spi/CancelStageVerification.java | 20 +- .../tck/spi/CollectStageVerification.java | 94 +++-- .../tck/spi/ConcatStageVerification.java | 139 ++++--- .../tck/spi/CoupledStageVerification.java | 106 +++--- .../tck/spi/DistinctStageVerification.java | 42 +-- .../tck/spi/DropWhileStageVerification.java | 104 +++--- .../tck/spi/EmptyProcessorVerification.java | 7 +- .../tck/spi/FilterStageVerification.java | 45 ++- .../tck/spi/FindFirstStageVerification.java | 21 +- .../FlatMapCompletionStageVerification.java | 81 ++-- .../spi/FlatMapIterableStageVerification.java | 121 +++--- .../tck/spi/FlatMapStageVerification.java | 149 ++++---- ...omCompletionStageNullableVerification.java | 53 ++- .../spi/FromCompletionStageVerification.java | 55 ++- .../tck/spi/LimitStageVerification.java | 118 +++--- .../tck/spi/MapStageVerification.java | 46 ++- .../tck/spi/OfStageVerification.java | 57 ++- .../spi/OnErrorResumeStageVerification.java | 348 +++++++++--------- .../tck/spi/OnStagesVerification.java | 155 ++++---- .../tck/spi/PeekStageVerification.java | 54 +-- .../spi/ReactiveStreamsSpiVerification.java | 59 ++- .../operators/tck/spi/ScheduledPublisher.java | 16 +- .../tck/spi/SkipStageVerification.java | 30 +- .../tck/spi/SubscriberStageVerification.java | 18 +- .../tck/spi/TakeWhileStageVerification.java | 78 ++-- tck/src/main/licenses/Final/LICENSE.md | 83 ----- tck/src/main/resources/META-INF/LICENSE | 201 ++++++++++ tck/src/main/resources/META-INF/NOTICE | 19 + tck/src/main/resources/META-INF/tck | 0 89 files changed, 2427 insertions(+), 3018 deletions(-) delete mode 100644 api/src/main/javadoc/licenses/Draft/license.html delete mode 100644 api/src/main/javadoc/licenses/Final/license.html create mode 100644 api/src/main/resources/META-INF/NOTICE delete mode 100644 mp_checkstyle_rules.xml rename {tck/src/main/licenses/Draft => spec/src/main/resources/META-INF}/LICENSE (100%) create mode 100644 spec/src/main/resources/META-INF/NOTICE delete mode 100644 tck/src/main/licenses/Final/LICENSE.md create mode 100644 tck/src/main/resources/META-INF/LICENSE create mode 100644 tck/src/main/resources/META-INF/NOTICE create mode 100644 tck/src/main/resources/META-INF/tck diff --git a/api/package-lock.json b/api/package-lock.json index b8d5ceb..0e11aee 100644 --- a/api/package-lock.json +++ b/api/package-lock.json @@ -10,7 +10,7 @@ "integrity": "sha512-salcGninV0nPrwpGNn4VTXBb1SOuXQBiqbrNXoeizJsHrsL6ERFM2Ne3JUSBWRE6aeNJI2ROP/WEEIDUiDe3cg==", "dev": true, "requires": { - "es6-promisify": "^5.0.0" + "es6-promisify": "5.0.0" } }, "async-limiter": { @@ -59,10 +59,10 @@ "integrity": "sha512-27HBghJxjiZtIk3Ycvn/4kbJk/1uZuJFfuPEns6LaEvpvG1f0hTea8lilrouyo9mVc2GWdcEZ8OLoGmSADlrCw==", "dev": true, "requires": { - "buffer-from": "^1.0.0", - "inherits": "^2.0.3", - "readable-stream": "^2.2.2", - "typedarray": "^0.0.6" + "buffer-from": "1.1.1", + "inherits": "2.0.3", + "readable-stream": "2.3.7", + "typedarray": "0.0.6" } }, "core-util-is": { @@ -77,7 +77,7 @@ "integrity": "sha512-pYAIzeRo8J6KPEaJ0VWOh5Pzkbw/RetuzehGM7QRRX5he4fPHx2rdKMB256ehJCkX+XRQm16eZLqLNS8RSZXZw==", "dev": true, "requires": { - "ms": "^2.1.1" + "ms": "2.1.2" } }, "es6-promise": { @@ -92,7 +92,7 @@ "integrity": "sha1-UQnWLz5W6pZ8S2NQWu8IKRyKUgM=", "dev": true, "requires": { - "es6-promise": "^4.0.3" + "es6-promise": "4.2.8" } }, "extract-zip": { @@ -101,10 +101,10 @@ "integrity": "sha512-xoh5G1W/PB0/27lXgMQyIhP5DSY/LhoCsOyZgb+6iMmRtCwVBo55uKaMoEYrDCKQhWvqEip5ZPKAc6eFNyf/MA==", "dev": true, "requires": { - "concat-stream": "^1.6.2", - "debug": "^2.6.9", - "mkdirp": "^0.5.4", - "yauzl": "^2.10.0" + "concat-stream": "1.6.2", + "debug": "2.6.9", + "mkdirp": "0.5.5", + "yauzl": "2.10.0" }, "dependencies": { "debug": { @@ -130,7 +130,7 @@ "integrity": "sha1-JcfInLH5B3+IkbvmHY85Dq4lbx4=", "dev": true, "requires": { - "pend": "~1.2.0" + "pend": "1.2.0" } }, "fs.realpath": { @@ -159,8 +159,8 @@ "integrity": "sha512-OmvfoQ53WLjtA9HeYP9RNrWMJzzAz1JGaSFr1nijg0PVR1JaD/xbJq1mdEIIlxGpXp9eSe/O2LgU9DJmTPd0Eg==", "dev": true, "requires": { - "agent-base": "^4.3.0", - "debug": "^3.1.0" + "agent-base": "4.3.0", + "debug": "3.2.6" }, "dependencies": { "debug": { @@ -169,7 +169,7 @@ "integrity": "sha512-mel+jf7nrtEl5Pn1Qx46zARXKDpBbvzezse7p7LqINmdoIk8PYP5SySaxEmYv6TZ0JyEKA1hsCId6DIhgITtWQ==", "dev": true, "requires": { - "ms": "^2.1.1" + "ms": "2.1.2" } } } @@ -229,7 +229,7 @@ "integrity": "sha512-NKmAlESf6jMGym1++R0Ra7wvhV+wFW63FaSOFPwRahvea0gMUcGUhVeAg/0BC0wiv9ih5NYPB1Wn1UEI1/L+xQ==", "dev": true, "requires": { - "minimist": "^1.2.5" + "minimist": "1.2.5" } }, "ms": { @@ -289,14 +289,14 @@ "integrity": "sha512-LUXgvhjfB/P6IOUDAKxOcbCz9ISwBLL9UpKghYrcBDwrOGx1m60y0iN2M64mdAUbT4+7oZM5DTxOW7equa2fxQ==", "dev": true, "requires": { - "debug": "^4.1.0", - "extract-zip": "^1.6.6", - "https-proxy-agent": "^2.2.1", - "mime": "^2.0.3", - "progress": "^2.0.1", - "proxy-from-env": "^1.0.0", - "rimraf": "^2.6.1", - "ws": "^6.1.0" + "debug": "4.1.1", + "extract-zip": "1.7.0", + "https-proxy-agent": "2.2.4", + "mime": "2.4.6", + "progress": "2.0.3", + "proxy-from-env": "1.1.0", + "rimraf": "2.7.1", + "ws": "6.2.1" } }, "readable-stream": { @@ -305,13 +305,13 @@ "integrity": "sha512-Ebho8K4jIbHAxnuxi7o42OrZgF/ZTNcsZj6nRKyUmkhLFq8CHItp/fy6hQZuZmP/n3yZ9VBUbp4zz/mX8hmYPw==", "dev": true, "requires": { - "core-util-is": "~1.0.0", - "inherits": "~2.0.3", - "isarray": "~1.0.0", - "process-nextick-args": "~2.0.0", - "safe-buffer": "~5.1.1", - "string_decoder": "~1.1.1", - "util-deprecate": "~1.0.1" + "core-util-is": "1.0.2", + "inherits": "2.0.3", + "isarray": "1.0.0", + "process-nextick-args": "2.0.1", + "safe-buffer": "5.1.2", + "string_decoder": "1.1.1", + "util-deprecate": "1.0.2" } }, "rechoir": { @@ -338,7 +338,7 @@ "integrity": "sha512-uWjbaKIK3T1OSVptzX7Nl6PvQ3qAGtKEtVRjRuazjfL3Bx5eI409VZSqgND+4UNnmzLVdPj9FqFJNPqBZFve4w==", "dev": true, "requires": { - "glob": "^7.1.3" + "glob": "7.1.6" }, "dependencies": { "glob": { @@ -347,12 +347,12 @@ "integrity": "sha512-LwaxwyZ72Lk7vZINtNNrywX0ZuLyStrdDtabefZKAY5ZGJhVtgdznluResxNmPitE0SAO+O26sWTHeKSI2wMBA==", "dev": true, "requires": { - "fs.realpath": "^1.0.0", - "inflight": "^1.0.4", - "inherits": "2", - "minimatch": "^3.0.4", - "once": "^1.3.0", - "path-is-absolute": "^1.0.0" + "fs.realpath": "1.0.0", + "inflight": "1.0.6", + "inherits": "2.0.3", + "minimatch": "3.0.4", + "once": "1.4.0", + "path-is-absolute": "1.0.1" } } } @@ -380,7 +380,7 @@ "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==", "dev": true, "requires": { - "safe-buffer": "~5.1.0" + "safe-buffer": "5.1.2" } }, "svg.js": { @@ -412,7 +412,7 @@ "integrity": "sha512-GIyAXC2cB7LjvpgMt9EKS2ldqr0MTrORaleiOno6TweZ6r3TKtoFQWay/2PceJ3RuBasOHzXNn5Lrw1X0bEjqA==", "dev": true, "requires": { - "async-limiter": "~1.0.0" + "async-limiter": "1.0.1" } }, "yauzl": { @@ -421,8 +421,8 @@ "integrity": "sha1-x+sXyT4RLLEIb6bY5R+wZnt5pfk=", "dev": true, "requires": { - "buffer-crc32": "~0.2.3", - "fd-slicer": "~1.1.0" + "buffer-crc32": "0.2.13", + "fd-slicer": "1.1.0" } } } diff --git a/api/pom.xml b/api/pom.xml index 4a305bc..5ef7865 100644 --- a/api/pom.xml +++ b/api/pom.xml @@ -1,6 +1,6 @@ org.eclipse.microprofile.reactive-streams-operators microprofile-reactive-streams-operators-parent - 2.1-SNAPSHOT + 3.0-SNAPSHOT + 1.6 false + microprofile-reactive-streams-operators-api Eclipse MicroProfile Reactive Streams Operators API Eclipse MicroProfile Reactive Streams Operators :: API + org.reactivestreams @@ -46,121 +49,10 @@ - - maven-resources-plugin - 3.2.0 - - - copy-resources - validate - - copy-resources - - - ${basedir}/target/apidocs/doc-files/ - true - - - src/main/javadoc/licenses/${revremark}/ - true - - - - - - - - org.apache.maven.plugins - maven-javadoc-plugin - - 8 - false - ${javadoc.options} - true - true - none - ${project.name} - ${project.name} -
${project.name} v${project.version}]]>
- - - Use is subject to license terms. - ]]> - - - - implSpec - a - Implementation Specification: - - - - - - attach-javadocs - - jar - - - - - - org.apache.maven.plugins - maven-source-plugin - - - attach-sources - - jar - - - - - - biz.aQute.bnd - bnd-maven-plugin - 4.2.0 - - - - - bnd-process - - - - - - org.apache.maven.plugins - maven-jar-plugin - - - ${project.build.outputDirectory}/META-INF/MANIFEST.MF - - - - - biz.aQute.bnd - bnd-baseline-maven-plugin - 4.2.0 - - - 1.0.1 - - - - - baseline - - baseline - - - - com.github.eirslett frontend-maven-plugin + ${frontend-maven-plugin.version} v8.11.3 @@ -198,6 +90,7 @@ com.github.eirslett frontend-maven-plugin + ${frontend-maven-plugin.version} generate-marble-diagrams @@ -214,24 +107,6 @@ - - eclipse-jarsigner - - - - org.eclipse.cbi.maven.plugins - eclipse-jarsigner-plugin - - - - sign - - - - - - - diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/CompletionRunner.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/CompletionRunner.java index b072a64..15de9e4 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/CompletionRunner.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/CompletionRunner.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,11 +19,10 @@ package org.eclipse.microprofile.reactive.streams.operators; +import java.util.concurrent.CompletionStage; import org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine; -import java.util.concurrent.CompletionStage; - /** * A builder for a closed reactive streams graph. *

@@ -31,7 +30,8 @@ * subscriber of the stream when the stream completes normally, or will be redeemed with an error if the stream * encounters an error. * - * @param The result of the stream. + * @param + * The result of the stream. * @see ReactiveStreams */ public interface CompletionRunner extends ProducesResult { @@ -45,7 +45,8 @@ public interface CompletionRunner extends ProducesResult { /** * Run this stream, using the supplied {@code ReactiveStreamsEngine}. * - * @param engine The engine to run the stream with. + * @param engine + * The engine to run the stream with. * @return A completion stage that will be redeemed with the result of the stream, or an error if the stream fails. */ CompletionStage run(ReactiveStreamsEngine engine); diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/CompletionSubscriber.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/CompletionSubscriber.java index eeeb4b1..07776e9 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/CompletionSubscriber.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/CompletionSubscriber.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018, 2020 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,22 +19,24 @@ package org.eclipse.microprofile.reactive.streams.operators; -import org.reactivestreams.Subscriber; -import org.reactivestreams.Subscription; - import java.util.Objects; import java.util.concurrent.CompletionStage; +import org.reactivestreams.Subscriber; +import org.reactivestreams.Subscription; + /** * A subscriber that redeems a completion stage when it completes. *

- * The result is provided through a {@link CompletionStage}, which is redeemed when the subscriber receives a - * completion or error signal, or otherwise cancels the stream. + * The result is provided through a {@link CompletionStage}, which is redeemed when the subscriber receives a completion + * or error signal, or otherwise cancels the stream. *

* The best way to instantiate one of these is using the {@link CompletionSubscriber#of} factory method. * - * @param The type of the elements that the subscriber consumes. - * @param The type of the result that the subscriber emits. + * @param + * The type of the elements that the subscriber consumes. + * @param + * The type of the result that the subscriber emits. */ public interface CompletionSubscriber extends Subscriber { @@ -50,17 +52,19 @@ public interface CompletionSubscriber extends Subscriber { CompletionStage getCompletion(); /** - * Create a {@link CompletionSubscriber} by combining the given subscriber and completion stage. - * The objects passed to this method should not be associated with more than one stream instance. + * Create a {@link CompletionSubscriber} by combining the given subscriber and completion stage. The objects passed + * to this method should not be associated with more than one stream instance. *

- * The returned {@code CompletionSubscriber} will delegate calls from the {@code Subscriber} - * interface to {@code subscriber} and will return {@code completion} from {@link #getCompletion()}. + * The returned {@code CompletionSubscriber} will delegate calls from the {@code Subscriber} interface to + * {@code subscriber} and will return {@code completion} from {@link #getCompletion()}. *

- * It is the callers responsibility to ensure that {@code completion} is completed with the correct - * value when {@code subscriber} terminates. + * It is the callers responsibility to ensure that {@code completion} is completed with the correct value when + * {@code subscriber} terminates. * - * @param subscriber The subscriber. - * @param completion The completion stage. + * @param subscriber + * The subscriber. + * @param completion + * The completion stage. * @return A completion subscriber. */ static CompletionSubscriber of(Subscriber subscriber, CompletionStage completion) { @@ -116,7 +120,7 @@ public boolean equals(Object o) { } DefaultCompletionSubscriber that = (DefaultCompletionSubscriber) o; return Objects.equals(subscriber, that.subscriber) && - Objects.equals(completion, that.completion); + Objects.equals(completion, that.completion); } @Override diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ConnectingOperators.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ConnectingOperators.java index 4bceed8..477fc21 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ConnectingOperators.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ConnectingOperators.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -26,61 +26,61 @@ /** * Operators for connecting different graphs together. * - * @param The type of the elements that the stream emits. + * @param + * The type of the elements that the stream emits. */ public interface ConnectingOperators { /** - * Connect the outlet of the {@link Publisher} built by this builder to the given {@link Subscriber}. - * The Reactive Streams specification states that a subscriber should cancel - * any new stream subscription it receives if it already has an active subscription. - * The returned result of this method is a stream that creates a subscription for the - * subscriber passed in, so the resulting stream should only be run once. - * For the same reason, the subscriber passed in should not have any active subscriptions - * and should not be used in more than one call to this method. + * Connect the outlet of the {@link Publisher} built by this builder to the given {@link Subscriber}. The Reactive + * Streams specification states that a subscriber should cancel any new stream subscription it receives if it + * already has an active subscription. The returned result of this method is a stream that creates a subscription + * for the subscriber passed in, so the resulting stream should only be run once. For the same reason, the + * subscriber passed in should not have any active subscriptions and should not be used in more than one call to + * this method. * - * @param subscriber The subscriber to connect. + * @param subscriber + * The subscriber to connect. * @return A completion builder that completes when the stream completes. */ ProducesResult to(Subscriber subscriber); /** - * Connect the outlet of this stream to the given {@link SubscriberBuilder} graph. - * The Reactive Streams specification states that a subscriber should cancel - * any new stream subscription it receives if it already has an active subscription. - * For this reason, a subscriber builder, particularly any that represents a graph that - * includes a user supplied {@link Subscriber} or {@link Processor} stage, should not be - * used in the creation of more than one stream instance. + * Connect the outlet of this stream to the given {@link SubscriberBuilder} graph. The Reactive Streams + * specification states that a subscriber should cancel any new stream subscription it receives if it already has an + * active subscription. For this reason, a subscriber builder, particularly any that represents a graph that + * includes a user supplied {@link Subscriber} or {@link Processor} stage, should not be used in the creation of + * more than one stream instance. * - * @param subscriberBuilder The subscriber builder to connect. + * @param subscriberBuilder + * The subscriber builder to connect. * @return A completion builder that completes when the stream completes. */ - ProducesResult to(SubscriberBuilder subscriberBuilder ); + ProducesResult to(SubscriberBuilder subscriberBuilder); /** - * Connect the outlet of the {@link Publisher} built by this builder to the given {@link ProcessorBuilder}. - * The Reactive Streams specification states that a subscribing processor should cancel - * any new stream subscription it receives if it already has an active subscription. - * For this reason, a processor builder, particularly any that represents a graph that - * includes a user supplied {@link Processor} stage, should not be - * used in the creation of more than one stream instance. + * Connect the outlet of the {@link Publisher} built by this builder to the given {@link ProcessorBuilder}. The + * Reactive Streams specification states that a subscribing processor should cancel any new stream subscription it + * receives if it already has an active subscription. For this reason, a processor builder, particularly any that + * represents a graph that includes a user supplied {@link Processor} stage, should not be used in the creation of + * more than one stream instance. * - * @param processorBuilder The processor builder to connect. + * @param processorBuilder + * The processor builder to connect. * @return A stream builder that represents the passed in processor's outlet. */ - ConnectingOperators via(ProcessorBuilder processorBuilder ); + ConnectingOperators via(ProcessorBuilder processorBuilder); /** - * Connect the outlet of this stream to the given {@link Processor}. - * The Reactive Streams specification states that a subscribing processor should cancel - * any new stream subscription it receives if it already has an active subscription. - * The returned result of this method is a stream that creates a subscription for the - * processor passed in, so the resulting stream should only be run once. - * For the same reason, the processor passed in should not have any active subscriptions - * and should not be used in more than one call to this method. - + * Connect the outlet of this stream to the given {@link Processor}. The Reactive Streams specification states that + * a subscribing processor should cancel any new stream subscription it receives if it already has an active + * subscription. The returned result of this method is a stream that creates a subscription for the processor passed + * in, so the resulting stream should only be run once. For the same reason, the processor passed in should not have + * any active subscriptions and should not be used in more than one call to this method. * - * @param processor The processor builder to connect. + * + * @param processor + * The processor builder to connect. * @return A stream builder that represents the passed in processor builder's outlet. */ ConnectingOperators via(Processor processor); diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ConsumingOperators.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ConsumingOperators.java index 4de1ec6..1121261 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ConsumingOperators.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ConsumingOperators.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,8 +19,6 @@ package org.eclipse.microprofile.reactive.streams.operators; -import org.reactivestreams.Publisher; - import java.util.List; import java.util.Optional; import java.util.concurrent.CompletionStage; @@ -30,19 +28,22 @@ import java.util.function.Supplier; import java.util.stream.Collector; +import org.reactivestreams.Publisher; + /** * Operators for completing a stream. *

* The documentation for each operator uses marble diagrams to visualize how the operator functions. Each element - * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator - * applying some transformation or having some side effect, termination and error signals potentially being passed, and - * for operators that subscribe to the stream, an output value being redeemed at the end. + * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator applying + * some transformation or having some side effect, termination and error signals potentially being passed, and for + * operators that subscribe to the stream, an output value being redeemed at the end. *

* Below is an example diagram labelling all the parts of the stream. *

* Example marble diagram * - * @param The type of the elements that the stream emits. + * @param + * The type of the elements that the stream emits. */ public interface ConsumingOperators { @@ -51,10 +52,12 @@ public interface ConsumingOperators { *

* forEach marble diagram *

- * The returned {@link CompletionStage} will be redeemed when the stream completes, either successfully if the stream - * completes normally, or with an error if the stream completes with an error or if the action throws an exception. + * The returned {@link CompletionStage} will be redeemed when the stream completes, either successfully if the + * stream completes normally, or with an error if the stream completes with an error or if the action throws an + * exception. * - * @param action The action. + * @param action + * The action. * @return A new completion runner. */ ProducesResult forEach(Consumer action); @@ -89,8 +92,10 @@ public interface ConsumingOperators { *

* The result of the reduction is returned in the {@link CompletionStage}. * - * @param identity The identity value. - * @param accumulator The accumulator function. + * @param identity + * The identity value. + * @param accumulator + * The accumulator function. * @return A completion builder for the reduction. */ ProducesResult reduce(T identity, BinaryOperator accumulator); @@ -100,18 +105,17 @@ public interface ConsumingOperators { *

* reduce marble diagram *

- * The result of the reduction is returned as an {@code Optional} - * in the {@link CompletionStage}. If there are no elements in this stream, - * empty will be returned. + * The result of the reduction is returned as an {@code Optional} in the {@link CompletionStage}. If there are no + * elements in this stream, empty will be returned. * - * @param accumulator The accumulator function. + * @param accumulator + * The accumulator function. * @return A completion builder for the reduction. */ ProducesResult> reduce(BinaryOperator accumulator); /** - * Find the first element emitted by the {@link Publisher}, and return it in a - * {@link CompletionStage}. + * Find the first element emitted by the {@link Publisher}, and return it in a {@link CompletionStage}. *

* findFirst marble diagram *

@@ -127,26 +131,32 @@ public interface ConsumingOperators { * Since Reactive Streams are intrinsically sequential, only the accumulator of the collector will be used, the * combiner will not be used. * - * @param collector The collector to collect the elements. - * @param The result of the collector. - * @param The accumulator type. + * @param collector + * The collector to collect the elements. + * @param + * The result of the collector. + * @param + * The accumulator type. * @return A completion builder that emits the collected result. */ ProducesResult collect(Collector collector); /** - * Collect the elements emitted by this stream using a {@link Collector} built from the given - * {@link Supplier supplier} and {@link BiConsumer accumulator}. + * Collect the elements emitted by this stream using a {@link Collector} built from the given {@link Supplier + * supplier} and {@link BiConsumer accumulator}. *

* collect marble diagram *

- * Since Reactive Streams are intrinsically sequential, the combiner will not be used. This is why this method does not - * accept a combiner method. + * Since Reactive Streams are intrinsically sequential, the combiner will not be used. This is why this method does + * not accept a combiner method. * - * @param supplier a function that creates a new result container. It creates objects of type {@code }. - * @param accumulator an associative, non-interfering, stateless function for incorporating an additional element into a - * result - * @param The result of the collector. + * @param supplier + * a function that creates a new result container. It creates objects of type {@code }. + * @param accumulator + * an associative, non-interfering, stateless function for incorporating an additional element into a + * result + * @param + * The result of the collector. * @return A completion builder that emits the collected result. */ ProducesResult collect(Supplier supplier, BiConsumer accumulator); diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ErrorHandlingOperators.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ErrorHandlingOperators.java index 704ee78..a71cd5d 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ErrorHandlingOperators.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ErrorHandlingOperators.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,25 +19,25 @@ package org.eclipse.microprofile.reactive.streams.operators; +import java.util.function.Function; + import org.reactivestreams.Publisher; import org.reactivestreams.Subscription; - -import java.util.function.Function; - /** * Operators for handling errors in streams. *

* The documentation for each operator uses marble diagrams to visualize how the operator functions. Each element - * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator - * applying some transformation or some side effect, termination and error signals potentially being passed, and - * for operators that subscribe to the stream, an output value being redeemed at the end. + * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator applying + * some transformation or some side effect, termination and error signals potentially being passed, and for operators + * that subscribe to the stream, an output value being redeemed at the end. *

* Below is an example diagram labelling all the parts of the stream. *

* Example marble diagram * - * @param The type of the elements that the stream emits. + * @param + * The type of the elements that the stream emits. * @see ReactiveStreams */ public interface ErrorHandlingOperators { @@ -49,14 +49,14 @@ public interface ErrorHandlingOperators { * onErrorResume marble diagram *

* By default, when a stream encounters an error that prevents it from emitting the expected item to its subscriber, - * the stream invokes its subscriber's onError method, and then terminates without invoking any more - * of its subscriber's methods. This operator changes this behavior. If the current stream encounters an error, - * instead of invoking its subscriber's onError method, it will instead emit the return value of the - * passed function. This operator prevents errors from propagating or to supply fallback data should errors be - * encountered. + * the stream invokes its subscriber's onError method, and then terminates without invoking any more of + * its subscriber's methods. This operator changes this behavior. If the current stream encounters an error, instead + * of invoking its subscriber's onError method, it will instead emit the return value of the passed + * function. This operator prevents errors from propagating or to supply fallback data should errors be encountered. * - * @param errorHandler the function returning the value that needs to be emitting instead of the error. - * The function must not return {@code null}. + * @param errorHandler + * the function returning the value that needs to be emitting instead of the error. The function must not + * return {@code null}. * @return The new stream builder. */ ErrorHandlingOperators onErrorResume(Function errorHandler); @@ -68,20 +68,21 @@ public interface ErrorHandlingOperators { * onErrorResumeWith marble diagram *

* By default, when a stream encounters an error that prevents it from emitting the expected item to its subscriber, - * the stream invokes its subscriber's onError method, and then terminates without invoking any more - * of its subscriber's methods. This operator changes this behavior. If the current stream encounters an error, - * instead of invoking its subscriber's onError method, it will instead relinquish control to the + * the stream invokes its subscriber's onError method, and then terminates without invoking any more of + * its subscriber's methods. This operator changes this behavior. If the current stream encounters an error, instead + * of invoking its subscriber's onError method, it will instead relinquish control to the * {@link PublisherBuilder} returned from the given function, which invokes the subscriber's onNext - * method if it is able to do so. The subscriber's original {@link Subscription} is used to - * control the flow of elements both before and after any error occurring. - * In such a case, because no publisher necessarily invokes onError on the stream's subscriber, - * it may never know that an error happened. + * method if it is able to do so. The subscriber's original {@link Subscription} is used to control the flow of + * elements both before and after any error occurring. In such a case, because no publisher necessarily invokes + * onError on the stream's subscriber, it may never know that an error happened. * - * @param errorHandler the function returning the stream that needs to be emitting instead of the error. - * The function must not return {@code null}. + * @param errorHandler + * the function returning the stream that needs to be emitting instead of the error. The function must + * not return {@code null}. * @return The new stream builder. */ - ErrorHandlingOperators onErrorResumeWith(Function> errorHandler); + ErrorHandlingOperators onErrorResumeWith( + Function> errorHandler); /** * Returns a stream containing all the elements from this stream. Additionally, in the case of failure, it invokes @@ -90,18 +91,19 @@ public interface ErrorHandlingOperators { * onErrorResumeWithRsPublisher marble diagram *

* By default, when a stream encounters an error that prevents it from emitting the expected item to its subscriber, - * the stream invokes its subscriber's onError method, and then terminates without invoking any more - * of its subscriber's methods. This operator changes this behavior. If the current stream encounters an error, - * instead of invoking its subscriber's onError method, the subscriber will be fed from the - * {@link Publisher} returned from the given function, and the subscriber's onNext - * method is called as the returned Publisher publishes. The subscriber's original {@link Subscription} is used to - * control the flow of both the original and the onError Publishers' elements. - * In such a case, because no publisher necessarily invokes onError, - * the subscriber may never know that an error happened. + * the stream invokes its subscriber's onError method, and then terminates without invoking any more of + * its subscriber's methods. This operator changes this behavior. If the current stream encounters an error, instead + * of invoking its subscriber's onError method, the subscriber will be fed from the {@link Publisher} + * returned from the given function, and the subscriber's onNext method is called as the returned + * Publisher publishes. The subscriber's original {@link Subscription} is used to control the flow of both the + * original and the onError Publishers' elements. In such a case, because no publisher necessarily invokes + * onError, the subscriber may never know that an error happened. * - * @param errorHandler the function returning the stream that need to be emitting instead of the error. - * The function must not return {@code null}. + * @param errorHandler + * the function returning the stream that need to be emitting instead of the error. The function must not + * return {@code null}. * @return The new stream builder. */ - ErrorHandlingOperators onErrorResumeWithRsPublisher(Function> errorHandler); + ErrorHandlingOperators onErrorResumeWithRsPublisher( + Function> errorHandler); } diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/FilteringOperators.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/FilteringOperators.java index 4799dd7..bdda41e 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/FilteringOperators.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/FilteringOperators.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -25,27 +25,29 @@ * Operations for transforming a stream. *

* The documentation for each operator uses marble diagrams to visualize how the operator functions. Each element - * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator - * applying some transformation or some side effect, termination and error signals potentially being passed, and - * for operators that subscribe to the stream, an output value being redeemed at the end. + * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator applying + * some transformation or some side effect, termination and error signals potentially being passed, and for operators + * that subscribe to the stream, an output value being redeemed at the end. *

* Below is an example diagram labelling all the parts of the stream. *

* Example marble diagram * - * @param The type of the elements that the stream emits. + * @param + * The type of the elements that the stream emits. */ public interface FilteringOperators { /** * Filter elements emitted by this publisher using the given {@link Predicate}. *

- * Any elements that return {@code true} when passed to the {@link Predicate} will be emitted, all other - * elements will be dropped. + * Any elements that return {@code true} when passed to the {@link Predicate} will be emitted, all other elements + * will be dropped. *

* filter marbles diagram * - * @param predicate The predicate to apply to each element. + * @param predicate + * The predicate to apply to each element. * @return A new stream builder. */ FilteringOperators filter(Predicate predicate); @@ -67,21 +69,25 @@ public interface FilteringOperators { * If {@code maxSize} is reached, the stream will be completed, and upstream will be cancelled. Completion of the * stream will occur immediately when the element that satisfies the {@code maxSize} is received. * - * @param maxSize The maximum size of the returned stream. + * @param maxSize + * The maximum size of the returned stream. * @return A new stream builder. - * @throws IllegalArgumentException If {@code maxSize} is less than zero. + * @throws IllegalArgumentException + * If {@code maxSize} is less than zero. */ FilteringOperators limit(long maxSize); /** - * Discard the first {@code n} of this stream. If this stream contains fewer than {@code n} elements, this stream will - * effectively be an empty stream. + * Discard the first {@code n} of this stream. If this stream contains fewer than {@code n} elements, this stream + * will effectively be an empty stream. *

* skip marble diagram * - * @param n The number of elements to discard. + * @param n + * The number of elements to discard. * @return A new stream builder. - * @throws IllegalArgumentException If {@code n} is less than zero. + * @throws IllegalArgumentException + * If {@code n} is less than zero. */ FilteringOperators skip(long n); @@ -92,7 +98,8 @@ public interface FilteringOperators { *

* When the {@code predicate} returns false, the stream will be completed, and upstream will be cancelled. * - * @param predicate The predicate. + * @param predicate + * The predicate. * @return A new stream builder. */ FilteringOperators takeWhile(Predicate predicate); @@ -102,11 +109,12 @@ public interface FilteringOperators { *

* dropWhile marble diagram *

- * As long as the {@code predicate} returns true, no elements will be emitted from this stream. Once the first element - * is encountered for which the {@code predicate} returns false, all subsequent elements will be emitted, and the - * {@code predicate} will no longer be invoked. + * As long as the {@code predicate} returns true, no elements will be emitted from this stream. Once the first + * element is encountered for which the {@code predicate} returns false, all subsequent elements will be emitted, + * and the {@code predicate} will no longer be invoked. * - * @param predicate The predicate. + * @param predicate + * The predicate. * @return A new stream builder. */ FilteringOperators dropWhile(Predicate predicate); diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/PeekingOperators.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/PeekingOperators.java index e6ef9b4..b623377 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/PeekingOperators.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/PeekingOperators.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -25,65 +25,70 @@ * Operations for peeking at elements and signals in the stream, without impacting the stream itself. *

* The documentation for each operator uses marble diagrams to visualize how the operator functions. Each element - * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator - * applying some transformation or some side effect, termination and error signals potentially being passed, and - * for operators that subscribe to the stream, an output value being redeemed at the end. + * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator applying + * some transformation or some side effect, termination and error signals potentially being passed, and for operators + * that subscribe to the stream, an output value being redeemed at the end. *

* Below is an example diagram labelling all the parts of the stream. *

* Example marble diagram * - * @param The type of the elements that the stream emits. + * @param + * The type of the elements that the stream emits. */ public interface PeekingOperators { /** - * Returns a stream containing all the elements from this stream, additionally performing the provided action on each - * element. + * Returns a stream containing all the elements from this stream, additionally performing the provided action on + * each element. *

* peek marbles diagram * - * @param consumer The function called for every element. - * @return A new stream builder that consumes elements of type T and emits the same elements. In between, - * the given function is called for each element. + * @param consumer + * The function called for every element. + * @return A new stream builder that consumes elements of type T and emits the same elements. In + * between, the given function is called for each element. */ PeekingOperators peek(Consumer consumer); /** - * Returns a stream containing all the elements from this stream, additionally performing the provided action if this - * stream conveys an error. The given consumer is called with the failure. + * Returns a stream containing all the elements from this stream, additionally performing the provided action if + * this stream conveys an error. The given consumer is called with the failure. *

* onError marble diagram * - * @param errorHandler The function called with the failure. + * @param errorHandler + * The function called with the failure. * @return A new stream builder that consumes elements of type T and emits the same elements. If the - * stream conveys a failure, the given error handler is called. + * stream conveys a failure, the given error handler is called. */ PeekingOperators onError(Consumer errorHandler); /** - * Returns a stream containing all the elements from this stream, additionally performing the provided action when this - * stream completes or failed. The given action does not know if the stream failed or completed. If you need to - * distinguish use {@link #onError(Consumer)} and {@link #onComplete(Runnable)}. In addition, the action is called if - * the stream is cancelled downstream. + * Returns a stream containing all the elements from this stream, additionally performing the provided action when + * this stream completes or failed. The given action does not know if the stream failed or completed. If you need to + * distinguish use {@link #onError(Consumer)} and {@link #onComplete(Runnable)}. In addition, the action is called + * if the stream is cancelled downstream. *

* onTerminate marble diagram * - * @param action The function called when the stream completes or failed. + * @param action + * The function called when the stream completes or failed. * @return A new stream builder that consumes elements of type T and emits the same elements. The given - * action is called when the stream completes or fails. + * action is called when the stream completes or fails. */ PeekingOperators onTerminate(Runnable action); /** - * Returns a stream containing all the elements from this stream, additionally performing the provided action when this - * stream completes. + * Returns a stream containing all the elements from this stream, additionally performing the provided action when + * this stream completes. *

* onComplete marble diagram * - * @param action The function called when the stream completes. + * @param action + * The function called when the stream completes. * @return A new stream builder that consumes elements of type T and emits the same elements. The given - * action is called when the stream completes. + * action is called when the stream completes. */ PeekingOperators onComplete(Runnable action); } diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ProcessorBuilder.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ProcessorBuilder.java index 7928a63..67d36fd 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ProcessorBuilder.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ProcessorBuilder.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018, 2020 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,11 +19,6 @@ package org.eclipse.microprofile.reactive.streams.operators; -import org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine; -import org.reactivestreams.Processor; -import org.reactivestreams.Publisher; -import org.reactivestreams.Subscriber; - import java.util.List; import java.util.Optional; import java.util.concurrent.CompletionStage; @@ -35,26 +30,40 @@ import java.util.function.Supplier; import java.util.stream.Collector; +import org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine; +import org.reactivestreams.Processor; +import org.reactivestreams.Publisher; +import org.reactivestreams.Subscriber; + /** * A builder for a {@link Processor}. *

* The documentation for each operator uses marble diagrams to visualize how the operator functions. Each element - * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator - * applying some transformation or some side effect, termination and error signals potentially being passed, and - * for operators that subscribe to the stream, an output value being redeemed at the end. + * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator applying + * some transformation or some side effect, termination and error signals potentially being passed, and for operators + * that subscribe to the stream, an output value being redeemed at the end. *

* Below is an example diagram labelling all the parts of the stream. *

* Example marble diagram *

- * Instances of this interface are immutable. Methods which return a {@code ProcessorBuilder} will return a new instance. + * Instances of this interface are immutable. Methods which return a {@code ProcessorBuilder} will return a new + * instance. * - * @param The type of the elements that the processor consumes. - * @param The type of the elements that the processor emits. + * @param + * The type of the elements that the processor consumes. + * @param + * The type of the elements that the processor emits. * @see ReactiveStreams */ -public interface ProcessorBuilder extends TransformingOperators, FilteringOperators, PeekingOperators, ConsumingOperators, - ErrorHandlingOperators, ConnectingOperators { +public interface ProcessorBuilder + extends + TransformingOperators, + FilteringOperators, + PeekingOperators, + ConsumingOperators, + ErrorHandlingOperators, + ConnectingOperators { /** * {@inheritDoc} @@ -78,7 +87,8 @@ public interface ProcessorBuilder extends TransformingOperators, Filter * {@inheritDoc} */ @Override - ProcessorBuilder flatMapCompletionStage(Function> mapper); + ProcessorBuilder flatMapCompletionStage( + Function> mapper); /** * {@inheritDoc} @@ -148,6 +158,7 @@ public interface ProcessorBuilder extends TransformingOperators, Filter /** * {@inheritDoc} + * * @return A {@link SubscriberBuilder} that will invoke the action for each element of the stream. */ @Override @@ -155,6 +166,7 @@ public interface ProcessorBuilder extends TransformingOperators, Filter /** * {@inheritDoc} + * * @return A new {@link SubscriberBuilder} for the stream. */ @Override @@ -162,6 +174,7 @@ public interface ProcessorBuilder extends TransformingOperators, Filter /** * {@inheritDoc} + * * @return A new {@link SubscriberBuilder} for the stream. */ @Override @@ -169,6 +182,7 @@ public interface ProcessorBuilder extends TransformingOperators, Filter /** * {@inheritDoc} + * * @return A new {@link SubscriberBuilder} for the reduction. */ @Override @@ -176,6 +190,7 @@ public interface ProcessorBuilder extends TransformingOperators, Filter /** * {@inheritDoc} + * * @return A new {@link SubscriberBuilder} for the reduction. */ @Override @@ -183,6 +198,7 @@ public interface ProcessorBuilder extends TransformingOperators, Filter /** * {@inheritDoc} + * * @return A new {@link SubscriberBuilder} that will emit the collected result. */ @Override @@ -190,6 +206,7 @@ public interface ProcessorBuilder extends TransformingOperators, Filter /** * {@inheritDoc} + * * @return A new {@link SubscriberBuilder} that will emit the collected result. */ @Override @@ -197,6 +214,7 @@ public interface ProcessorBuilder extends TransformingOperators, Filter /** * {@inheritDoc} + * * @return A new {@link SubscriberBuilder} that will emit the list. */ @Override @@ -204,6 +222,7 @@ public interface ProcessorBuilder extends TransformingOperators, Filter /** * {@inheritDoc} + * * @return A new {@link SubscriberBuilder}. */ @Override @@ -225,7 +244,8 @@ public interface ProcessorBuilder extends TransformingOperators, Filter * {@inheritDoc} */ @Override - ProcessorBuilder onErrorResumeWithRsPublisher(Function> errorHandler); + ProcessorBuilder onErrorResumeWithRsPublisher( + Function> errorHandler); /** * {@inheritDoc} @@ -261,7 +281,8 @@ public interface ProcessorBuilder extends TransformingOperators, Filter /** * Build this stream, using the supplied {@link ReactiveStreamsEngine}. * - * @param engine The engine to run the stream with. + * @param engine + * The engine to run the stream with. * @return A {@link Processor} that will run this stream. */ Processor buildRs(ReactiveStreamsEngine engine); diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ProducesResult.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ProducesResult.java index a81714c..0ad6d62 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ProducesResult.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ProducesResult.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -25,7 +25,8 @@ * This will either be a {@link SubscriberBuilder}, representing a stream with an inlet that can be plumbed to a * publisher in order to run it, or a {@link CompletionRunner}, representing a closed graph that can be run as is. * - * @param The result of the stream. + * @param + * The result of the stream. * @see SubscriberBuilder * @see CompletionRunner */ diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/PublisherBuilder.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/PublisherBuilder.java index 445116b..45da89d 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/PublisherBuilder.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/PublisherBuilder.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018, 2020 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,11 +19,6 @@ package org.eclipse.microprofile.reactive.streams.operators; -import org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine; -import org.reactivestreams.Processor; -import org.reactivestreams.Publisher; -import org.reactivestreams.Subscriber; - import java.util.List; import java.util.Optional; import java.util.concurrent.CompletionStage; @@ -35,25 +30,38 @@ import java.util.function.Supplier; import java.util.stream.Collector; +import org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine; +import org.reactivestreams.Processor; +import org.reactivestreams.Publisher; +import org.reactivestreams.Subscriber; + /** * A builder for a {@link Publisher}. *

* The documentation for each operator uses marble diagrams to visualize how the operator functions. Each element - * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator - * applying some transformation or some side effect, termination and error signals potentially being passed, and - * for operators that subscribe to the stream, an output value being redeemed at the end. + * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator applying + * some transformation or some side effect, termination and error signals potentially being passed, and for operators + * that subscribe to the stream, an output value being redeemed at the end. *

* Below is an example diagram labelling all the parts of the stream. *

* Example marble diagram *

- * Instances of this interface are immutable. Methods which return a {@code PublisherBuilder} will return a new instance. + * Instances of this interface are immutable. Methods which return a {@code PublisherBuilder} will return a new + * instance. * - * @param The type of the elements that the publisher emits. + * @param + * The type of the elements that the publisher emits. * @see ReactiveStreams */ -public interface PublisherBuilder extends TransformingOperators, FilteringOperators, PeekingOperators, ConsumingOperators, - ErrorHandlingOperators, ConnectingOperators { +public interface PublisherBuilder + extends + TransformingOperators, + FilteringOperators, + PeekingOperators, + ConsumingOperators, + ErrorHandlingOperators, + ConnectingOperators { /** * {@inheritDoc} @@ -147,6 +155,7 @@ public interface PublisherBuilder extends TransformingOperators, Filtering /** * {@inheritDoc} + * * @return A new {@link CompletionRunner} that can be used to run the stream. */ @Override @@ -154,6 +163,7 @@ public interface PublisherBuilder extends TransformingOperators, Filtering /** * {@inheritDoc} + * * @return A new {@link CompletionRunner} that can be used to run the stream. */ @Override @@ -161,6 +171,7 @@ public interface PublisherBuilder extends TransformingOperators, Filtering /** * {@inheritDoc} + * * @return A new {@link CompletionRunner} that can be used to run the stream. */ @Override @@ -168,6 +179,7 @@ public interface PublisherBuilder extends TransformingOperators, Filtering /** * {@inheritDoc} + * * @return A new {@link CompletionRunner} that can be used to run the stream. */ @Override @@ -175,6 +187,7 @@ public interface PublisherBuilder extends TransformingOperators, Filtering /** * {@inheritDoc} + * * @return A new {@link CompletionRunner} that can be used to run the stream. */ @Override @@ -182,6 +195,7 @@ public interface PublisherBuilder extends TransformingOperators, Filtering /** * {@inheritDoc} + * * @return A new {@link CompletionRunner} that can be used to run the stream. */ @Override @@ -189,13 +203,15 @@ public interface PublisherBuilder extends TransformingOperators, Filtering /** * {@inheritDoc} - * @return A new {@link CompletionRunner} that can be used to run the stream, - * R is the result type of the collector's reduction operation. + * + * @return A new {@link CompletionRunner} that can be used to run the stream, R is the result type of the + * collector's reduction operation. */ @Override CompletionRunner collect(Collector collector); /** * {@inheritDoc} + * * @return A new {@link CompletionRunner} that can be used to run the stream which emits the collected result. */ @Override @@ -203,6 +219,7 @@ public interface PublisherBuilder extends TransformingOperators, Filtering /** * {@inheritDoc} + * * @return A new {@link CompletionRunner} that can be used to run the stream that emits the list. */ @Override @@ -224,10 +241,12 @@ public interface PublisherBuilder extends TransformingOperators, Filtering * {@inheritDoc} */ @Override - PublisherBuilder onErrorResumeWithRsPublisher(Function> errorHandler); + PublisherBuilder onErrorResumeWithRsPublisher( + Function> errorHandler); /** * {@inheritDoc} + * * @return A new {@link CompletionRunner} that can be used to run the composed stream. */ @Override @@ -235,6 +254,7 @@ public interface PublisherBuilder extends TransformingOperators, Filtering /** * {@inheritDoc} + * * @return A new {@link CompletionRunner} that can be used to run the composed stream. */ @Override @@ -259,10 +279,12 @@ public interface PublisherBuilder extends TransformingOperators, Filtering Publisher buildRs(); /** - * Build this stream, using the supplied {@link ReactiveStreamsEngine}. - * This method is designed for the use case where you have to supply a paritcular {@link ReactiveStreamsEngine}. - * Most cases you should use {@link #buildRs()}. - * @param engine The engine to run the stream with. + * Build this stream, using the supplied {@link ReactiveStreamsEngine}. This method is designed for the use case + * where you have to supply a paritcular {@link ReactiveStreamsEngine}. Most cases you should use + * {@link #buildRs()}. + * + * @param engine + * The engine to run the stream with. * @return A {@link Publisher} that will run this stream. */ Publisher buildRs(ReactiveStreamsEngine engine); diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ReactiveStreams.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ReactiveStreams.java index 2c72513..59ba9f0 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ReactiveStreams.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ReactiveStreams.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018, 2020 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,15 +19,15 @@ package org.eclipse.microprofile.reactive.streams.operators; -import org.reactivestreams.Processor; -import org.reactivestreams.Publisher; -import org.reactivestreams.Subscriber; +import static org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsFactoryResolver.instance; import java.util.concurrent.CompletionStage; import java.util.function.Supplier; import java.util.function.UnaryOperator; -import static org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsFactoryResolver.instance; +import org.reactivestreams.Processor; +import org.reactivestreams.Publisher; +import org.reactivestreams.Subscriber; /** * Primary entry point into the Reactive Streams utility API. @@ -36,9 +36,9 @@ * using their respective APIs. *

* The documentation for each operator uses marble diagrams to visualize how the operator functions. Each element - * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator - * applying some transformation or some side effect, termination and error signals potentially being passed, and - * for operators that subscribe to the stream, an output value being redeemed at the end. + * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator applying + * some transformation or some side effect, termination and error signals potentially being passed, and for operators + * that subscribe to the stream, an output value being redeemed at the end. *

* Below is an example diagram labelling all the parts of the stream. *

@@ -52,8 +52,10 @@ private ReactiveStreams() { /** * Create a {@link PublisherBuilder} from the given {@link Publisher}. * - * @param publisher The publisher to wrap. - * @param The type of the elements that the publisher produces. + * @param publisher + * The publisher to wrap. + * @param + * The type of the elements that the publisher produces. * @return A publisher builder that wraps the given publisher. */ public static PublisherBuilder fromPublisher(Publisher publisher) { @@ -65,8 +67,10 @@ public static PublisherBuilder fromPublisher(Publisher publi *

* of marble diagram * - * @param t The element to emit. - * @param The type of the element. + * @param t + * The element to emit. + * @param + * The type of the element. * @return A publisher builder that will emit the element. */ public static PublisherBuilder of(T t) { @@ -78,8 +82,10 @@ public static PublisherBuilder of(T t) { *

* of marble diagram * - * @param ts The elements to emit. - * @param The type of the elements. + * @param ts + * The elements to emit. + * @param + * The type of the elements. * @return A publisher builder that will emit the elements. */ public static PublisherBuilder of(T... ts) { @@ -91,7 +97,8 @@ public static PublisherBuilder of(T... ts) { *

* empty marble diagram * - * @param The type of the publisher builder. + * @param + * The type of the publisher builder. * @return A publisher builder that will just emit a completion signal. */ public static PublisherBuilder empty() { @@ -99,13 +106,15 @@ public static PublisherBuilder empty() { } /** - * Create a {@link PublisherBuilder} that will emit a single element if t is not null, otherwise will be - * empty. + * Create a {@link PublisherBuilder} that will emit a single element if t is not null, otherwise will + * be empty. *

* ofNullable marble diagram * - * @param t The element to emit, null if to element should be emitted. - * @param The type of the element. + * @param t + * The element to emit, null if to element should be emitted. + * @param + * The type of the element. * @return A publisher builder that optionally emits a single element. */ public static PublisherBuilder ofNullable(T t) { @@ -117,8 +126,10 @@ public static PublisherBuilder ofNullable(T t) { *

* fromIterable marble diagram * - * @param ts The elements to emit. - * @param The type of the elements. + * @param ts + * The elements to emit. + * @param + * The type of the elements. * @return A publisher builder that emits the elements of the iterable. */ public static PublisherBuilder fromIterable(Iterable ts) { @@ -132,8 +143,10 @@ public static PublisherBuilder fromIterable(Iterable ts) { *

* This publisher will just emit an error. * - * @param t The error te emit. - * @param The type of the publisher builder. + * @param t + * The error te emit. + * @param + * The type of the publisher builder. * @return A publisher builder that completes the stream with an error. */ public static PublisherBuilder failed(Throwable t) { @@ -145,7 +158,8 @@ public static PublisherBuilder failed(Throwable t) { *

* identity marble diagram * - * @param The type of elements that the processor consumes and emits. + * @param + * The type of elements that the processor consumes and emits. * @return The identity processor builder. */ public static ProcessorBuilder builder() { @@ -155,9 +169,12 @@ public static ProcessorBuilder builder() { /** * Create a {@link ProcessorBuilder} from the given {@link Processor}. * - * @param processor The processor to be wrapped. - * @param The type of the elements that the processor consumes. - * @param The type of the elements that the processor emits. + * @param processor + * The processor to be wrapped. + * @param + * The type of the elements that the processor consumes. + * @param + * The type of the elements that the processor emits. * @return A processor builder that wraps the processor. */ public static ProcessorBuilder fromProcessor(Processor processor) { @@ -165,11 +182,13 @@ public static ProcessorBuilder fromProcessor(Processor The type of elements that the subscriber consumes. + * @param subscriber + * The subscriber to be wrapped. + * @param + * The type of elements that the subscriber consumes. * @return A subscriber builder that wraps the subscriber. */ public static SubscriberBuilder fromSubscriber(Subscriber subscriber) { @@ -182,9 +201,12 @@ public static SubscriberBuilder fromSubscriber(Subscriber * iterate marble diagram * - * @param seed The initial element. - * @param f A function applied to the previous element to produce the next element. - * @param The type of stream elements. + * @param seed + * The initial element. + * @param f + * A function applied to the previous element to produce the next element. + * @param + * The type of stream elements. * @return A publisher builder. */ public static PublisherBuilder iterate(T seed, UnaryOperator f) { @@ -196,8 +218,10 @@ public static PublisherBuilder iterate(T seed, UnaryOperator f) { *

* generate marble diagram * - * @param s The supplier. - * @param The type of stream elements. + * @param s + * The supplier. + * @param + * The type of stream elements. * @return A publisher builder. */ public static PublisherBuilder generate(Supplier s) { @@ -214,17 +238,19 @@ public static PublisherBuilder generate(Supplier s) { * will be emitted. *

* If the first publisher completes with an error signal, then the second publisher will be subscribed to but - * immediately cancelled, none of its elements will be emitted. This ensures that hot publishers are cleaned up. - * If downstream emits a cancellation signal before the first publisher finishes, it will be passed to both - * publishers. + * immediately cancelled, none of its elements will be emitted. This ensures that hot publishers are cleaned up. If + * downstream emits a cancellation signal before the first publisher finishes, it will be passed to both publishers. * - * @param a The first publisher. - * @param b The second publisher. - * @param The type of stream elements. + * @param a + * The first publisher. + * @param b + * The second publisher. + * @param + * The type of stream elements. * @return A publisher builder. */ public static PublisherBuilder concat(PublisherBuilder a, - PublisherBuilder b) { + PublisherBuilder b) { return instance().concat(a, b); } @@ -239,8 +265,10 @@ public static PublisherBuilder concat(PublisherBuilder a, *

* If the {@code CompletionStage} is completed with a failure, this failure will be propagated through the stream. * - * @param completionStage The {@code CompletionStage} to create the publisher from. - * @param The type of the {@code CompletionStage} value. + * @param completionStage + * The {@code CompletionStage} to create the publisher from. + * @param + * The type of the {@code CompletionStage} value. * @return A {@code PublisherBuilder} representation of this {@code CompletionStage}. */ public static PublisherBuilder fromCompletionStage(CompletionStage completionStage) { @@ -253,13 +281,15 @@ public static PublisherBuilder fromCompletionStage(CompletionStage *

* When the {@code CompletionStage} is redeemed, the publisher will emit the redeemed element, and then signal - * completion. If the completion stage is redeemed with {@code null}, the stream will be immediately completed - * with no element, ie, it will be an empty stream. + * completion. If the completion stage is redeemed with {@code null}, the stream will be immediately completed with + * no element, ie, it will be an empty stream. *

* If the {@code CompletionStage} is completed with a failure, this failure will be propagated through the stream. * - * @param completionStage The {@code CompletionStage} to create the publisher from. - * @param The type of the {@code CompletionStage} value. + * @param completionStage + * The {@code CompletionStage} to create the publisher from. + * @param + * The type of the {@code CompletionStage} value. * @return A {@code PublisherBuilder} representation of this {@code CompletionStage}. */ public static PublisherBuilder fromCompletionStageNullable(CompletionStage completionStage) { @@ -271,11 +301,11 @@ public static PublisherBuilder fromCompletionStageNullable(CompletionStag *

* coupled marble diagram *

- * The resulting processor sends all the elements received to the passed in subscriber, and emits all the - * elements received from the passed in publisher. + * The resulting processor sends all the elements received to the passed in subscriber, and emits all the elements + * received from the passed in publisher. *

- * In addition, the lifecycles of the subscriber and publisher are coupled, such that if one terminates or - * receives a termination signal, the other will be terminated. Below is a table of what signals are emited when. + * In addition, the lifecycles of the subscriber and publisher are coupled, such that if one terminates or receives + * a termination signal, the other will be terminated. Below is a table of what signals are emited when. *

* * @@ -323,14 +353,18 @@ public static PublisherBuilder fromCompletionStageNullable(CompletionStag * *
Lifecycle signal propagation
* - * @param subscriber The subscriber builder to wrap. - * @param publisher The publisher builder to wrap. - * @param The type of elements received. - * @param The type of elements emitted. + * @param subscriber + * The subscriber builder to wrap. + * @param publisher + * The publisher builder to wrap. + * @param + * The type of elements received. + * @param + * The type of elements emitted. * @return The coupled processor builder. */ public static ProcessorBuilder coupled(SubscriberBuilder subscriber, - PublisherBuilder publisher) { + PublisherBuilder publisher) { return instance().coupled(subscriber, publisher); } @@ -339,11 +373,11 @@ public static ProcessorBuilder coupled(SubscriberBuilder * coupled marble diagram *

- * The resulting processor sends all the elements received to the passed in subscriber, and emits all the - * elements received from the passed in publisher. + * The resulting processor sends all the elements received to the passed in subscriber, and emits all the elements + * received from the passed in publisher. *

- * In addition, the lifecycles of the subscriber and publisher are coupled, such that if one terminates or - * receives a termination signal, the other will be terminated. Below is a table of what signals are emited when: + * In addition, the lifecycles of the subscriber and publisher are coupled, such that if one terminates or receives + * a termination signal, the other will be terminated. Below is a table of what signals are emited when: *

* * @@ -391,15 +425,19 @@ public static ProcessorBuilder coupled(SubscriberBuilder *
Lifecycle signal propagation
* - * @param subscriber The subscriber builder to wrap. - * @param publisher The publisher builder to wrap. - * @param The type of elements received. - * @param The type of elements emitted. + * @param subscriber + * The subscriber builder to wrap. + * @param publisher + * The publisher builder to wrap. + * @param + * The type of elements received. + * @param + * The type of elements emitted. * @return The coupled processor builder. * @see #coupled(SubscriberBuilder, PublisherBuilder) */ public static ProcessorBuilder coupled(Subscriber subscriber, - Publisher publisher) { + Publisher publisher) { return instance().coupled(subscriber, publisher); } diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ReactiveStreamsFactory.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ReactiveStreamsFactory.java index c1c2a6f..5a94197 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ReactiveStreamsFactory.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/ReactiveStreamsFactory.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018, 2020 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,14 +19,14 @@ package org.eclipse.microprofile.reactive.streams.operators; -import org.reactivestreams.Processor; -import org.reactivestreams.Publisher; -import org.reactivestreams.Subscriber; - import java.util.concurrent.CompletionStage; import java.util.function.Supplier; import java.util.function.UnaryOperator; +import org.reactivestreams.Processor; +import org.reactivestreams.Publisher; +import org.reactivestreams.Subscriber; + /** * Factory interface for providing the implementation of the static factory methods in {@link ReactiveStreams}. */ @@ -34,8 +34,10 @@ public interface ReactiveStreamsFactory { /** * Create a {@link PublisherBuilder} from the given {@link Publisher}. * - * @param publisher The publisher to wrap. - * @param The type of the elements that the publisher produces. + * @param publisher + * The publisher to wrap. + * @param + * The type of the elements that the publisher produces. * @return A publisher builder that wraps the given publisher. */ PublisherBuilder fromPublisher(Publisher publisher); @@ -45,8 +47,10 @@ public interface ReactiveStreamsFactory { *

* of marble diagram * - * @param t The element to emit. - * @param The type of the element. + * @param t + * The element to emit. + * @param + * The type of the element. * @return A publisher builder that will emit the element. */ PublisherBuilder of(T t); @@ -56,8 +60,10 @@ public interface ReactiveStreamsFactory { *

* of marble diagram * - * @param ts The elements to emit. - * @param The type of the elements. + * @param ts + * The elements to emit. + * @param + * The type of the elements. * @return A publisher builder that will emit the elements. */ PublisherBuilder of(T... ts); @@ -67,19 +73,22 @@ public interface ReactiveStreamsFactory { *

* empty marble diagram * - * @param The type of the publisher builder. + * @param + * The type of the publisher builder. * @return A publisher builder that will just emit a completion signal. */ PublisherBuilder empty(); /** - * Create a {@link PublisherBuilder} that will emit a single element if t is not null, otherwise will be - * empty. + * Create a {@link PublisherBuilder} that will emit a single element if t is not null, otherwise will + * be empty. *

* ofNullable marble diagram * - * @param t The element to emit, null if to element should be emitted. - * @param The type of the element. + * @param t + * The element to emit, null if to element should be emitted. + * @param + * The type of the element. * @return A publisher builder that optionally emits a single element. */ PublisherBuilder ofNullable(T t); @@ -89,8 +98,10 @@ public interface ReactiveStreamsFactory { *

* fromIterable marble diagram * - * @param ts The elements to emit. - * @param The type of the elements. + * @param ts + * The elements to emit. + * @param + * The type of the elements. * @return A publisher builder that emits the elements of the iterable. */ PublisherBuilder fromIterable(Iterable ts); @@ -102,8 +113,10 @@ public interface ReactiveStreamsFactory { *

* This publisher will just emit an error. * - * @param t The error te emit. - * @param The type of the publisher builder. + * @param t + * The error te emit. + * @param + * The type of the publisher builder. * @return A publisher builder that completes the stream with an error. */ PublisherBuilder failed(Throwable t); @@ -113,7 +126,8 @@ public interface ReactiveStreamsFactory { *

* identity marble diagram * - * @param The type of elements that the processor consumes and emits. + * @param + * The type of elements that the processor consumes and emits. * @return The identity processor builder. */ ProcessorBuilder builder(); @@ -121,19 +135,24 @@ public interface ReactiveStreamsFactory { /** * Create a {@link ProcessorBuilder} from the given {@link Processor}. * - * @param processor The processor to be wrapped. - * @param The type of the elements that the processor consumes. - * @param The type of the elements that the processor emits. + * @param processor + * The processor to be wrapped. + * @param + * The type of the elements that the processor consumes. + * @param + * The type of the elements that the processor emits. * @return A processor builder that wraps the processor. */ ProcessorBuilder fromProcessor(Processor processor); /** - * Create a {@link SubscriberBuilder} from the given {@link Subscriber}. - * The subscriber can only be used to create a single subscriber builder. + * Create a {@link SubscriberBuilder} from the given {@link Subscriber}. The subscriber can only be used to create a + * single subscriber builder. * - * @param subscriber The subscriber to be wrapped. - * @param The type of elements that the subscriber consumes. + * @param subscriber + * The subscriber to be wrapped. + * @param + * The type of elements that the subscriber consumes. * @return A subscriber builder that wraps the subscriber. */ SubscriberBuilder fromSubscriber(Subscriber subscriber); @@ -144,9 +163,12 @@ public interface ReactiveStreamsFactory { *

* iterate marble diagram * - * @param seed The initial element. - * @param f A function applied to the previous element to produce the next element. - * @param The type of stream elements. + * @param seed + * The initial element. + * @param f + * A function applied to the previous element to produce the next element. + * @param + * The type of stream elements. * @return A publisher builder. */ PublisherBuilder iterate(T seed, UnaryOperator f); @@ -156,8 +178,10 @@ public interface ReactiveStreamsFactory { *

* generate marble diagram * - * @param s The supplier. - * @param The type of stream elements. + * @param s + * The supplier. + * @param + * The type of stream elements. * @return A publisher builder. */ PublisherBuilder generate(Supplier s); @@ -172,13 +196,15 @@ public interface ReactiveStreamsFactory { * will be emitted. *

* If the first publisher completes with an error signal, then the second publisher will be subscribed to but - * immediately cancelled, none of its elements will be emitted. This ensures that hot publishers are cleaned up. - * If downstream emits a cancellation signal before the first publisher finishes, it will be passed to both - * publishers. + * immediately cancelled, none of its elements will be emitted. This ensures that hot publishers are cleaned up. If + * downstream emits a cancellation signal before the first publisher finishes, it will be passed to both publishers. * - * @param a The first publisher. - * @param b The second publisher. - * @param The type of stream elements. + * @param a + * The first publisher. + * @param b + * The second publisher. + * @param + * The type of stream elements. * @return A publisher builder. */ PublisherBuilder concat(PublisherBuilder a, PublisherBuilder b); @@ -194,8 +220,10 @@ public interface ReactiveStreamsFactory { *

* If the {@code CompletionStage} is completed with a failure, this failure will be propagated through the stream. * - * @param completionStage The {@code CompletionStage} to create the publisher from. - * @param The type of the {@code CompletionStage} value. + * @param completionStage + * The {@code CompletionStage} to create the publisher from. + * @param + * The type of the {@code CompletionStage} value. * @return A {@code PublisherBuilder} representation of this {@code CompletionStage}. */ PublisherBuilder fromCompletionStage(CompletionStage completionStage); @@ -206,13 +234,15 @@ public interface ReactiveStreamsFactory { * fromCompletionStage marble diagram *

* When the {@code CompletionStage} is redeemed, the publisher will emit the redeemed element, and then signal - * completion. If the completion stage is redeemed with {@code null}, the stream will be immediately completed - * with no element, ie, it will be an empty stream. + * completion. If the completion stage is redeemed with {@code null}, the stream will be immediately completed with + * no element, ie, it will be an empty stream. *

* If the {@code CompletionStage} is completed with a failure, this failure will be propagated through the stream. * - * @param completionStage The {@code CompletionStage} to create the publisher from. - * @param The type of the {@code CompletionStage} value. + * @param completionStage + * The {@code CompletionStage} to create the publisher from. + * @param + * The type of the {@code CompletionStage} value. * @return A {@code PublisherBuilder} representation of this {@code CompletionStage}. */ PublisherBuilder fromCompletionStageNullable(CompletionStage completionStage); @@ -222,11 +252,11 @@ public interface ReactiveStreamsFactory { *

* coupled marble diagram *

- * The resulting processor sends all the elements received to the passed in subscriber, and emits all the - * elements received from the passed in publisher. + * The resulting processor sends all the elements received to the passed in subscriber, and emits all the elements + * received from the passed in publisher. *

- * In addition, the lifecycles of the subscriber and publisher are coupled, such that if one terminates or - * receives a termination signal, the other will be terminated. Below is a table of what signals are emited when: + * In addition, the lifecycles of the subscriber and publisher are coupled, such that if one terminates or receives + * a termination signal, the other will be terminated. Below is a table of what signals are emited when: *

* * @@ -274,25 +304,29 @@ public interface ReactiveStreamsFactory { * *
Lifecycle signal propagation
* - * @param subscriber The subscriber builder to wrap. - * @param publisher The publisher builder to wrap. - * @param The type of elements received. - * @param The type of elements emitted. + * @param subscriber + * The subscriber builder to wrap. + * @param publisher + * The publisher builder to wrap. + * @param + * The type of elements received. + * @param + * The type of elements emitted. * @return The coupled processor builder. */ ProcessorBuilder coupled(SubscriberBuilder subscriber, - PublisherBuilder publisher); + PublisherBuilder publisher); /** * Creates a {@link ProcessorBuilder} by coupling a {@link Subscriber} to a {@link Publisher}. *

* coupled marble diagram *

- * The resulting processor sends all the elements received to the passed in subscriber, and emits all the - * elements received from the passed in publisher. + * The resulting processor sends all the elements received to the passed in subscriber, and emits all the elements + * received from the passed in publisher. *

- * In addition, the lifecycles of the subscriber and publisher are coupled, such that if one terminates or - * receives a termination signal, the other will be terminated. Below is a table of what signals are emited when: + * In addition, the lifecycles of the subscriber and publisher are coupled, such that if one terminates or receives + * a termination signal, the other will be terminated. Below is a table of what signals are emited when: *

* * @@ -340,14 +374,18 @@ ProcessorBuilder coupled(SubscriberBuilder subscriber * *
Lifecycle signal propagation
* - * @param subscriber The subscriber builder to wrap. - * @param publisher The publisher builder to wrap. - * @param The type of elements received. - * @param The type of elements emitted. + * @param subscriber + * The subscriber builder to wrap. + * @param publisher + * The publisher builder to wrap. + * @param + * The type of elements received. + * @param + * The type of elements emitted. * @return The coupled processor builder. * @see #coupled(SubscriberBuilder, PublisherBuilder) */ ProcessorBuilder coupled(Subscriber subscriber, - Publisher publisher); + Publisher publisher); } diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/SubscriberBuilder.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/SubscriberBuilder.java index 59e79ac..c2a2b6d 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/SubscriberBuilder.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/SubscriberBuilder.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -25,15 +25,16 @@ * A builder for a {@link org.reactivestreams.Subscriber} and its result. *

* When built, this builder returns a {@link CompletionSubscriber}, which encapsulates both a - * {@link org.reactivestreams.Subscriber} and a {@link java.util.concurrent.CompletionStage} that will be redeemed - * with the result produced by the subscriber when the stream completes normally, or will be redeemed with an error - * if the subscriber receives an error. A {@link SubscriberBuilder} may represent a compound set of - * stream stages and may complete exceptionally without receiving an error externally. - * Similarly, {@link SubscriberBuilder}s may encapsulate error handling such as the - * onErrorResume operator and recover from an externally received errors. + * {@link org.reactivestreams.Subscriber} and a {@link java.util.concurrent.CompletionStage} that will be redeemed with + * the result produced by the subscriber when the stream completes normally, or will be redeemed with an error if the + * subscriber receives an error. A {@link SubscriberBuilder} may represent a compound set of stream stages and may + * complete exceptionally without receiving an error externally. Similarly, {@link SubscriberBuilder}s may encapsulate + * error handling such as the onErrorResume operator and recover from an externally received errors. * - * @param The type of the elements that this subscriber consumes. - * @param The type of the result that this subscriber emits. + * @param + * The type of the elements that this subscriber consumes. + * @param + * The type of the result that this subscriber emits. * @see ReactiveStreams */ public interface SubscriberBuilder extends ProducesResult { @@ -47,7 +48,8 @@ public interface SubscriberBuilder extends ProducesResult { /** * Build this stream, using the supplied {@link ReactiveStreamsEngine}. * - * @param engine The engine to run the stream with. + * @param engine + * The engine to run the stream with. * @return A {@link CompletionSubscriber} that will run this stream. */ CompletionSubscriber build(ReactiveStreamsEngine engine); diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/TransformingOperators.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/TransformingOperators.java index 0f62c63..779aae7 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/TransformingOperators.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/TransformingOperators.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,24 +19,25 @@ package org.eclipse.microprofile.reactive.streams.operators; -import org.reactivestreams.Publisher; - import java.util.concurrent.CompletionStage; import java.util.function.Function; +import org.reactivestreams.Publisher; + /** * Operations for transforming a stream. *

* The documentation for each operator uses marble diagrams to visualize how the operator functions. Each element - * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator - * applying some transformation or some side effect, termination and error signals potentially being passed, and - * for operators that subscribe to the stream, an output value being redeemed at the end. + * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator applying + * some transformation or some side effect, termination and error signals potentially being passed, and for operators + * that subscribe to the stream, an output value being redeemed at the end. *

* Below is an example diagram labelling all the parts of the stream. *

* Example marble diagram * - * @param The type of the elements that this stream emits. + * @param + * The type of the elements that this stream emits. */ public interface TransformingOperators { @@ -45,8 +46,10 @@ public interface TransformingOperators { *

* map marbles diagram * - * @param mapper The function to use to map the elements. - * @param The type of elements that the {@code mapper} function emits. + * @param mapper + * The function to use to map the elements. + * @param + * The type of elements that the {@code mapper} function emits. * @return A new stream builder that emits the mapped elements. */ TransformingOperators map(Function mapper); @@ -61,11 +64,12 @@ public interface TransformingOperators { * publishers produced by the mapper function. *

* Unlike {@link #flatMapRsPublisher(Function)}}, the mapper function returns a - * {@link org.eclipse.microprofile.reactive.streams} type instead of an - * {@link org.reactivestreams} type. + * {@link org.eclipse.microprofile.reactive.streams} type instead of an {@link org.reactivestreams} type. * - * @param mapper The mapper function. - * @param The type of the elements emitted from the new stream. + * @param mapper + * The mapper function. + * @param + * The type of the elements emitted from the new stream. * @return A new stream builder. */ TransformingOperators flatMap(Function> mapper); @@ -79,19 +83,21 @@ public interface TransformingOperators { * This method operates on one publisher at a time. The result is a concatenation of elements emitted from all the * publishers produced by the mapper function. *

- * Unlike {@link #flatMap(Function)}, the mapper function returns a {@link org.eclipse.microprofile.reactive.streams} - * builder instead of an {@link org.reactivestreams} type. + * Unlike {@link #flatMap(Function)}, the mapper function returns a + * {@link org.eclipse.microprofile.reactive.streams} builder instead of an {@link org.reactivestreams} type. * - * @param mapper The mapper function. - * @param The type of the elements emitted from the new stream. + * @param mapper + * The mapper function. + * @param + * The type of the elements emitted from the new stream. * @return A new stream builder. */ TransformingOperators flatMapRsPublisher(Function> mapper); /** * Map the elements to {@link CompletionStage}, and flatten so that the elements the values redeemed by each - * {@link CompletionStage} are emitted from this stream. - * If the element is {@code null}, this operation should be failed with a {@link NullPointerException}. + * {@link CompletionStage} are emitted from this stream. If the element is {@code null}, this operation should be + * failed with a {@link NullPointerException}. *

* flatMapCompletionStage marble diagram *

@@ -99,23 +105,28 @@ public interface TransformingOperators { * executed, and the next element is not consumed or passed to the {@code mapper} function until the previous * {@link CompletionStage} is redeemed. Hence this method also guarantees that ordering of the stream is maintained. * - * @param mapper The mapper function. - * @param The type of the elements emitted from the new stream. + * @param mapper + * The mapper function. + * @param + * The type of the elements emitted from the new stream. * @return A new stream builder. */ - TransformingOperators flatMapCompletionStage(Function> mapper); + TransformingOperators flatMapCompletionStage( + Function> mapper); /** - * Map the elements to {@link Iterable}'s, and flatten so that the elements contained in each iterable are - * emitted by this stream. + * Map the elements to {@link Iterable}'s, and flatten so that the elements contained in each iterable are emitted + * by this stream. *

* flatMapIterable marble diagram *

* This method operates on one iterable at a time. The result is a concatenation of elements contain in all the * iterables returned by the {@code mapper} function. * - * @param mapper The mapper function. - * @param The type of the elements emitted from the new stream. + * @param mapper + * The mapper function. + * @param + * The type of the elements emitted from the new stream. * @return A new stream builder. */ TransformingOperators flatMapIterable(Function> mapper); diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/package-info.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/package-info.java index 2e895bf..227c016 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/package-info.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/package-info.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018, 2020 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -39,8 +39,8 @@ *

* Operations on these builders may change the shape of the builder, for example, * {@link org.eclipse.microprofile.reactive.streams.operators.ProcessorBuilder#toList()} changes the builder to a - * {@link org.eclipse.microprofile.reactive.streams.operators.SubscriberBuilder}, since the processor now has a termination - * stage to direct its elements to. + * {@link org.eclipse.microprofile.reactive.streams.operators.SubscriberBuilder}, since the processor now has a + * termination stage to direct its elements to. *

* {@link SubscriberBuilder}'s are a special case, in that they don't just build a * {@link org.reactivestreams.Subscriber}, they build a @@ -56,16 +56,16 @@ * result is the {@link java.lang.Void} type, and the {@link java.util.concurrent.CompletionStage} is only useful for * signalling normal or error termination of the stream. *

- * The {@link org.eclipse.microprofile.reactive.streams.operators.CompletionRunner} builds a closed graph, in that case both a - * {@link org.reactivestreams.Publisher} and {@link org.reactivestreams.Subscriber} have been provided, and building the - * graph will run it and return the result of the {@link org.reactivestreams.Subscriber} as a + * The {@link org.eclipse.microprofile.reactive.streams.operators.CompletionRunner} builds a closed graph, in that case + * both a {@link org.reactivestreams.Publisher} and {@link org.reactivestreams.Subscriber} have been provided, and + * building the graph will run it and return the result of the {@link org.reactivestreams.Subscriber} as a * {@link java.util.concurrent.CompletionStage}. *

- * An example use of this API is perhaps you have a {@link org.reactivestreams.Publisher} of rows from a database, - * and you want to output it as a comma separated list of lines to publish to an HTTP client request body, which - * expects a {@link org.reactivestreams.Publisher} of {@link java.nio.ByteBuffer}. Here's how this might be - * implemented: + * An example use of this API is perhaps you have a {@link org.reactivestreams.Publisher} of rows from a database, and + * you want to output it as a comma separated list of lines to publish to an HTTP client request body, which expects a + * {@link org.reactivestreams.Publisher} of {@link java.nio.ByteBuffer}. Here's how this might be implemented: *

+ * * 

  *   Publisher<Row> rowsPublisher = ...;
  *
@@ -93,9 +93,9 @@
  *
*

* The documentation for each operator uses marble diagrams to visualize how the operator functions. Each element - * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator - * applying some transformation or some side effect, termination and error signals potentially being passed, and - * for operators that subscribe to the stream, an output value being redeemed at the end. + * flowing in and out of the stream is represented as a coloured marble that has a value, with the operator applying + * some transformation or some side effect, termination and error signals potentially being passed, and for operators + * that subscribe to the stream, an output value being redeemed at the end. *

* Below is an example diagram labelling all the parts of the stream. *

diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/Graph.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/Graph.java index 08efc51..3dffc7e 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/Graph.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/Graph.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -24,8 +24,8 @@ /** * A graph. *

- * Reactive Streams engines are required to convert the stages of this graph into a stream with interfaces according - * to the shape, which is determined by which method is invoked on the {@link ReactiveStreamsEngine}. + * Reactive Streams engines are required to convert the stages of this graph into a stream with interfaces according to + * the shape, which is determined by which method is invoked on the {@link ReactiveStreamsEngine}. */ public interface Graph { /** diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/ReactiveStreamsEngine.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/ReactiveStreamsEngine.java index 012232e..7c5f62f 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/ReactiveStreamsEngine.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/ReactiveStreamsEngine.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,19 +19,18 @@ package org.eclipse.microprofile.reactive.streams.operators.spi; +import java.util.concurrent.CompletionStage; import org.reactivestreams.Processor; import org.reactivestreams.Publisher; -import java.util.concurrent.CompletionStage; - /** * An engine for turning reactive streams graphs into Reactive Streams publishers/subscribers. *

- * The zero argument {@code build} and {@code run} methods on subclasses of this will use - * the {@link java.util.ServiceLoader} to load an engine for the current context classloader. It does not cache - * engines between invocations. If instantiating an engine is expensive (eg, it creates threads), then it is - * recommended that the implementation does its own caching by providing the engine using a static provider method. + * The zero argument {@code build} and {@code run} methods on subclasses of this will use the + * {@link java.util.ServiceLoader} to load an engine for the current context classloader. It does not cache engines + * between invocations. If instantiating an engine is expensive (eg, it creates threads), then it is recommended that + * the implementation does its own caching by providing the engine using a static provider method. */ public interface ReactiveStreamsEngine { @@ -40,10 +39,13 @@ public interface ReactiveStreamsEngine { *

* The passed in graph will have an outlet and no inlet. * - * @param graph The stages to build the publisher from. Will not be empty. - * @param The type of elements that the publisher publishes. + * @param graph + * The stages to build the publisher from. Will not be empty. + * @param + * The type of elements that the publisher publishes. * @return A publisher that implements the passed in graph of stages. - * @throws UnsupportedStageException If a stage in the stages is not supported by this Reactive Streams engine. + * @throws UnsupportedStageException + * If a stage in the stages is not supported by this Reactive Streams engine. */ Publisher buildPublisher(Graph graph) throws UnsupportedStageException; @@ -52,11 +54,15 @@ public interface ReactiveStreamsEngine { *

* The passed in graph will have an inlet and no outlet. * - * @param graph The graph to build the subscriber from. Will not be empty. - * @param The type of elements that the subscriber subscribes to. - * @param The result of subscribing to the stages. + * @param graph + * The graph to build the subscriber from. Will not be empty. + * @param + * The type of elements that the subscriber subscribes to. + * @param + * The result of subscribing to the stages. * @return A subscriber that implements the passed in graph of stages. - * @throws UnsupportedStageException If a stage in the stages is not supported by this Reactive Streams engine. + * @throws UnsupportedStageException + * If a stage in the stages is not supported by this Reactive Streams engine. */ SubscriberWithCompletionStage buildSubscriber(Graph graph) throws UnsupportedStageException; @@ -65,11 +71,15 @@ public interface ReactiveStreamsEngine { *

* The passed in graph will have an inlet and an outlet. * - * @param graph The graph to build the processor from. If empty, then the processor should be an identity processor. - * @param The type of elements that the processor subscribes to. - * @param The type of elements that the processor publishes. + * @param graph + * The graph to build the processor from. If empty, then the processor should be an identity processor. + * @param + * The type of elements that the processor subscribes to. + * @param + * The type of elements that the processor publishes. * @return A processor that implements the passed in graph of stages. - * @throws UnsupportedStageException If a stage in the stages is not supported by this Reactive Streams engine. + * @throws UnsupportedStageException + * If a stage in the stages is not supported by this Reactive Streams engine. */ Processor buildProcessor(Graph graph) throws UnsupportedStageException; @@ -78,10 +88,13 @@ public interface ReactiveStreamsEngine { *

* The passed in graph will have no inlet and no outlet. * - * @param graph The graph to build the closed graph from. Will not be empty. - * @param The type of the result of running the closed graph. + * @param graph + * The graph to build the closed graph from. Will not be empty. + * @param + * The type of the result of running the closed graph. * @return A CompletionStage of the result of running the graph. - * @throws UnsupportedStageException If a stage in the stages is not supported by this reactive streams engine. + * @throws UnsupportedStageException + * If a stage in the stages is not supported by this reactive streams engine. */ CompletionStage buildCompletion(Graph graph) throws UnsupportedStageException; diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/ReactiveStreamsFactoryResolver.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/ReactiveStreamsFactoryResolver.java index c055361..b752fa4 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/ReactiveStreamsFactoryResolver.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/ReactiveStreamsFactoryResolver.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -18,19 +18,18 @@ ******************************************************************************/ package org.eclipse.microprofile.reactive.streams.operators.spi; -import org.eclipse.microprofile.reactive.streams.operators.ReactiveStreams; -import org.eclipse.microprofile.reactive.streams.operators.ReactiveStreamsFactory; - import java.security.AccessController; import java.security.PrivilegedAction; import java.util.ServiceLoader; +import org.eclipse.microprofile.reactive.streams.operators.ReactiveStreams; +import org.eclipse.microprofile.reactive.streams.operators.ReactiveStreamsFactory; + /** - * This class is not intended to be used by end-users but for - * portable container integration purpose only. + * This class is not intended to be used by end-users but for portable container integration purpose only. *

- * Service provider for ReactiveStreamsFactory. The implementation registers - * itself via the {@link java.util.ServiceLoader} mechanism. + * Service provider for ReactiveStreamsFactory. The implementation registers itself via the + * {@link java.util.ServiceLoader} mechanism. */ public class ReactiveStreamsFactoryResolver { @@ -41,8 +40,7 @@ protected ReactiveStreamsFactoryResolver() { private static volatile ReactiveStreamsFactory instance = null; /** - * Creates a ReactiveStreamsFactory object - * Only used internally from within {@link ReactiveStreams} + * Creates a ReactiveStreamsFactory object Only used internally from within {@link ReactiveStreams} * * @return ReactiveStreamsFactory an instance of ReactiveStreamsFactory */ @@ -53,7 +51,8 @@ public static ReactiveStreamsFactory instance() { return instance; } - ClassLoader cl = AccessController.doPrivileged((PrivilegedAction) () -> Thread.currentThread().getContextClassLoader()); + ClassLoader cl = AccessController.doPrivileged( + (PrivilegedAction) () -> Thread.currentThread().getContextClassLoader()); if (cl == null) { cl = ReactiveStreamsFactory.class.getClassLoader(); } @@ -62,7 +61,7 @@ public static ReactiveStreamsFactory instance() { if (newInstance == null) { throw new IllegalStateException( - "No ReactiveStreamsFactory implementation found!"); + "No ReactiveStreamsFactory implementation found!"); } instance = newInstance; @@ -79,15 +78,14 @@ private static ReactiveStreamsFactory loadFromSpi(ClassLoader cl) { if (instance == null) { ServiceLoader sl = ServiceLoader.load( - ReactiveStreamsFactory.class, cl); + ReactiveStreamsFactory.class, cl); for (ReactiveStreamsFactory spi : sl) { if (instance != null) { throw new IllegalStateException( - "Multiple ReactiveStreamsFactory implementations found: " - + spi.getClass().getName() + " and " - + instance.getClass().getName()); - } - else { + "Multiple ReactiveStreamsFactory implementations found: " + + spi.getClass().getName() + " and " + + instance.getClass().getName()); + } else { instance = spi; } } @@ -96,10 +94,10 @@ private static ReactiveStreamsFactory loadFromSpi(ClassLoader cl) { } /** - * Set the instance. It is used by OSGi environment while service loader - * pattern is not supported. + * Set the instance. It is used by OSGi environment while service loader pattern is not supported. * - * @param factory set the instance. + * @param factory + * set the instance. */ public static void setInstance(ReactiveStreamsFactory factory) { instance = factory; diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/Stage.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/Stage.java index d440a9c..264c5d1 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/Stage.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/Stage.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,22 +19,21 @@ package org.eclipse.microprofile.reactive.streams.operators.spi; -import org.reactivestreams.Processor; -import org.reactivestreams.Publisher; -import org.reactivestreams.Subscriber; - import java.util.concurrent.CompletionStage; import java.util.function.Consumer; import java.util.function.Function; import java.util.function.Predicate; import java.util.stream.Collector; +import org.reactivestreams.Processor; +import org.reactivestreams.Publisher; +import org.reactivestreams.Subscriber; + /** * A stage of a Reactive Streams graph. *

- * A Reactive Streams engine will walk a graph of stages to produce {@link Publisher}, - * {@link Subscriber} and {@link Processor} instances that handle the stream - * according to the sequence of stages. + * A Reactive Streams engine will walk a graph of stages to produce {@link Publisher}, {@link Subscriber} and + * {@link Processor} instances that handle the stream according to the sequence of stages. */ public interface Stage { @@ -44,9 +43,9 @@ public interface Stage { * The given mapper function must be invoked on each element consumed, and the output of the function must be * emitted. *

- * Any {@link RuntimeException} thrown by the function must be propagated downstream as an error, and upstream - * must be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled - * must be dropped. + * Any {@link RuntimeException} thrown by the function must be propagated downstream as an error, and upstream must + * be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled must be + * dropped. */ interface Map extends Stage { /** @@ -58,14 +57,14 @@ interface Map extends Stage { } /** - * A stage returning a stream containing all the elements from this stream, - * additionally performing the provided action on each element. + * A stage returning a stream containing all the elements from this stream, additionally performing the provided + * action on each element. *

* The given consumer function must be invoked on each element consumed. *

- * Any {@link RuntimeException} thrown by the function must be propagated downstream as an error, and upstream - * must be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled - * must be dropped. + * Any {@link RuntimeException} thrown by the function must be propagated downstream as an error, and upstream must + * be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled must be + * dropped. */ interface Peek extends Stage { /** @@ -82,9 +81,9 @@ interface Peek extends Stage { * The given predicate must be invoked on each element consumed. If it returns {@code true}, the element must be * emitted, otherwise, it must be dropped. *

- * Any {@link RuntimeException} thrown by the predicate must be propagated downstream as an error, and upstream - * must be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled - * must be dropped. + * Any {@link RuntimeException} thrown by the predicate must be propagated downstream as an error, and upstream must + * be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled must be + * dropped. */ interface Filter extends Stage { /** @@ -100,15 +99,15 @@ interface Filter extends Stage { *

* The given predicate must be invoked on each element consumed, until it returns {@code true}. Each element that it * returns {@code true} for must be dropped, and once it returns {@code false}, that element that it returned - * {@code false} for, and all subsequent elements, must be emitted. The predicate must not be invoked after it returns - * {@code false} the first time. + * {@code false} for, and all subsequent elements, must be emitted. The predicate must not be invoked after it + * returns {@code false} the first time. *

* If upstream terminates for any reason before the predicate returns {@code false}, downstream must also be * terminated. *

- * Any {@link RuntimeException} thrown by the predicate must be propagated downstream as an error, and upstream - * must be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled - * must be dropped. + * Any {@link RuntimeException} thrown by the predicate must be propagated downstream as an error, and upstream must + * be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled must be + * dropped. */ interface DropWhile extends Stage { /** @@ -142,8 +141,8 @@ interface Skip extends Stage { * A limit stage. *

* Only {@code limit} elements may be emitted, once that many elements are emitted, downstream must be completed, - * and upstream must be cancelled. Any subsequent elements received from upstream before the cancellation signal - * is handled must be dropped. + * and upstream must be cancelled. Any subsequent elements received from upstream before the cancellation signal is + * handled must be dropped. *

* If less than {@code limit} elements are received before termination, then the termination must be propagated * downstream as normal. @@ -158,8 +157,8 @@ interface Limit extends Stage { } /** - * A stage returning a stream consisting of the distinct elements (according to {@link Object#equals(Object)}) of this - * stream. + * A stage returning a stream consisting of the distinct elements (according to {@link Object#equals(Object)}) of + * this stream. *

* Any {@link RuntimeException} thrown by the {@code equals} or {@code hashCode} methods of elements must be * propagated downstream as an error, and upstream must be cancelled. @@ -177,9 +176,9 @@ interface Distinct extends Stage { * The {@code predicate} must not be invoked again once it returns {@code false} for the first time. Any elements * supplied by upstream before it handles the cancellation signal must be dropped. *

- * Any {@link RuntimeException} thrown by the predicate must be propagated downstream as an error, and upstream - * must be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled - * must be dropped. + * Any {@link RuntimeException} thrown by the predicate must be propagated downstream as an error, and upstream must + * be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled must be + * dropped. */ interface TakeWhile extends Stage { /** @@ -193,8 +192,8 @@ interface TakeWhile extends Stage { /** * A publisher stage. *

- * The given {@code publisher} must be subscribed to whatever subscriber is provided to this graph, via any - * other subsequent stages. + * The given {@code publisher} must be subscribed to whatever subscriber is provided to this graph, via any other + * subsequent stages. */ interface PublisherStage extends Stage { /** @@ -211,8 +210,8 @@ interface PublisherStage extends Stage { * When built, must produce a publisher that produces all the values (until cancelled) emitted by this iterables * iterator, followed by completion of the stream. *

- * Any exceptions thrown by the iterator must be propagated downstream, or by the invocation of the - * {@code iterator} method, must be propagated downstream. + * Any exceptions thrown by the iterator must be propagated downstream, or by the invocation of the {@code iterator} + * method, must be propagated downstream. */ interface Of extends Stage { /** @@ -240,9 +239,9 @@ interface ProcessorStage extends Stage { /** * A subscriber stage that emits the first element encountered. *

- * When built, the {@link CompletionStage} must emit an {@link java.util.Optional} of the first element - * encountered. If no element is emitted before completion of the stream, it must emit an empty optional. Once - * the element has been emitted, the stream must be cancelled if not already complete. + * When built, the {@link CompletionStage} must emit an {@link java.util.Optional} of the first element encountered. + * If no element is emitted before completion of the stream, it must emit an empty optional. Once the element has + * been emitted, the stream must be cancelled if not already complete. *

* If an error is emitted before the first element is encountered, the stream must redeem the completion stage with * that error. @@ -270,8 +269,8 @@ interface SubscriberStage extends Stage { /** * A collect stage. *

- * This must use the collectors supplier to create an accumulated value, and then the accumulator BiConsumer must - * be used to accumulate the received elements in the value. Finally, the returned {@link CompletionStage} must be + * This must use the collectors supplier to create an accumulated value, and then the accumulator BiConsumer must be + * used to accumulate the received elements in the value. Finally, the returned {@link CompletionStage} must be * redeemed by value returned by the finisher function applied to the accumulated value when the stream terminates * normally, or must be redeemed with an error if the stream terminates with an error. *

@@ -290,19 +289,19 @@ interface Collect extends Stage { /** * A flat map stage. *

- * The flat map stage must execute the given mapper on each element, and concatenate the publishers emitted by - * the mapper function into the resulting stream. + * The flat map stage must execute the given mapper on each element, and concatenate the publishers emitted by the + * mapper function into the resulting stream. *

* The graph emitted by the mapper function is guaranteed to have an outlet but no inlet. *

* The engine must ensure only one publisher emitted by the mapper function is running at a time. *

- * Any {@link RuntimeException} thrown by the function must be propagated downstream as an error, and upstream - * must be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled - * must be dropped. + * Any {@link RuntimeException} thrown by the function must be propagated downstream as an error, and upstream must + * be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled must be + * dropped. *

- * If downstream cancels, then both the currently running inner publisher produced by the {@code mapper}, if one - * is currently running, and the outer upstream, must be cancelled. + * If downstream cancels, then both the currently running inner publisher produced by the {@code mapper}, if one is + * currently running, and the outer upstream, must be cancelled. *

* If the inner publisher terminates with an error, the outer publisher must be cancelled, and the error must be * propagated downstream. Any subsequent elements received from upstream before the cancellation signal is handled @@ -310,8 +309,8 @@ interface Collect extends Stage { *

* If the outer publisher terminates with an error, then implementations may cancel the inner publisher, if one is * currently running, immediately, or they may wait for the inner publisher to complete, before propagating the - * error downstream. For the purpose of failing fast, so that network failures can be detected and handled, it - * is recommended, but not required, that the inner publisher is cancelled as soon as possible. + * error downstream. For the purpose of failing fast, so that network failures can be detected and handled, it is + * recommended, but not required, that the inner publisher is cancelled as soon as possible. */ interface FlatMap extends Stage { /** @@ -326,16 +325,15 @@ interface FlatMap extends Stage { * A flat map stage that emits and flattens {@link CompletionStage}. *

* The flat map stage must execute the given mapper on each element, and concatenate the values redeemed by the - * {@link CompletionStage}'s emitted by the mapper function into the resulting stream. - * If the value is {@code null}, then no element must be emitted, and the stream should be failed with a - * {@link NullPointerException}. + * {@link CompletionStage}'s emitted by the mapper function into the resulting stream. If the value is {@code null}, + * then no element must be emitted, and the stream should be failed with a {@link NullPointerException}. *

* The engine must ensure only one mapper function is executed at a time, with the next mapper function not * executing until the {@link CompletionStage} returned by the previous mapper function has been redeemed. *

- * Any {@link RuntimeException} thrown by the function must be propagated downstream as an error, and upstream - * must be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled - * must be dropped. + * Any {@link RuntimeException} thrown by the function must be propagated downstream as an error, and upstream must + * be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled must be + * dropped. *

* If downstream cancels, then upstream must be cancelled, and if there is a currently executing * {@code CompletionStage}, its result must be ignored. @@ -346,10 +344,9 @@ interface FlatMap extends Stage { *

* If upstream terminates with an error, then implementations may decide to ignore the result of any currently * executing {@code CompletionStage}, and propagate the error immediately, or they may wait for the - * {@code CompletionStage} to be redeemed, emit its result, and then propagate the error downstream. For the - * purpose of failing fast, so that network failures can be detected and handled, it is recommended, but not - * required, that the failure is propagated downstream as soon as possible, and the result of the - * {@code CompletionStage} ignored. + * {@code CompletionStage} to be redeemed, emit its result, and then propagate the error downstream. For the purpose + * of failing fast, so that network failures can be detected and handled, it is recommended, but not required, that + * the failure is propagated downstream as soon as possible, and the result of the {@code CompletionStage} ignored. */ interface FlatMapCompletionStage extends Stage { /** @@ -363,12 +360,12 @@ interface FlatMapCompletionStage extends Stage { /** * A flat map stage that emits and fattens {@link Iterable}. *

- * The flat map stage must execute the given mapper on each element, and concatenate the iterables emitted by - * the mapper function into the resulting stream. + * The flat map stage must execute the given mapper on each element, and concatenate the iterables emitted by the + * mapper function into the resulting stream. *

- * Any {@link RuntimeException} thrown by the function must be propagated downstream as an error, and upstream - * must be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled - * must be dropped. + * Any {@link RuntimeException} thrown by the function must be propagated downstream as an error, and upstream must + * be cancelled. Any subsequent elements received from upstream before the cancellation signal is handled must be + * dropped. *

* If downstream cancels, then upstream must be cancelled, and if there is a current iterator being published, it * must no longer be consumed. The iterator must not be run through to completion in such a circumstance. @@ -379,9 +376,9 @@ interface FlatMapCompletionStage extends Stage { *

* If upstream terminates with an error, then implementations may decide to stop consuming any currently running * iterator, and propagate the error immediately, or they may run the iterator through to completion, before - * propagating the error. For the purpose of failing fast, so that network failures can be detected and handled, - * it is recommended, but not required, that the failure is propagated downstream as soon as possible, and the - * iterator not be run through to completion. + * propagating the error. For the purpose of failing fast, so that network failures can be detected and handled, it + * is recommended, but not required, that the failure is propagated downstream as soon as possible, and the iterator + * not be run through to completion. */ interface FlatMapIterable extends Stage { /** @@ -393,8 +390,8 @@ interface FlatMapIterable extends Stage { } /** - * A stage returning a stream containing all the elements from this stream, - * additionally performing the provided action if this stream conveys an error. + * A stage returning a stream containing all the elements from this stream, additionally performing the provided + * action if this stream conveys an error. *

* The given consumer function must be invoked with the conveyed failure. *

@@ -417,8 +414,8 @@ interface OnError extends Stage { * The given action cannot determine in which state the stream is (error, completed or cancelled). Use * {@link OnError} and {@link OnComplete} if you need to distinguish between these cases. *

- * The action must only be invoked once. If both upstream completes, and downstream cancels, at the same time, - * only one of those signals may trigger the invocation of action. + * The action must only be invoked once. If both upstream completes, and downstream cancels, at the same time, only + * one of those signals may trigger the invocation of action. *

* If this action is invoked as the result of an upstream completion or error, any {@link RuntimeException} thrown * by the function must be propagated downstream as an error, replacing the exception that the consumer was @@ -454,15 +451,15 @@ interface OnComplete extends Stage { /** * A stage to handle errors from upstream. It builds a stream containing all the elements from upstream. - * Additionally, in the case of failure, rather than propagating the error downstream, it invokes the given - * function method emits the result as the final event of the stream, terminating the stream after that. + * Additionally, in the case of failure, rather than propagating the error downstream, it invokes the given function + * method emits the result as the final event of the stream, terminating the stream after that. *

- * By default, when a stream encounters an error that prevents it from emitting the expected item to its - * subscriber, the stream (publisher) invokes its subscriber's onError method, and then terminates - * without invoking any more of its subscriber's methods. This operator changes this behavior. If the current - * stream encounters an error, instead of invoking its subscriber's onError method, it will instead - * emit the return value of the passed function. This operator prevents errors from propagating and allows - * supplying fallback data should errors be encountered. + * By default, when a stream encounters an error that prevents it from emitting the expected item to its subscriber, + * the stream (publisher) invokes its subscriber's onError method, and then terminates without invoking + * any more of its subscriber's methods. This operator changes this behavior. If the current stream encounters an + * error, instead of invoking its subscriber's onError method, it will instead emit the return value of + * the passed function. This operator prevents errors from propagating and allows supplying fallback data should + * errors be encountered. *

* Any {@link RuntimeException} thrown by the function must be propagated downstream as an error, replacing the * exception that the function was handling. @@ -478,16 +475,15 @@ interface OnErrorResume extends Stage { /** * A stage to handle errors from upstream. It builds a stream containing all the elements from upstream. - * Additionally, in the case of failure, rather than propagating the error downstream, it invokes the given - * function and switches control to the returned stream. + * Additionally, in the case of failure, rather than propagating the error downstream, it invokes the given function + * and switches control to the returned stream. *

- * By default, when a stream encounters an error that prevents it from emitting the expected item to its - * subscriber, the stream (publisher) invokes its subscriber's onError method, and then terminates - * without invoking any more of its subscriber's methods. This operator changes this behavior. If the current - * stream encounters an error, instead of invoking its subscriber's onError method, it will instead - * relinquish control to the {@code PublisherBuilder} returned from - * given function. In such a case, because no publisher necessarily invokes onError, the subscriber - * may never know that an error happened. + * By default, when a stream encounters an error that prevents it from emitting the expected item to its subscriber, + * the stream (publisher) invokes its subscriber's onError method, and then terminates without invoking + * any more of its subscriber's methods. This operator changes this behavior. If the current stream encounters an + * error, instead of invoking its subscriber's onError method, it will instead relinquish control to + * the {@code PublisherBuilder} returned from given function. In such a case, because no publisher necessarily + * invokes onError, the subscriber may never know that an error happened. *

* Any elements emitted by the returned publisher must be sent downstream, in addition to its completion and error * signals. If the returned publisher completes with an error, that error must not result in the recovery function @@ -524,13 +520,14 @@ interface Failed extends Stage { *

* Each graph must have an outlet and no inlet. *

- * The resulting publisher produced by the concat stage must emit all the elements from the first graph, - * and once that graph emits a completion signal, it must then subscribe to and emit all the elements from - * the second. If an error is emitted by the either graph, the error must be emitted from the resulting stream. + * The resulting publisher produced by the concat stage must emit all the elements from the first graph, and once + * that graph emits a completion signal, it must then subscribe to and emit all the elements from the second. If an + * error is emitted by the either graph, the error must be emitted from the resulting stream. *

* If processing terminates early while the first graph is still emitting, either due to that graph emitting an - * error, or due to a cancellation signal from downstream, then the second graph must be subscribed to and cancelled. - * This is to ensure that any hot publishers holding onto resources that may be backing the graphs are cleaned up. + * error, or due to a cancellation signal from downstream, then the second graph must be subscribed to and + * cancelled. This is to ensure that any hot publishers holding onto resources that may be backing the graphs are + * cleaned up. */ interface Concat extends Stage { /** @@ -561,14 +558,14 @@ interface Cancel extends Stage { /** * A publisher representation of a {@link CompletionStage}. *

- * This stage must emit the value produced by the {@code CompletionStage}, then immediately complete the stream. - * If the value is {@code null}, then no element must be emitted, and the stream should be failed with a + * This stage must emit the value produced by the {@code CompletionStage}, then immediately complete the stream. If + * the value is {@code null}, then no element must be emitted, and the stream should be failed with a * {@link NullPointerException}. If the {@code CompletionStage} is redeemed with a failure, the stream must be * failed with that failure. *

* If the stream is cancelled by downstream before the {@code CompletionStage} has been redeemed, then this stage - * must do nothing. It must not cancel the {@code CompletionStage} (since {@code CompletionStage} offers no API - * for cancellation), and it must not emit any further signals when the {@code CompletionStage} is redeemed. + * must do nothing. It must not cancel the {@code CompletionStage} (since {@code CompletionStage} offers no API for + * cancellation), and it must not emit any further signals when the {@code CompletionStage} is redeemed. */ interface FromCompletionStage extends Stage { /** @@ -582,13 +579,13 @@ interface FromCompletionStage extends Stage { /** * A publisher representation of a {@link CompletionStage}. *

- * This stage must emit the value produced by the {@code CompletionStage}, then immediately complete the stream. - * If the value is {@code null}, then no element must be emitted, and the stream must be immediately completed. - * If the {@code CompletionStage} is redeemed with a failure, the stream must be failed with that failure. + * This stage must emit the value produced by the {@code CompletionStage}, then immediately complete the stream. If + * the value is {@code null}, then no element must be emitted, and the stream must be immediately completed. If the + * {@code CompletionStage} is redeemed with a failure, the stream must be failed with that failure. *

* If the stream is cancelled by downstream before the {@code CompletionStage} has been redeemed, then this stage - * must do nothing. It must not cancel the {@code CompletionStage} (since {@code CompletionStage} offers no API - * for cancellation), and it must not emit any further signals when the {@code CompletionStage} is redeemed. + * must do nothing. It must not cancel the {@code CompletionStage} (since {@code CompletionStage} offers no API for + * cancellation), and it must not emit any further signals when the {@code CompletionStage} is redeemed. */ interface FromCompletionStageNullable extends Stage { /** @@ -605,8 +602,8 @@ interface FromCompletionStageNullable extends Stage { * The resulting stage sends all the elements received to the passed in subscriber, and emits all the elements * received from the passed in publisher. *

- * In addition, the lifecycles of the subscriber and publisher are coupled, such that if one terminates or - * receives a termination signal, the other will be terminated. Below is a table of what signals are emited when: + * In addition, the lifecycles of the subscriber and publisher are coupled, such that if one terminates or receives + * a termination signal, the other will be terminated. Below is a table of what signals are emited when: *

* * diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/SubscriberWithCompletionStage.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/SubscriberWithCompletionStage.java index 3009079..5192ba4 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/SubscriberWithCompletionStage.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/SubscriberWithCompletionStage.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,14 +19,17 @@ package org.eclipse.microprofile.reactive.streams.operators.spi; -import org.reactivestreams.Subscriber; import java.util.concurrent.CompletionStage; +import org.reactivestreams.Subscriber; + /** * A subscriber and completion stage pair. * - * @param The type of the elements that the subscriber consumes. - * @param The type of the result that the subscriber emits. + * @param + * The type of the elements that the subscriber consumes. + * @param + * The type of the result that the subscriber emits. */ public interface SubscriberWithCompletionStage { diff --git a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/package-info.java b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/package-info.java index 960cddb..a83e807 100644 --- a/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/package-info.java +++ b/api/src/main/java/org/eclipse/microprofile/reactive/streams/operators/spi/package-info.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018, 2020 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -20,11 +20,11 @@ /** * The Reactive Streams utils SPI. * - * Implementors are expected to implement the {@code ReactiveStreamsEngine} interface, and use this SPI to inspect - * the graph of stages. + * Implementors are expected to implement the {@code ReactiveStreamsEngine} interface, and use this SPI to inspect the + * graph of stages. * - * A TCK is also provided that validates that an implementation is both correct according to this specification, and - * the Reactive Streams specification. + * A TCK is also provided that validates that an implementation is both correct according to this specification, and the + * Reactive Streams specification. */ @org.osgi.annotation.versioning.Version("1.0") package org.eclipse.microprofile.reactive.streams.operators.spi; diff --git a/api/src/main/javadoc/licenses/Draft/license.html b/api/src/main/javadoc/licenses/Draft/license.html deleted file mode 100644 index 994b5f8..0000000 --- a/api/src/main/javadoc/licenses/Draft/license.html +++ /dev/null @@ -1,27 +0,0 @@ - - -Apache License - Version 2 - - -

Apache License - Version 2

-

-Copyright (c) ${inceptionYear}-${currentYear} Contributors to the Eclipse Foundation -

-

-Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at -

-

- - http://www.apache.org/licenses/LICENSE-2.0 -

-

-Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -

- - \ No newline at end of file diff --git a/api/src/main/javadoc/licenses/Final/license.html b/api/src/main/javadoc/licenses/Final/license.html deleted file mode 100644 index be52b4f..0000000 --- a/api/src/main/javadoc/licenses/Final/license.html +++ /dev/null @@ -1,72 +0,0 @@ - - -Eclipse Foundation Specification License - v1.0 - - -

Eclipse Foundation Specification License - v1.0

-

By using and/or copying this document, or the Eclipse Foundation - document from which this statement is linked, you (the licensee) agree - that you have read, understood, and will comply with the following - terms and conditions:

- -

Permission to copy, and distribute the contents of this document, or - the Eclipse Foundation document from which this statement is linked, in - any medium for any purpose and without fee or royalty is hereby - granted, provided that you include the following on ALL copies of the - document, or portions thereof, that you use:

- -
    -
  • link or URL to the original Eclipse Foundation document.
    • -
  • All existing copyright notices, or if one does not exist, a notice - (hypertext is preferred, but a textual representation is permitted) - of the form: "Copyright © [$date-of-document] - “Eclipse Foundation, Inc. <<url to this license>> - " -
    • -
- -

Inclusion of the full text of this NOTICE must be provided. We - request that authorship attribution be provided in any software, - documents, or other items or products that you create pursuant to the - implementation of the contents of this document, or any portion - thereof.

- -

No right to create modifications or derivatives of Eclipse Foundation - documents is granted pursuant to this license, except anyone may - prepare and distribute derivative works and portions of this document - in software that implements the specification, in supporting materials - accompanying such software, and in documentation of such software, - PROVIDED that all such works include the notice below. HOWEVER, the - publication of derivative works of this document for use as a technical - specification is expressly prohibited.

- -

The notice is:

- -

"Copyright © [$date-of-document] Eclipse Foundation. This software or - document includes material copied from or derived from [title and URI - of the Eclipse Foundation specification document]."

- -

Disclaimers

- -

THIS DOCUMENT IS PROVIDED "AS IS," AND THE COPYRIGHT - HOLDERS AND THE ECLIPSE FOUNDATION MAKE NO REPRESENTATIONS OR - WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, - WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, - NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE - SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS - WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR - OTHER RIGHTS.

- -

THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION WILL NOT BE LIABLE - FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT - OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE - CONTENTS THEREOF.

- -

The name and trademarks of the copyright holders or the Eclipse - Foundation may NOT be used in advertising or publicity pertaining to - this document or its contents without specific, written prior - permission. Title to copyright in this document will at all times - remain with copyright holders.

- - - diff --git a/api/src/main/resources/META-INF/NOTICE b/api/src/main/resources/META-INF/NOTICE new file mode 100644 index 0000000..d6ab672 --- /dev/null +++ b/api/src/main/resources/META-INF/NOTICE @@ -0,0 +1,19 @@ +========================================================================= +== NOTICE file corresponding to section 4(d) of the Apache License, == +== Version 2.0, MicroProfile Reactive Streams Operators == +========================================================================= + +This product includes software developed at +The Apache Software Foundation (http://www.apache.org/). + + +SPDXVersion: SPDX-2.1 +PackageName: Eclipse Microprofile +PackageHomePage: http://www.eclipse.org/microprofile +PackageLicenseDeclared: Apache-2.0 + +PackageCopyrightText: +James Roper james@lightbend.com +Clement Escoffier clement.escoffier@redhat.com +Gordon Hutchison gordon_hutchison@uk.ibm.com + \ No newline at end of file diff --git a/core/pom.xml b/core/pom.xml index 11d4cad..b3d113e 100644 --- a/core/pom.xml +++ b/core/pom.xml @@ -1,6 +1,6 @@ org.eclipse.microprofile.reactive-streams-operators microprofile-reactive-streams-operators-parent - 2.1-SNAPSHOT + 3.0-SNAPSHOT @@ -49,94 +49,4 @@ - - - - org.apache.maven.plugins - maven-javadoc-plugin - - - attach-javadocs - - jar - - - - - - org.apache.maven.plugins - maven-source-plugin - - - attach-sources - - jar - - - - - - biz.aQute.bnd - bnd-maven-plugin - 3.4.0 - - - - - bnd-process - - - - - - org.apache.maven.plugins - maven-jar-plugin - - - ${project.build.outputDirectory}/META-INF/MANIFEST.MF - - - - - biz.aQute.bnd - bnd-baseline-maven-plugin - 3.5.0 - - - 1.0.1 - - - - - baseline - - baseline - - - - - - - - - - eclipse-jarsigner - - - - org.eclipse.cbi.maven.plugins - eclipse-jarsigner-plugin - - - - sign - - - - - - - - - diff --git a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/CompletionRunnerImpl.java b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/CompletionRunnerImpl.java index 81a33ca..50c1717 100644 --- a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/CompletionRunnerImpl.java +++ b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/CompletionRunnerImpl.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,13 +19,13 @@ package org.eclipse.microprofile.reactive.streams.operators.core; +import java.util.Objects; +import java.util.concurrent.CompletionStage; + import org.eclipse.microprofile.reactive.streams.operators.CompletionRunner; import org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine; import org.eclipse.microprofile.reactive.streams.operators.spi.Stage; -import java.util.Objects; -import java.util.concurrent.CompletionStage; - final class CompletionRunnerImpl extends ReactiveStreamsGraphBuilder implements CompletionRunner { CompletionRunnerImpl(Stage stage, ReactiveStreamsGraphBuilder previous) { diff --git a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/GraphImpl.java b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/GraphImpl.java index 1908751..58553f3 100644 --- a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/GraphImpl.java +++ b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/GraphImpl.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,11 +19,11 @@ package org.eclipse.microprofile.reactive.streams.operators.core; +import java.util.Collection; + import org.eclipse.microprofile.reactive.streams.operators.spi.Graph; import org.eclipse.microprofile.reactive.streams.operators.spi.Stage; -import java.util.Collection; - final class GraphImpl implements Graph { private final Collection stages; @@ -34,7 +34,8 @@ final class GraphImpl implements Graph { * {@link org.reactivestreams.Subscriber}. If the last stage has an outlet, then this graph has an outlet, and * therefore can be represented as a {@link org.reactivestreams.Publisher}. * - * @param stages The stages. + * @param stages + * The stages. */ GraphImpl(Collection stages) { this.stages = stages; @@ -48,7 +49,7 @@ public Collection getStages() { @Override public String toString() { return "Graph{" + - "stages=" + stages + - '}'; + "stages=" + stages + + '}'; } } diff --git a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/InternalStages.java b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/InternalStages.java index 26fc949..b6d7591 100644 --- a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/InternalStages.java +++ b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/InternalStages.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,18 +19,18 @@ package org.eclipse.microprofile.reactive.streams.operators.core; +import java.util.Objects; + import org.eclipse.microprofile.reactive.streams.operators.spi.Graph; import org.eclipse.microprofile.reactive.streams.operators.spi.Stage; import org.eclipse.microprofile.reactive.streams.operators.spi.ToGraphable; -import java.util.Objects; - /** * Internal stages, used to capture the graph while being built, but never passed to a - * {@link org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine}. These exist for performance reasons, - * allowing the builder to hold the graph as an immutable linked tree where multiple stages can be appended in constant - * time, rather than needing to copy an array each time. However, when it comes to building the graph, it is first - * flattened out to an array, removing any of the internal stages that held nested stages, etc. + * {@link org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine}. These exist for performance + * reasons, allowing the builder to hold the graph as an immutable linked tree where multiple stages can be appended in + * constant time, rather than needing to copy an array each time. However, when it comes to building the graph, it is + * first flattened out to an array, removing any of the internal stages that held nested stages, etc. */ class InternalStages { @@ -90,13 +90,11 @@ static InternalStage nested(Object object) { Objects.requireNonNull(object); if (object instanceof ReactiveStreamsGraphBuilder) { return new Nested((ReactiveStreamsGraphBuilder) object); - } - else if (object instanceof ToGraphable) { + } else if (object instanceof ToGraphable) { return new NestedGraph(((ToGraphable) object).toGraph()); - } - else { + } else { throw new IllegalArgumentException("The passed in builder does not implement " + ToGraphable.class + - " and so can't be added to this graph"); + " and so can't be added to this graph"); } } } diff --git a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ProcessorBuilderImpl.java b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ProcessorBuilderImpl.java index 83680e1..e2d830d 100644 --- a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ProcessorBuilderImpl.java +++ b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ProcessorBuilderImpl.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,15 +19,6 @@ package org.eclipse.microprofile.reactive.streams.operators.core; -import org.eclipse.microprofile.reactive.streams.operators.ProcessorBuilder; -import org.eclipse.microprofile.reactive.streams.operators.PublisherBuilder; -import org.eclipse.microprofile.reactive.streams.operators.SubscriberBuilder; -import org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine; -import org.eclipse.microprofile.reactive.streams.operators.spi.Stage; -import org.reactivestreams.Processor; -import org.reactivestreams.Publisher; -import org.reactivestreams.Subscriber; - import java.util.List; import java.util.Objects; import java.util.Optional; @@ -41,6 +32,15 @@ import java.util.stream.Collector; import java.util.stream.Collectors; +import org.eclipse.microprofile.reactive.streams.operators.ProcessorBuilder; +import org.eclipse.microprofile.reactive.streams.operators.PublisherBuilder; +import org.eclipse.microprofile.reactive.streams.operators.SubscriberBuilder; +import org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine; +import org.eclipse.microprofile.reactive.streams.operators.spi.Stage; +import org.reactivestreams.Processor; +import org.reactivestreams.Publisher; +import org.reactivestreams.Subscriber; + final class ProcessorBuilderImpl extends ReactiveStreamsGraphBuilder implements ProcessorBuilder { ProcessorBuilderImpl(Stage stage, ReactiveStreamsGraphBuilder previous) { @@ -78,7 +78,8 @@ public ProcessorBuilder flatMapRsPublisher(Function ProcessorBuilder flatMapCompletionStage(Function> mapper) { + public ProcessorBuilder flatMapCompletionStage( + Function> mapper) { return addStage(new Stages.FlatMapCompletionStage((Function) mapper)); } @@ -111,11 +112,10 @@ public ProcessorBuilder dropWhile(Predicate predicate) { public SubscriberBuilder forEach(Consumer action) { Objects.requireNonNull(action, "Action must not be null"); return collect(Collector.of( - () -> null, - (n, r) -> action.accept(r), - (v1, v2) -> null, - v -> null - )); + () -> null, + (n, r) -> action.accept(r), + (v1, v2) -> null, + v -> null)); } @Override @@ -181,13 +181,17 @@ public ProcessorBuilder onErrorResume(Function err } @Override - public ProcessorBuilder onErrorResumeWith(Function> errorHandler) { - return addStage(new Stages.OnErrorResumeWith(errorHandler.andThen(ReactiveStreamsGraphBuilder::rsBuilderToGraph))); + public ProcessorBuilder onErrorResumeWith( + Function> errorHandler) { + return addStage( + new Stages.OnErrorResumeWith(errorHandler.andThen(ReactiveStreamsGraphBuilder::rsBuilderToGraph))); } @Override - public ProcessorBuilder onErrorResumeWithRsPublisher(Function> errorHandler) { - return addStage(new Stages.OnErrorResumeWith(errorHandler.andThen(ReactiveStreamsGraphBuilder::publisherToGraph))); + public ProcessorBuilder onErrorResumeWithRsPublisher( + Function> errorHandler) { + return addStage( + new Stages.OnErrorResumeWith(errorHandler.andThen(ReactiveStreamsGraphBuilder::publisherToGraph))); } @Override diff --git a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/PublisherBuilderImpl.java b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/PublisherBuilderImpl.java index 270d959..2935960 100644 --- a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/PublisherBuilderImpl.java +++ b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/PublisherBuilderImpl.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,16 +19,6 @@ package org.eclipse.microprofile.reactive.streams.operators.core; -import org.eclipse.microprofile.reactive.streams.operators.CompletionRunner; -import org.eclipse.microprofile.reactive.streams.operators.ProcessorBuilder; -import org.eclipse.microprofile.reactive.streams.operators.PublisherBuilder; -import org.eclipse.microprofile.reactive.streams.operators.SubscriberBuilder; -import org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine; -import org.eclipse.microprofile.reactive.streams.operators.spi.Stage; -import org.reactivestreams.Processor; -import org.reactivestreams.Publisher; -import org.reactivestreams.Subscriber; - import java.util.List; import java.util.Objects; import java.util.Optional; @@ -42,6 +32,16 @@ import java.util.stream.Collector; import java.util.stream.Collectors; +import org.eclipse.microprofile.reactive.streams.operators.CompletionRunner; +import org.eclipse.microprofile.reactive.streams.operators.ProcessorBuilder; +import org.eclipse.microprofile.reactive.streams.operators.PublisherBuilder; +import org.eclipse.microprofile.reactive.streams.operators.SubscriberBuilder; +import org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine; +import org.eclipse.microprofile.reactive.streams.operators.spi.Stage; +import org.reactivestreams.Processor; +import org.reactivestreams.Publisher; +import org.reactivestreams.Subscriber; + final class PublisherBuilderImpl extends ReactiveStreamsGraphBuilder implements PublisherBuilder { PublisherBuilderImpl(Stage stage, ReactiveStreamsGraphBuilder previous) { @@ -83,7 +83,8 @@ public PublisherBuilder flatMapRsPublisher(Function PublisherBuilder flatMapCompletionStage(Function> mapper) { + public PublisherBuilder flatMapCompletionStage( + Function> mapper) { return addStage(new Stages.FlatMapCompletionStage((Function) mapper)); } @@ -116,11 +117,10 @@ public PublisherBuilder dropWhile(Predicate predicate) { public CompletionRunner forEach(Consumer action) { Objects.requireNonNull(action, "Action must not be null"); return collect(Collector.of( - () -> null, - (n, t) -> action.accept(t), - (v1, v2) -> null, - v -> null - )); + () -> null, + (n, t) -> action.accept(t), + (v1, v2) -> null, + v -> null)); } @Override @@ -197,13 +197,17 @@ public PublisherBuilder onErrorResume(Function errorH } @Override - public PublisherBuilder onErrorResumeWith(Function> errorHandler) { - return addStage(new Stages.OnErrorResumeWith(errorHandler.andThen(ReactiveStreamsGraphBuilder::rsBuilderToGraph))); + public PublisherBuilder onErrorResumeWith( + Function> errorHandler) { + return addStage( + new Stages.OnErrorResumeWith(errorHandler.andThen(ReactiveStreamsGraphBuilder::rsBuilderToGraph))); } @Override - public PublisherBuilder onErrorResumeWithRsPublisher(Function> errorHandler) { - return addStage(new Stages.OnErrorResumeWith(errorHandler.andThen(ReactiveStreamsGraphBuilder::publisherToGraph))); + public PublisherBuilder onErrorResumeWithRsPublisher( + Function> errorHandler) { + return addStage( + new Stages.OnErrorResumeWith(errorHandler.andThen(ReactiveStreamsGraphBuilder::publisherToGraph))); } @Override diff --git a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ReactiveStreamsEngineResolver.java b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ReactiveStreamsEngineResolver.java index 83130dd..bf0ab7e 100644 --- a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ReactiveStreamsEngineResolver.java +++ b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ReactiveStreamsEngineResolver.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -18,19 +18,18 @@ ******************************************************************************/ package org.eclipse.microprofile.reactive.streams.operators.core; -import org.eclipse.microprofile.reactive.streams.operators.ReactiveStreams; -import org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine; - import java.security.AccessController; import java.security.PrivilegedAction; import java.util.ServiceLoader; +import org.eclipse.microprofile.reactive.streams.operators.ReactiveStreams; +import org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine; + /** - * This class is not intended to be used by end-users but for - * portable container integration purpose only. + * This class is not intended to be used by end-users but for portable container integration purpose only. *

- * Service provider for ReactiveStreamsEngine. The implementation registers - * itself via the {@link ServiceLoader} mechanism. + * Service provider for ReactiveStreamsEngine. The implementation registers itself via the {@link ServiceLoader} + * mechanism. */ public class ReactiveStreamsEngineResolver { @@ -41,8 +40,7 @@ protected ReactiveStreamsEngineResolver() { private static volatile ReactiveStreamsEngine instance = null; /** - * Creates a ReactiveStreamsFactory object - * Only used internally from within {@link ReactiveStreams} + * Creates a ReactiveStreamsFactory object Only used internally from within {@link ReactiveStreams} * * @return ReactiveStreamsFactory an instance of ReactiveStreamsFactory */ @@ -53,7 +51,8 @@ public static ReactiveStreamsEngine instance() { return instance; } - ClassLoader cl = AccessController.doPrivileged((PrivilegedAction) () -> Thread.currentThread().getContextClassLoader()); + ClassLoader cl = AccessController.doPrivileged( + (PrivilegedAction) () -> Thread.currentThread().getContextClassLoader()); if (cl == null) { cl = ReactiveStreamsEngine.class.getClassLoader(); } @@ -62,7 +61,7 @@ public static ReactiveStreamsEngine instance() { if (newInstance == null) { throw new IllegalStateException( - "No ReactiveStreamsEngine implementation found!"); + "No ReactiveStreamsEngine implementation found!"); } instance = newInstance; @@ -78,15 +77,14 @@ private static ReactiveStreamsEngine loadFromSpi(ClassLoader cl) { } if (instance == null) { ServiceLoader sl = ServiceLoader.load( - ReactiveStreamsEngine.class, cl); + ReactiveStreamsEngine.class, cl); for (ReactiveStreamsEngine spi : sl) { if (instance != null) { throw new IllegalStateException( - "Multiple ReactiveStreamsEngine implementations found: " - + spi.getClass().getName() + " and " - + instance.getClass().getName()); - } - else { + "Multiple ReactiveStreamsEngine implementations found: " + + spi.getClass().getName() + " and " + + instance.getClass().getName()); + } else { instance = spi; } } @@ -95,10 +93,10 @@ private static ReactiveStreamsEngine loadFromSpi(ClassLoader cl) { } /** - * Set the instance. It is used by OSGi environment while service loader - * pattern is not supported. + * Set the instance. It is used by OSGi environment while service loader pattern is not supported. * - * @param factory set the instance. + * @param factory + * set the instance. */ public static void setInstance(ReactiveStreamsEngine factory) { instance = factory; diff --git a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ReactiveStreamsFactoryImpl.java b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ReactiveStreamsFactoryImpl.java index 365f9eb..036f2ff 100644 --- a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ReactiveStreamsFactoryImpl.java +++ b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ReactiveStreamsFactoryImpl.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018, 2020 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,6 +19,14 @@ package org.eclipse.microprofile.reactive.streams.operators.core; +import java.util.Arrays; +import java.util.Collections; +import java.util.Objects; +import java.util.concurrent.CompletionStage; +import java.util.function.Supplier; +import java.util.function.UnaryOperator; +import java.util.stream.Stream; + import org.eclipse.microprofile.reactive.streams.operators.ProcessorBuilder; import org.eclipse.microprofile.reactive.streams.operators.PublisherBuilder; import org.eclipse.microprofile.reactive.streams.operators.ReactiveStreamsFactory; @@ -28,14 +36,6 @@ import org.reactivestreams.Publisher; import org.reactivestreams.Subscriber; -import java.util.Arrays; -import java.util.Collections; -import java.util.Objects; -import java.util.concurrent.CompletionStage; -import java.util.function.Supplier; -import java.util.function.UnaryOperator; -import java.util.stream.Stream; - public class ReactiveStreamsFactoryImpl implements ReactiveStreamsFactory { @Override @@ -46,7 +46,7 @@ public PublisherBuilder fromPublisher(Publisher publisher) { @Override public PublisherBuilder of(T t) { return new PublisherBuilderImpl<>(new Stages.Of(Collections.singletonList( - Objects.requireNonNull(t, "Reactive Streams does not support null elements")))); + Objects.requireNonNull(t, "Reactive Streams does not support null elements")))); } @Override @@ -103,11 +103,10 @@ public PublisherBuilder generate(Supplier s) { @Override public PublisherBuilder concat(PublisherBuilder a, - PublisherBuilder b) { + PublisherBuilder b) { return new PublisherBuilderImpl<>(new Stages.Concat( - ReactiveStreamsGraphBuilder.rsBuilderToGraph(a), - ReactiveStreamsGraphBuilder.rsBuilderToGraph(b) - )); + ReactiveStreamsGraphBuilder.rsBuilderToGraph(a), + ReactiveStreamsGraphBuilder.rsBuilderToGraph(b))); } @Override @@ -122,11 +121,11 @@ public PublisherBuilder fromCompletionStageNullable(CompletionStage ProcessorBuilder coupled(SubscriberBuilder subscriber, - PublisherBuilder publisher) { + PublisherBuilder publisher) { Graph sGraph = ReactiveStreamsGraphBuilder.rsBuilderToGraph(Objects.requireNonNull(subscriber, - "Subscriber must not be null")); + "Subscriber must not be null")); Graph pGraph = ReactiveStreamsGraphBuilder.rsBuilderToGraph(Objects.requireNonNull(publisher, - "Publisher must not be null")); + "Publisher must not be null")); return new ProcessorBuilderImpl<>(new Stages.Coupled(sGraph, pGraph), null); } diff --git a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ReactiveStreamsGraphBuilder.java b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ReactiveStreamsGraphBuilder.java index 12885c6..3323d5c 100644 --- a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ReactiveStreamsGraphBuilder.java +++ b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/ReactiveStreamsGraphBuilder.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,13 +19,13 @@ package org.eclipse.microprofile.reactive.streams.operators.core; +import java.util.*; + import org.eclipse.microprofile.reactive.streams.operators.spi.Graph; import org.eclipse.microprofile.reactive.streams.operators.spi.Stage; import org.eclipse.microprofile.reactive.streams.operators.spi.ToGraphable; import org.reactivestreams.Publisher; -import java.util.*; - /** * Builds graphs of reactive streams. */ @@ -51,25 +51,21 @@ private void flatten(Deque stages) { while (thisStage != null) { if (thisStage.stage == InternalStages.Identity.INSTANCE) { // Ignore, no need to add an identity stage - } - else if (thisStage.stage instanceof InternalStages.Nested) { + } else if (thisStage.stage instanceof InternalStages.Nested) { ((InternalStages.Nested) thisStage.stage).getBuilder().flatten(stages); - } - else if (thisStage.stage instanceof InternalStages.NestedGraph) { + } else if (thisStage.stage instanceof InternalStages.NestedGraph) { // need to prepend to front in reverse order Collection nestedStages = ((InternalStages.NestedGraph) thisStage.stage).getGraph().getStages(); ListIterator iter; if (nestedStages instanceof List) { iter = ((List) nestedStages).listIterator(nestedStages.size()); - } - else { + } else { iter = new ArrayList<>(nestedStages).listIterator(nestedStages.size()); } while (iter.hasPrevious()) { stages.addFirst(iter.previous()); } - } - else { + } else { stages.addFirst(thisStage.stage); } thisStage = thisStage.previous; @@ -80,10 +76,9 @@ static Graph rsBuilderToGraph(Object obj) { Objects.requireNonNull(obj); if (obj instanceof ToGraphable) { return (((ToGraphable) obj).toGraph()); - } - else { + } else { throw new IllegalArgumentException(obj + " is not an instance of ToGraphable and so can't participate " + - "in this graph"); + "in this graph"); } } diff --git a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/Reductions.java b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/Reductions.java index 580bb29..ffde4cc 100644 --- a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/Reductions.java +++ b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/Reductions.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -35,36 +35,31 @@ private Reductions() { static Collector> reduce(BinaryOperator reducer) { Objects.requireNonNull(reducer, "Reduction function must not be null"); return Collector.of(Reduction::new, - (r, t) -> { - if (r.value == null) { - r.value = t; - } - else { - r.value = reducer.apply(r.value, t); - } - }, - (r, s) -> { - if (r.value == null) { - return r.replace(s.value); - } - else if (s.value != null) { - return r.replace(reducer.apply(r.value, s.value)); - } - else { - return r; - } - }, - r -> Optional.ofNullable(r.value) - ); + (r, t) -> { + if (r.value == null) { + r.value = t; + } else { + r.value = reducer.apply(r.value, t); + } + }, + (r, s) -> { + if (r.value == null) { + return r.replace(s.value); + } else if (s.value != null) { + return r.replace(reducer.apply(r.value, s.value)); + } else { + return r; + } + }, + r -> Optional.ofNullable(r.value)); } static Collector reduce(T identity, BinaryOperator reducer) { Objects.requireNonNull(reducer, "Reduction function must not be null"); return Collector.of(() -> new Reduction<>(identity), - (r, t) -> r.value = reducer.apply(r.value, t), - (r, s) -> r.replace(reducer.apply(r.value, s.value)), - r -> r.value - ); + (r, t) -> r.value = reducer.apply(r.value, t), + (r, s) -> r.replace(reducer.apply(r.value, s.value)), + r -> r.value); } private static class Reduction { diff --git a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/Stages.java b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/Stages.java index b1b53e6..16cce4b 100644 --- a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/Stages.java +++ b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/Stages.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,12 +19,6 @@ package org.eclipse.microprofile.reactive.streams.operators.core; -import org.eclipse.microprofile.reactive.streams.operators.spi.Graph; -import org.eclipse.microprofile.reactive.streams.operators.spi.Stage; -import org.reactivestreams.Processor; -import org.reactivestreams.Publisher; -import org.reactivestreams.Subscriber; - import java.util.Collections; import java.util.Objects; import java.util.concurrent.CompletionStage; @@ -33,6 +27,12 @@ import java.util.function.Predicate; import java.util.stream.Collector; +import org.eclipse.microprofile.reactive.streams.operators.spi.Graph; +import org.eclipse.microprofile.reactive.streams.operators.spi.Stage; +import org.reactivestreams.Processor; +import org.reactivestreams.Publisher; +import org.reactivestreams.Subscriber; + /** * Implementations of stages. */ @@ -128,7 +128,6 @@ private Distinct() { } } - final static class TakeWhile implements Stage.TakeWhile { private final Predicate predicate; @@ -287,7 +286,7 @@ public Runnable getAction() { final static class OnErrorResume implements Stage.OnErrorResume { private final Function function; - OnErrorResume(Function function) { + OnErrorResume(Function function) { this.function = Objects.requireNonNull(function, "Resume function must not be null"); } diff --git a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/SubscriberBuilderImpl.java b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/SubscriberBuilderImpl.java index 66c7a4b..ebdce20 100644 --- a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/SubscriberBuilderImpl.java +++ b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/SubscriberBuilderImpl.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2018 Contributors to the Eclipse Foundation + * Copyright (c) 2018, 2022 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. @@ -19,14 +19,14 @@ package org.eclipse.microprofile.reactive.streams.operators.core; +import java.util.Objects; + import org.eclipse.microprofile.reactive.streams.operators.CompletionSubscriber; import org.eclipse.microprofile.reactive.streams.operators.SubscriberBuilder; import org.eclipse.microprofile.reactive.streams.operators.spi.ReactiveStreamsEngine; import org.eclipse.microprofile.reactive.streams.operators.spi.Stage; import org.eclipse.microprofile.reactive.streams.operators.spi.SubscriberWithCompletionStage; -import java.util.Objects; - public final class SubscriberBuilderImpl extends ReactiveStreamsGraphBuilder implements SubscriberBuilder { SubscriberBuilderImpl(Stage stage, ReactiveStreamsGraphBuilder previous) { @@ -42,6 +42,7 @@ public CompletionSubscriber build() { public CompletionSubscriber build(ReactiveStreamsEngine engine) { Objects.requireNonNull(engine, "Engine must not be null"); SubscriberWithCompletionStage subscriberWithCompletionStage = engine.buildSubscriber(toGraph()); - return CompletionSubscriber.of(subscriberWithCompletionStage.getSubscriber(), subscriberWithCompletionStage.getCompletion()); + return CompletionSubscriber.of(subscriberWithCompletionStage.getSubscriber(), + subscriberWithCompletionStage.getCompletion()); } } diff --git a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/package-info.java b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/package-info.java index 936ef43..fa45e38 100644 --- a/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/package-info.java +++ b/core/src/main/java/org/eclipse/microprofile/reactive/streams/operators/core/package-info.java @@ -1,20 +1,16 @@ /******************************************************************************* - * Copyright (c) 2020 Contributors to the Eclipse Foundation + * Copyright (c) 2020, 2022 Contributors to the Eclipse Foundation * - * See the NOTICE file(s) distributed with this work for additional - * information regarding copyright ownership. + * See the NOTICE file(s) distributed with this work for additional information regarding copyright ownership. * - * Licensed under the Apache License, Version 2.0 (the "License"); - * You may not use this file except in compliance with the License. - * You may obtain a copy of the License at + * Licensed under the Apache License, Version 2.0 (the "License"); You may not use this file except in compliance with + * the License. You may obtain a copy of the License at * - * http://www.apache.org/licenses/LICENSE-2.0 + * http://www.apache.org/licenses/LICENSE-2.0 * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. + * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on + * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the + * specific language governing permissions and limitations under the License. ******************************************************************************/ @org.osgi.annotation.versioning.Version("1.0") diff --git a/mp_checkstyle_rules.xml b/mp_checkstyle_rules.xml deleted file mode 100644 index df0e16c..0000000 --- a/mp_checkstyle_rules.xml +++ /dev/null @@ -1,93 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/pom.xml b/pom.xml index 93b5bb5..3af8eef 100644 --- a/pom.xml +++ b/pom.xml @@ -1,6 +1,6 @@ - false - - false - Draft - 2018 - - - - - Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0.txt - repo - A business-friendly OSS license - - - - - Eclipse Foundation - http://www.eclipse.org/ - - - - GitHub - https://github.com/eclipse/microprofile-reactive/issues - - James Roper @@ -124,264 +96,6 @@ 1.0.0 provided - - org.jboss.arquillian - arquillian-bom - 1.1.15.Final - import - pom - - - org.testng - testng - 6.11 - - - jakarta.enterprise - jakarta.enterprise.cdi-api - 2.0.2 - - - jakarta.el - jakarta.el-api - - - jakarta.ejb - jakarta.ejb-api - - - - - - - repo.eclipse.org - Project Repository - Releases - https://repo.eclipse.org/content/groups/cbi/ - - - microprofile.repo.eclipse.org - Microprofile Project Repository - Releases - https://repo.eclipse.org/content/groups/microprofile/ - - - - - - - - org.apache.maven.plugins - maven-release-plugin - 2.5.3 - - true - true - false - ${arguments} -Prelease -Drevremark=${revremark} - - - - org.eclipse.cbi.maven.plugins - eclipse-jarsigner-plugin - 1.1.4 - - - org.apache.maven.plugins - maven-checkstyle-plugin - ${checkstyle.version} - - - org.apache.maven.plugins - maven-jar-plugin - 3.0.2 - - - org.apache.maven.plugins - maven-source-plugin - 3.0.1 - - - org.apache.maven.plugins - maven-javadoc-plugin - 3.2.0 - - - org.apache.maven.plugins - maven-gpg-plugin - 1.6 - - - com.github.eirslett - frontend-maven-plugin - 1.6 - - - - - - org.apache.maven.plugins - maven-checkstyle-plugin - - - verify-style - process-classes - - checkstyle-aggregate - - - - - UTF-8 - true - true - true - true - true - true - ${project.basedir}/mp_checkstyle_rules.xml - - - - - org.apache.rat - apache-rat-plugin - 0.12 - - - rat-check - - check - - - - - - **/*.svg - **/target - .travis.yml.* - bnd.bnd - *.log - .checkstyle - .factorypath - .editorconfig - **/node_modules/** - **/*.json - **/*.html - **/license-efsl.adoc - **/*.asciidoc - **/*.md - .vscode** - **/*.adoc - - - - - org.eclipse.microprofile.maven - microprofile-maven-build-extension - true - - - - - - - release - - - - org.sonatype.plugins - nexus-staging-maven-plugin - 1.6.3 - true - - https://oss.sonatype.org/ - ossrh - ${autorelease} - ${keepStagingReposOnFailure} - - - - - org.apache.maven.plugins - maven-source-plugin - - - attach-sources - - jar-no-fork - - - - - - org.apache.maven.plugins - maven-javadoc-plugin - - - attach-javadocs - - jar - - - - - - org.apache.maven.plugins - maven-gpg-plugin - - - sign-artifacts - verify - - sign - - - - --pinentry-mode - loopback - - - - - - - org.codehaus.mojo - build-helper-maven-plugin - 1.12 - - - timestamp-property - - timestamp-property - - validate - - currentYear - yyyy - - - - - - - - - - custom-deploy - - - ${custom-deploy.id} - ${custom-deploy.url} - - - ${custom-deploy.id} - ${custom-deploy.url} - - - - diff --git a/spec/pom.xml b/spec/pom.xml index 36475a6..2bfdb81 100644 --- a/spec/pom.xml +++ b/spec/pom.xml @@ -1,6 +1,6 @@

Lifecycle signal propagation