Deprecate publishAndSubscribeOnOverride methods (#1527)

**Motivation**: Refactoring of offloading is expected to remove these methods so it is important to give users forewarning to migrate to other methods. **Modifications**: The `publishOnOverride`, `subscribeOnOverride` and `publishAndSubscribeOnOverride` methods of `Publisher`, `Single` and `Completable` are deprecated as well as the internal methods they call are marked deprecated and an alternative suggestion is provided. **Result**: Users are forewarned of upcoming API change.
apple · May 5, 2021 · 0c27f44 · 0c27f44
1 parent edc0e6d
commit 0c27f44
Show file tree

Hide file tree

Showing 6 changed files with 36 additions and 9 deletions.
diff --git a/servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/Completable.java b/servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/Completable.java
@@ -1505,12 +1505,14 @@ public final Completable publishOn(Executor executor) {
      * This method overrides preceding {@link Executor}s, if any, specified for {@code this} {@link Completable}.
      * That is to say preceding and subsequent operations for this execution chain will use this {@link Executor}.
      * If such an override is not required, {@link #publishOn(Executor)} can be used.
-     *
+     * @deprecated This method will be removed in a future release. Consider switching to
+     * {@link #publishOn(Executor)} and/or using {@link Executor#execute(Runnable)} for offloading.
      * @param executor {@link Executor} to use.
      * @return A new {@link Completable} that will use the passed {@link Executor} to invoke all methods of
      * {@link Subscriber}, {@link Cancellable} and {@link #handleSubscribe(CompletableSource.Subscriber)} both for the
      * returned {@link Completable} as well as {@code this} {@link Completable}.
      */
+    @Deprecated
     public final Completable publishOnOverride(Executor executor) {
         return PublishAndSubscribeOnCompletables.publishOnOverride(this, executor);
     }
@@ -1542,12 +1544,14 @@ public final Completable subscribeOn(Executor executor) {
      * This method overrides preceding {@link Executor}s, if any, specified for {@code this} {@link Completable}.
      * That is to say preceding and subsequent operations for this execution chain will use this {@link Executor}.
      * If such an override is not required, {@link #subscribeOn(Executor)} can be used.
-     *
+     * @deprecated This method will be removed in a future release. Consider switching to
+     * {@link #subscribeOn(Executor)} and/or using {@link Executor#execute(Runnable)} for offloading.
      * @param executor {@link Executor} to use.
      * @return A new {@link Completable} that will use the passed {@link Executor} to invoke all methods of
      * {@link Cancellable} and {@link #handleSubscribe(CompletableSource.Subscriber)} both for the returned
      * {@link Completable} as well as {@code this} {@link Completable}.
      */
+    @Deprecated
     public final Completable subscribeOnOverride(Executor executor) {
         return PublishAndSubscribeOnCompletables.subscribeOnOverride(this, executor);
     }
@@ -1581,12 +1585,14 @@ public final Completable publishAndSubscribeOn(Executor executor) {
      * This method overrides preceding {@link Executor}s, if any, specified for {@code this} {@link Completable}.
      * That is to say preceding and subsequent operations for this execution chain will use this {@link Executor}.
      * If such an override is not required, {@link #publishAndSubscribeOn(Executor)} can be used.
-     *
+     * @deprecated This method will be removed in a future release. Consider switching to
+     * {@link #publishAndSubscribeOn(Executor)} and/or using {@link Executor#execute(Runnable)} for offloading.
      * @param executor {@link Executor} to use.
      * @return A new {@link Completable} that will use the passed {@link Executor} to invoke all methods of
      * {@link Subscriber}, {@link Cancellable} and {@link #handleSubscribe(CompletableSource.Subscriber)} both for the
      * returned {@link Completable} as well as {@code this} {@link Completable}.
      */
+    @Deprecated
     public final Completable publishAndSubscribeOnOverride(Executor executor) {
         return PublishAndSubscribeOnCompletables.publishAndSubscribeOnOverride(this, executor);
     }

diff --git a/...nt-api/src/main/java/io/servicetalk/concurrent/api/PublishAndSubscribeOnCompletables.java b/...nt-api/src/main/java/io/servicetalk/concurrent/api/PublishAndSubscribeOnCompletables.java
@@ -44,6 +44,7 @@ static Completable publishAndSubscribeOn(Completable original, Executor executor
         return original.executor() == executor ? original : new PublishAndSubscribeOn(executor, original);
     }
 
+    @Deprecated
     static Completable publishAndSubscribeOnOverride(Completable original, Executor executor) {
         return original.executor() == executor ? original : new PublishAndSubscribeOnOverride(original, executor);
     }
@@ -52,6 +53,7 @@ static Completable publishOn(Completable original, Executor executor) {
         return original.executor() == executor ? original : new PublishOn(executor, original);
     }
 
+    @Deprecated
     static Completable publishOnOverride(Completable original, Executor executor) {
         return original.executor() == executor ? original : new PublishOnOverride(original, executor);
     }
@@ -60,6 +62,7 @@ static Completable subscribeOn(Completable original, Executor executor) {
         return original.executor() == executor ? original : new SubscribeOn(executor, original);
     }
 
+    @Deprecated
     static Completable subscribeOnOverride(Completable original, Executor executor) {
         return original.executor() == executor ? original : new SubscribeOnOverride(original, executor);
     }

diff --git a/...rent-api/src/main/java/io/servicetalk/concurrent/api/PublishAndSubscribeOnPublishers.java b/...rent-api/src/main/java/io/servicetalk/concurrent/api/PublishAndSubscribeOnPublishers.java
@@ -44,6 +44,7 @@ static <T> Publisher<T> publishAndSubscribeOn(Publisher<T> original, Executor ex
         return original.executor() == executor ? original : new PublishAndSubscribeOn<>(executor, original);
     }
 
+    @Deprecated
     static <T> Publisher<T> publishAndSubscribeOnOverride(Publisher<T> original, Executor executor) {
         return original.executor() == executor ? original : new PublishAndSubscribeOnOverride<>(original, executor);
     }
@@ -52,6 +53,7 @@ static <T> Publisher<T> publishOn(Publisher<T> original, Executor executor) {
         return original.executor() == executor ? original : new PublishOn<>(executor, original);
     }
 
+    @Deprecated
     static <T> Publisher<T> publishOnOverride(Publisher<T> original, Executor executor) {
         return original.executor() == executor ? original : new PublishOnOverride<>(original, executor);
     }
@@ -60,6 +62,7 @@ static <T> Publisher<T> subscribeOn(Publisher<T> original, Executor executor) {
         return original.executor() == executor ? original : new SubscribeOn<>(executor, original);
     }
 
+    @Deprecated
     static <T> Publisher<T> subscribeOnOverride(Publisher<T> original, Executor executor) {
         return original.executor() == executor ? original : new SubscribeOnOverride<>(original, executor);
     }

diff --git a/...current-api/src/main/java/io/servicetalk/concurrent/api/PublishAndSubscribeOnSingles.java b/...current-api/src/main/java/io/servicetalk/concurrent/api/PublishAndSubscribeOnSingles.java
@@ -43,6 +43,7 @@ static <T> Single<T> publishAndSubscribeOn(Single<T> original, Executor executor
         return original.executor() == executor ? original : new PublishAndSubscribeOn<>(executor, original);
     }
 
+    @Deprecated
     static <T> Single<T> publishAndSubscribeOnOverride(Single<T> original, Executor executor) {
         return original.executor() == executor ? original : new PublishAndSubscribeOnOverride<>(original, executor);
     }
@@ -51,6 +52,7 @@ static <T> Single<T> publishOn(Single<T> original, Executor executor) {
         return original.executor() == executor ? original : new PublishOn<>(executor, original);
     }
 
+    @Deprecated
     static <T> Single<T> publishOnOverride(Single<T> original, Executor executor) {
         return original.executor() == executor ? original : new PublishOnOverride<>(original, executor);
     }
@@ -59,6 +61,7 @@ static <T> Single<T> subscribeOn(Single<T> original, Executor executor) {
         return original.executor() == executor ? original : new SubscribeOn<>(executor, original);
     }
 
+    @Deprecated
     static <T> Single<T> subscribeOnOverride(Single<T> original, Executor executor) {
         return original.executor() == executor ? original : new SubscribeOnOverride<>(original, executor);
     }

diff --git a/servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/Publisher.java b/servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/Publisher.java
@@ -2849,11 +2849,13 @@ public final Publisher<T> publishOn(Executor executor) {
      * This method overrides preceding {@link Executor}s, if any, specified for {@code this} {@link Publisher}.
      * That is to say preceding and subsequent operations for this execution chain will use this {@link Executor}.
      * If such an override is not required, {@link #publishOn(Executor)} can be used.
-     *
+     * @deprecated This method will be removed in a future release. Consider switching to {@link #publishOn(Executor)}
+     * and/or using {@link Executor#execute(Runnable)} for offloading.
      * @param executor {@link Executor} to use.
      * @return A new {@link Publisher} that will use the passed {@link Executor} to invoke all methods of
      * {@link Subscriber} both for the returned {@link Publisher} as well as {@code this} {@link Publisher}.
      */
+    @Deprecated
     public final Publisher<T> publishOnOverride(Executor executor) {
         return PublishAndSubscribeOnPublishers.publishOnOverride(this, executor);
     }
@@ -2885,12 +2887,14 @@ public final Publisher<T> subscribeOn(Executor executor) {
      * This method overrides preceding {@link Executor}s, if any, specified for {@code this} {@link Publisher}.
      * That is to say preceding and subsequent operations for this execution chain will use this {@link Executor}.
      * If such an override is not required, {@link #subscribeOn(Executor)} can be used.
-     *
+     * @deprecated This method will be removed in a future release. Consider switching to {@link #subscribeOn(Executor)}
+     * and/or using {@link Executor#execute(Runnable)} for offloading.
      * @param executor {@link Executor} to use.
      * @return A new {@link Publisher} that will use the passed {@link Executor} to invoke all methods of
      * {@link Subscription} and {@link #handleSubscribe(PublisherSource.Subscriber)} both for the returned
      * {@link Publisher} as well as {@code this} {@link Publisher}.
      */
+    @Deprecated
     public final Publisher<T> subscribeOnOverride(Executor executor) {
         return PublishAndSubscribeOnPublishers.subscribeOnOverride(this, executor);
     }
@@ -2924,12 +2928,14 @@ public final Publisher<T> publishAndSubscribeOn(Executor executor) {
      * This method overrides preceding {@link Executor}s, if any, specified for {@code this} {@link Publisher}.
      * That is to say preceding and subsequent operations for this execution chain will use this {@link Executor}.
      * If such an override is not required, {@link #publishAndSubscribeOn(Executor)} can be used.
-     *
+     * @deprecated This method will be removed in a future release. Consider switching to
+     * {@link #publishAndSubscribeOn(Executor)} and/or using {@link Executor#execute(Runnable)} for offloading.
      * @param executor {@link Executor} to use.
      * @return A new {@link Publisher} that will use the passed {@link Executor} to invoke all methods of
      * {@link Subscriber}, {@link Subscription} and {@link #handleSubscribe(PublisherSource.Subscriber)} both for the
      * returned {@link Publisher} as well as {@code this} {@link Publisher}.
      */
+    @Deprecated
     public final Publisher<T> publishAndSubscribeOnOverride(Executor executor) {
         return PublishAndSubscribeOnPublishers.publishAndSubscribeOnOverride(this, executor);
     }

diff --git a/servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/Single.java b/servicetalk-concurrent-api/src/main/java/io/servicetalk/concurrent/api/Single.java
@@ -1470,12 +1470,14 @@ public final Single<T> publishOn(Executor executor) {
      * That is to say preceding and subsequent operations for this execution chain will use this {@link Executor} for
      * invoking all {@link Subscriber} methods. If such an override is not required, {@link #publishOn(Executor)} can be
      * used.
-     *
+     * @deprecated This method will be removed in a future release. Consider switching to
+     * {@link #publishOn(Executor)} and/or using {@link Executor#execute(Runnable)} for offloading.
      * @param executor {@link Executor} to use.
      * @return A new {@link Single} that will use the passed {@link Executor} to invoke all methods of
      * {@link Subscriber}, {@link Cancellable} and {@link #handleSubscribe(SingleSource.Subscriber)} both for the
      * returned {@link Single} as well as {@code this} {@link Single}.
      */
+    @Deprecated
     public final Single<T> publishOnOverride(Executor executor) {
         return PublishAndSubscribeOnSingles.publishOnOverride(this, executor);
     }
@@ -1508,12 +1510,14 @@ public final Single<T> subscribeOn(Executor executor) {
      * That is to say preceding and subsequent operations for this execution chain will use this {@link Executor} for
      * invoking the above specified methods.
      * If such an override is not required, {@link #subscribeOn(Executor)} can be used.
-     *
+     * @deprecated This method will be removed in a future release. Consider switching to
+     * {@link #subscribeOn(Executor)} and/or using {@link Executor#execute(Runnable)} for offloading.
      * @param executor {@link Executor} to use.
      * @return A new {@link Single} that will use the passed {@link Executor} to invoke all methods of
      * {@link Cancellable} and {@link #handleSubscribe(SingleSource.Subscriber)} both for the returned
      * {@link Single} as well as {@code this} {@link Single}.
      */
+    @Deprecated
     public final Single<T> subscribeOnOverride(Executor executor) {
         return PublishAndSubscribeOnSingles.subscribeOnOverride(this, executor);
     }
@@ -1547,12 +1551,14 @@ public final Single<T> publishAndSubscribeOn(Executor executor) {
      * This method overrides preceding {@link Executor}s, if any, specified for {@code this} {@link Single}.
      * That is to say preceding and subsequent operations for this execution chain will use this {@link Executor}.
      * If such an override is not required, {@link #publishAndSubscribeOn(Executor)} can be used.
-     *
+     * @deprecated This method will be removed in a future release. Consider switching to
+     * {@link #publishAndSubscribeOn(Executor)} and/or using {@link Executor#execute(Runnable)} for offloading.
      * @param executor {@link Executor} to use.
      * @return A new {@link Single} that will use the passed {@link Executor} to invoke all methods of
      * {@link Subscriber}, {@link Cancellable} and {@link #handleSubscribe(SingleSource.Subscriber)} both for the
      * returned {@link Single} as well as {@code this} {@link Single}.
      */
+    @Deprecated
     public final Single<T> publishAndSubscribeOnOverride(Executor executor) {
         return PublishAndSubscribeOnSingles.publishAndSubscribeOnOverride(this, executor);
     }