3.x: Add safeSubscribe to Maybe, Single & Completable (#6887)

Author: akarnokd

docs/Operator-Matrix.md

@@ -2651,6 +2651,31 @@ public final Completable retryWhen(@NonNull Function<? super Flowable<Throwable>
         return fromPublisher(toFlowable().retryWhen(handler));
     }
 
+    /**
+     * Wraps the given {@link CompletableObserver}, catches any {@link RuntimeException}s thrown by its
+     * {@link CompletableObserver#onSubscribe(Disposable)}, {@link CompletableObserver#onError(Throwable)}
+     * or {@link CompletableObserver#onComplete()} methods and routes those to the global
+     * error handler via {@link RxJavaPlugins#onError(Throwable)}.
+     * <p>
+     * By default, the {@code Completable} protocol forbids the {@code onXXX} methods to throw, but some
+     * {@code CompletableObserver} implementation may do it anyway, causing undefined behavior in the
+     * upstream. This method and the underlying safe wrapper ensures such misbehaving consumers don't
+     * disrupt the protocol.
+     * <dl>
+     *  <dt><b>Scheduler:</b></dt>
+     *  <dd>{@code safeSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
+     * </dl>
+     * @param observer the potentially misbehaving {@code CompletableObserver}
+     * @throws NullPointerException if {@code observer} is {@code null}
+     * @see #subscribe(Action, Consumer)
+     * @since 3.0.0
+     */
+    @SchedulerSupport(SchedulerSupport.NONE)
+    public final void safeSubscribe(@NonNull CompletableObserver observer) {
+        Objects.requireNonNull(observer, "observer is null");
+        subscribe(new SafeCompletableObserver(observer));
+    }
+
     /**
      * Returns a {@code Completable} which first runs the other {@link CompletableSource}
      * then the current {@code Completable} if the other completed normally.

src/main/java/io/reactivex/rxjava3/core/Completable.java

@@ -4860,6 +4860,31 @@ public final Maybe<T> retryWhen(
         return toFlowable().retryWhen(handler).singleElement();
     }
 
+    /**
+     * Wraps the given {@link MaybeObserver}, catches any {@link RuntimeException}s thrown by its
+     * {@link MaybeObserver#onSubscribe(Disposable)}, {@link MaybeObserver#onSuccess(Object)},
+     * {@link MaybeObserver#onError(Throwable)} or {@link MaybeObserver#onComplete()} methods
+     * and routes those to the global error handler via {@link RxJavaPlugins#onError(Throwable)}.
+     * <p>
+     * By default, the {@code Maybe} protocol forbids the {@code onXXX} methods to throw, but some
+     * {@code MaybeObserver} implementation may do it anyway, causing undefined behavior in the
+     * upstream. This method and the underlying safe wrapper ensures such misbehaving consumers don't
+     * disrupt the protocol.
+     * <dl>
+     *  <dt><b>Scheduler:</b></dt>
+     *  <dd>{@code safeSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
+     * </dl>
+     * @param observer the potentially misbehaving {@code MaybeObserver}
+     * @throws NullPointerException if {@code observer} is {@code null}
+     * @see #subscribe(Consumer,Consumer, Action)
+     * @since 3.0.0
+     */
+    @SchedulerSupport(SchedulerSupport.NONE)
+    public final void safeSubscribe(@NonNull MaybeObserver<? super T> observer) {
+        Objects.requireNonNull(observer, "observer is null");
+        subscribe(new SafeMaybeObserver<>(observer));
+    }
+
     /**
      * Returns a {@link Flowable} which first runs the other {@link CompletableSource}
      * then the current {@code Maybe} if the other completed normally.

src/main/java/io/reactivex/rxjava3/core/Maybe.java

@@ -4287,6 +4287,31 @@ public final Single<T> retryWhen(@NonNull Function<? super Flowable<Throwable>,
         return toSingle(toFlowable().retryWhen(handler));
     }
 
+    /**
+     * Wraps the given {@link SingleObserver}, catches any {@link RuntimeException}s thrown by its
+     * {@link SingleObserver#onSubscribe(Disposable)}, {@link SingleObserver#onSuccess(Object)} or
+     * {@link SingleObserver#onError(Throwable)} methods* and routes those to the global error handler
+     * via {@link RxJavaPlugins#onError(Throwable)}.
+     * <p>
+     * By default, the {@code Single} protocol forbids the {@code onXXX} methods to throw, but some
+     * {@code SingleObserver} implementation may do it anyway, causing undefined behavior in the
+     * upstream. This method and the underlying safe wrapper ensures such misbehaving consumers don't
+     * disrupt the protocol.
+     * <dl>
+     *  <dt><b>Scheduler:</b></dt>
+     *  <dd>{@code safeSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
+     * </dl>
+     * @param observer the potentially misbehaving {@code SingleObserver}
+     * @throws NullPointerException if {@code observer} is {@code null}
+     * @see #subscribe(Consumer,Consumer)
+     * @since 3.0.0
+     */
+    @SchedulerSupport(SchedulerSupport.NONE)
+    public final void safeSubscribe(@NonNull SingleObserver<? super T> observer) {
+        Objects.requireNonNull(observer, "observer is null");
+        subscribe(new SafeSingleObserver<>(observer));
+    }
+
     /**
      * Returns a {@link Flowable} which first runs the other {@link CompletableSource}
      * then the current {@code Single} if the other completed normally.

src/main/java/io/reactivex/rxjava3/core/Single.java

@@ -0,0 +1,78 @@
+/**
+ * Copyright (c) 2016-present, RxJava Contributors.
+ *
+ * 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.
+ */
+
+package io.reactivex.rxjava3.internal.observers;
+
+import io.reactivex.rxjava3.annotations.NonNull;
+import io.reactivex.rxjava3.core.CompletableObserver;
+import io.reactivex.rxjava3.disposables.Disposable;
+import io.reactivex.rxjava3.exceptions.*;
+import io.reactivex.rxjava3.plugins.RxJavaPlugins;
+
+/**
+ * Wraps another {@link CompletableObserver} and catches exceptions thrown by its
+ * {@code onSubscribe}, {@code onError} or
+ * {@code onComplete} methods despite the protocol forbids it.
+ * <p>
+ * Such exceptions are routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
+ *
+ * @since 3.0.0
+ */
+public final class SafeCompletableObserver implements CompletableObserver {
+
+    final CompletableObserver downstream;
+
+    boolean onSubscribeFailed;
+
+    public SafeCompletableObserver(CompletableObserver downstream) {
+        this.downstream = downstream;
+    }
+
+    @Override
+    public void onSubscribe(@NonNull Disposable d) {
+        try {
+            downstream.onSubscribe(d);
+        } catch (Throwable ex) {
+            Exceptions.throwIfFatal(ex);
+            onSubscribeFailed = true;
+            d.dispose();
+            RxJavaPlugins.onError(ex);
+        }
+    }
+
+    @Override
+    public void onError(@NonNull Throwable e) {
+        if (onSubscribeFailed) {
+            RxJavaPlugins.onError(e);
+        } else {
+            try {
+                downstream.onError(e);
+            } catch (Throwable ex) {
+                Exceptions.throwIfFatal(ex);
+                RxJavaPlugins.onError(new CompositeException(e, ex));
+            }
+        }
+    }
+
+    @Override
+    public void onComplete() {
+        if (!onSubscribeFailed) {
+            try {
+                downstream.onComplete();
+            } catch (Throwable ex) {
+                Exceptions.throwIfFatal(ex);
+                RxJavaPlugins.onError(ex);
+            }
+        }
+    }
+}

src/main/java/io/reactivex/rxjava3/internal/observers/SafeCompletableObserver.java

@@ -0,0 +1,91 @@
+/**
+ * Copyright (c) 2016-present, RxJava Contributors.
+ *
+ * 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.
+ */
+
+package io.reactivex.rxjava3.internal.observers;
+
+import io.reactivex.rxjava3.annotations.NonNull;
+import io.reactivex.rxjava3.core.MaybeObserver;
+import io.reactivex.rxjava3.disposables.Disposable;
+import io.reactivex.rxjava3.exceptions.*;
+import io.reactivex.rxjava3.plugins.RxJavaPlugins;
+
+/**
+ * Wraps another {@link MaybeObserver} and catches exceptions thrown by its
+ * {@code onSubscribe}, {@code onSuccess}, {@code onError} or
+ * {@code onComplete} methods despite the protocol forbids it.
+ * <p>
+ * Such exceptions are routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
+ *
+ * @param <T> the element type of the sequence
+ * @since 3.0.0
+ */
+public final class SafeMaybeObserver<T> implements MaybeObserver<T> {
+
+    final MaybeObserver<? super T> downstream;
+
+    boolean onSubscribeFailed;
+
+    public SafeMaybeObserver(MaybeObserver<? super T> downstream) {
+        this.downstream = downstream;
+    }
+
+    @Override
+    public void onSubscribe(@NonNull Disposable d) {
+        try {
+            downstream.onSubscribe(d);
+        } catch (Throwable ex) {
+            Exceptions.throwIfFatal(ex);
+            onSubscribeFailed = true;
+            d.dispose();
+            RxJavaPlugins.onError(ex);
+        }
+    }
+
+    @Override
+    public void onSuccess(@NonNull T t) {
+        if (!onSubscribeFailed) {
+            try {
+                downstream.onSuccess(t);
+            } catch (Throwable ex) {
+                Exceptions.throwIfFatal(ex);
+                RxJavaPlugins.onError(ex);
+            }
+        }
+    }
+
+    @Override
+    public void onError(@NonNull Throwable e) {
+        if (onSubscribeFailed) {
+            RxJavaPlugins.onError(e);
+        } else {
+            try {
+                downstream.onError(e);
+            } catch (Throwable ex) {
+                Exceptions.throwIfFatal(ex);
+                RxJavaPlugins.onError(new CompositeException(e, ex));
+            }
+        }
+    }
+
+    @Override
+    public void onComplete() {
+        if (!onSubscribeFailed) {
+            try {
+                downstream.onComplete();
+            } catch (Throwable ex) {
+                Exceptions.throwIfFatal(ex);
+                RxJavaPlugins.onError(ex);
+            }
+        }
+    }
+}

src/main/java/io/reactivex/rxjava3/internal/observers/SafeMaybeObserver.java

@@ -0,0 +1,79 @@
+/**
+ * Copyright (c) 2016-present, RxJava Contributors.
+ *
+ * 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.
+ */
+
+package io.reactivex.rxjava3.internal.observers;
+
+import io.reactivex.rxjava3.annotations.NonNull;
+import io.reactivex.rxjava3.core.SingleObserver;
+import io.reactivex.rxjava3.disposables.Disposable;
+import io.reactivex.rxjava3.exceptions.*;
+import io.reactivex.rxjava3.plugins.RxJavaPlugins;
+
+/**
+ * Wraps another {@link SingleObserver} and catches exceptions thrown by its
+ * {@code onSubscribe}, {@code onSuccess} or {@code onError} methods despite
+ * the protocol forbids it.
+ * <p>
+ * Such exceptions are routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
+ *
+ * @param <T> the element type of the sequence
+ * @since 3.0.0
+ */
+public final class SafeSingleObserver<T> implements SingleObserver<T> {
+
+    final SingleObserver<? super T> downstream;
+
+    boolean onSubscribeFailed;
+
+    public SafeSingleObserver(SingleObserver<? super T> downstream) {
+        this.downstream = downstream;
+    }
+
+    @Override
+    public void onSubscribe(@NonNull Disposable d) {
+        try {
+            downstream.onSubscribe(d);
+        } catch (Throwable ex) {
+            Exceptions.throwIfFatal(ex);
+            onSubscribeFailed = true;
+            d.dispose();
+            RxJavaPlugins.onError(ex);
+        }
+    }
+
+    @Override
+    public void onSuccess(@NonNull T t) {
+        if (!onSubscribeFailed) {
+            try {
+                downstream.onSuccess(t);
+            } catch (Throwable ex) {
+                Exceptions.throwIfFatal(ex);
+                RxJavaPlugins.onError(ex);
+            }
+        }
+    }
+
+    @Override
+    public void onError(@NonNull Throwable e) {
+        if (onSubscribeFailed) {
+            RxJavaPlugins.onError(e);
+        } else {
+            try {
+                downstream.onError(e);
+            } catch (Throwable ex) {
+                Exceptions.throwIfFatal(ex);
+                RxJavaPlugins.onError(new CompositeException(e, ex));
+            }
+        }
+    }
+}