- * All methods are safe to call from multiple threads. + * All methods are safe to call from multiple threads, but note that there is no guarantee + * whose terminal event will win and get delivered to the downstream. *
- * Calling onComplete or onError multiple times has no effect. + * Calling {@link #onComplete()} multiple times has no effect. + * Calling {@link #onError(Throwable)} multiple times or after {@code onComplete} will route the + * exception into the global error handler via {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)}. + *
+ * The emitter allows the registration of a single resource, in the form of a {@link Disposable} + * or {@link Cancellable} via {@link #setDisposable(Disposable)} or {@link #setCancellable(Cancellable)} + * respectively. The emitter implementations will dispose/cancel this instance when the + * downstream cancels the flow or after the event generator logic calls + * {@link #onError(Throwable)}, {@link #onComplete()} or when {@link #tryOnError(Throwable)} succeeds. + *
+ * Only one {@code Disposable} or {@code Cancellable} object can be associated with the emitter at + * a time. Calling either {@code set} method will dispose/cancel any previous object. If there + * is a need for handling multiple resources, one can create a {@link io.reactivex.disposables.CompositeDisposable} + * and associate that with the emitter instead. + *
+ * The {@link Cancellable} is logically equivalent to {@code Disposable} but allows using cleanup logic that can + * throw a checked exception (such as many {@code close()} methods on Java IO components). Since + * the release of resources happens after the terminal events have been delivered or the sequence gets + * cancelled, exceptions throw within {@code Cancellable} are routed to the global error handler via + * {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)}. */ public interface CompletableEmitter { @@ -53,8 +73,11 @@ public interface CompletableEmitter { void setCancellable(@Nullable Cancellable c); /** - * Returns true if the downstream disposed the sequence. - * @return true if the downstream disposed the sequence + * Returns true if the downstream disposed the sequence or the + * emitter was terminated via {@link #onError(Throwable)}, + * {@link #onComplete} or a successful {@link #tryOnError(Throwable)}. + *
This method is thread-safe. + * @return true if the downstream disposed the sequence or the emitter was terminated */ boolean isDisposed(); diff --git a/src/main/java/io/reactivex/FlowableEmitter.java b/src/main/java/io/reactivex/FlowableEmitter.java index 9b76cbbad0..f3c1d8e0cb 100644 --- a/src/main/java/io/reactivex/FlowableEmitter.java +++ b/src/main/java/io/reactivex/FlowableEmitter.java @@ -22,10 +22,29 @@ * a resource with it and exposes the current number of downstream * requested amount. *
- * The onNext, onError and onComplete methods should be called - * in a sequential manner, just like the Subscriber's methods. - * Use {@link #serialize()} if you want to ensure this. + * The {@link #onNext(Object)}, {@link #onError(Throwable)}, {@link #tryOnError(Throwable)} + * and {@link #onComplete()} methods should be called in a sequential manner, just like + * the {@link org.reactivestreams.Subscriber Subscriber}'s methods. + * Use the {@code FlowableEmitter} the {@link #serialize()} method returns instead of the original + * {@code FlowableEmitter} instance provided by the generator routine if you want to ensure this. * The other methods are thread-safe. + *
+ * The emitter allows the registration of a single resource, in the form of a {@link Disposable} + * or {@link Cancellable} via {@link #setDisposable(Disposable)} or {@link #setCancellable(Cancellable)} + * respectively. The emitter implementations will dispose/cancel this instance when the + * downstream cancels the flow or after the event generator logic calls {@link #onError(Throwable)}, + * {@link #onComplete()} or when {@link #tryOnError(Throwable)} succeeds. + *
+ * Only one {@code Disposable} or {@code Cancellable} object can be associated with the emitter at + * a time. Calling either {@code set} method will dispose/cancel any previous object. If there + * is a need for handling multiple resources, one can create a {@link io.reactivex.disposables.CompositeDisposable} + * and associate that with the emitter instead. + *
+ * The {@link Cancellable} is logically equivalent to {@code Disposable} but allows using cleanup logic that can
+ * throw a checked exception (such as many {@code close()} methods on Java IO components). Since
+ * the release of resources happens after the terminal events have been delivered or the sequence gets
+ * cancelled, exceptions throw within {@code Cancellable} are routed to the global error handler via
+ * {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)}.
*
* @param This method is thread-safe.
- * @return true if the downstream cancelled the sequence
+ * @return true if the downstream cancelled the sequence or the emitter was terminated
*/
boolean isCancelled();
diff --git a/src/main/java/io/reactivex/MaybeEmitter.java b/src/main/java/io/reactivex/MaybeEmitter.java
index dfe7958d11..c772430730 100644
--- a/src/main/java/io/reactivex/MaybeEmitter.java
+++ b/src/main/java/io/reactivex/MaybeEmitter.java
@@ -21,9 +21,29 @@
* Abstraction over an RxJava {@link MaybeObserver} that allows associating
* a resource with it.
*
- * All methods are safe to call from multiple threads.
+ * All methods are safe to call from multiple threads, but note that there is no guarantee
+ * whose terminal event will win and get delivered to the downstream.
*
- * Calling onSuccess, onError or onComplete multiple times has no effect.
+ * Calling {@link #onSuccess(Object)} or {@link #onComplete()} multiple times has no effect.
+ * Calling {@link #onError(Throwable)} multiple times or after the other two will route the
+ * exception into the global error handler via {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)}.
+ *
+ * The emitter allows the registration of a single resource, in the form of a {@link Disposable}
+ * or {@link Cancellable} via {@link #setDisposable(Disposable)} or {@link #setCancellable(Cancellable)}
+ * respectively. The emitter implementations will dispose/cancel this instance when the
+ * downstream cancels the flow or after the event generator logic calls {@link #onSuccess(Object)},
+ * {@link #onError(Throwable)}, {@link #onComplete()} or when {@link #tryOnError(Throwable)} succeeds.
+ *
+ * Only one {@code Disposable} or {@code Cancellable} object can be associated with the emitter at
+ * a time. Calling either {@code set} method will dispose/cancel any previous object. If there
+ * is a need for handling multiple resources, one can create a {@link io.reactivex.disposables.CompositeDisposable}
+ * and associate that with the emitter instead.
+ *
+ * The {@link Cancellable} is logically equivalent to {@code Disposable} but allows using cleanup logic that can
+ * throw a checked exception (such as many {@code close()} methods on Java IO components). Since
+ * the release of resources happens after the terminal events have been delivered or the sequence gets
+ * cancelled, exceptions throw within {@code Cancellable} are routed to the global error handler via
+ * {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)}.
*
* @param This method is thread-safe.
+ * @return true if the downstream disposed the sequence or the emitter was terminated
*/
boolean isDisposed();
diff --git a/src/main/java/io/reactivex/ObservableEmitter.java b/src/main/java/io/reactivex/ObservableEmitter.java
index bd2aac8eb1..68c81207b6 100644
--- a/src/main/java/io/reactivex/ObservableEmitter.java
+++ b/src/main/java/io/reactivex/ObservableEmitter.java
@@ -21,10 +21,29 @@
* Abstraction over an RxJava {@link Observer} that allows associating
* a resource with it.
*
- * The onNext, onError and onComplete methods should be called
- * in a sequential manner, just like the Observer's methods.
- * Use {@link #serialize()} if you want to ensure this.
+ * The {@link #onNext(Object)}, {@link #onError(Throwable)}, {@link #tryOnError(Throwable)}
+ * and {@link #onComplete()} methods should be called in a sequential manner, just like the
+ * {@link Observer}'s methods should be.
+ * Use the {@code ObservableEmitter} the {@link #serialize()} method returns instead of the original
+ * {@code ObservableEmitter} instance provided by the generator routine if you want to ensure this.
* The other methods are thread-safe.
+ *
+ * The emitter allows the registration of a single resource, in the form of a {@link Disposable}
+ * or {@link Cancellable} via {@link #setDisposable(Disposable)} or {@link #setCancellable(Cancellable)}
+ * respectively. The emitter implementations will dispose/cancel this instance when the
+ * downstream cancels the flow or after the event generator logic calls {@link #onError(Throwable)},
+ * {@link #onComplete()} or when {@link #tryOnError(Throwable)} succeeds.
+ *
+ * Only one {@code Disposable} or {@code Cancellable} object can be associated with the emitter at
+ * a time. Calling either {@code set} method will dispose/cancel any previous object. If there
+ * is a need for handling multiple resources, one can create a {@link io.reactivex.disposables.CompositeDisposable}
+ * and associate that with the emitter instead.
+ *
+ * The {@link Cancellable} is logically equivalent to {@code Disposable} but allows using cleanup logic that can
+ * throw a checked exception (such as many {@code close()} methods on Java IO components). Since
+ * the release of resources happens after the terminal events have been delivered or the sequence gets
+ * cancelled, exceptions throw within {@code Cancellable} are routed to the global error handler via
+ * {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)}.
*
* @param This method is thread-safe.
+ * @return true if the downstream disposed the sequence or the emitter was terminated
*/
boolean isDisposed();
diff --git a/src/main/java/io/reactivex/SingleEmitter.java b/src/main/java/io/reactivex/SingleEmitter.java
index 6c0da0ce06..c623638ef7 100644
--- a/src/main/java/io/reactivex/SingleEmitter.java
+++ b/src/main/java/io/reactivex/SingleEmitter.java
@@ -21,9 +21,29 @@
* Abstraction over an RxJava {@link SingleObserver} that allows associating
* a resource with it.
*
- * All methods are safe to call from multiple threads.
+ * All methods are safe to call from multiple threads, but note that there is no guarantee
+ * whose terminal event will win and get delivered to the downstream.
*
- * Calling onSuccess or onError multiple times has no effect.
+ * Calling {@link #onSuccess(Object)} multiple times has no effect.
+ * Calling {@link #onError(Throwable)} multiple times or after {@code onSuccess} will route the
+ * exception into the global error handler via {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)}.
+ *
+ * The emitter allows the registration of a single resource, in the form of a {@link Disposable}
+ * or {@link Cancellable} via {@link #setDisposable(Disposable)} or {@link #setCancellable(Cancellable)}
+ * respectively. The emitter implementations will dispose/cancel this instance when the
+ * downstream cancels the flow or after the event generator logic calls {@link #onSuccess(Object)},
+ * {@link #onError(Throwable)}, or when {@link #tryOnError(Throwable)} succeeds.
+ *
+ * Only one {@code Disposable} or {@code Cancellable} object can be associated with the emitter at
+ * a time. Calling either {@code set} method will dispose/cancel any previous object. If there
+ * is a need for handling multiple resources, one can create a {@link io.reactivex.disposables.CompositeDisposable}
+ * and associate that with the emitter instead.
+ *
+ * The {@link Cancellable} is logically equivalent to {@code Disposable} but allows using cleanup logic that can
+ * throw a checked exception (such as many {@code close()} methods on Java IO components). Since
+ * the release of resources happens after the terminal events have been delivered or the sequence gets
+ * cancelled, exceptions throw within {@code Cancellable} are routed to the global error handler via
+ * {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)}.
*
* @param This method is thread-safe.
+ * @return true if the downstream disposed the sequence or the emitter was terminated
*/
boolean isDisposed();