2.x: Explain the properties of the XEmitter interfaces in detail (#5844)

Author: akarnokd

src/main/java/io/reactivex/CompletableEmitter.java

@@ -21,9 +21,29 @@
  * Abstraction over an RxJava {@link CompletableObserver} that allows associating
  * a resource with it.
  * <p>
- * 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.
  * <p>
- * 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)}.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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)}.
+     * <p>This method is thread-safe.
+     * @return true if the downstream disposed the sequence or the emitter was terminated
      */
     boolean isDisposed();
 

src/main/java/io/reactivex/FlowableEmitter.java

@@ -22,10 +22,29 @@
  * a resource with it and exposes the current number of downstream
  * requested amount.
  * <p>
- * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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 <T> the value type to emit
  */
@@ -53,9 +72,11 @@ public interface FlowableEmitter<T> extends Emitter<T> {
     long requested();
 
     /**
-     * Returns true if the downstream cancelled the sequence.
+     * Returns true if the downstream cancelled the sequence or the
+     * emitter was terminated via {@link #onError(Throwable)}, {@link #onComplete} or a
+     * successful {@link #tryOnError(Throwable)}.
      * <p>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();
 

src/main/java/io/reactivex/MaybeEmitter.java

@@ -21,9 +21,29 @@
  * Abstraction over an RxJava {@link MaybeObserver} that allows associating
  * a resource with it.
  * <p>
- * 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.
  * <p>
- * 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)}.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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 <T> the value type to emit
  */
@@ -61,8 +81,12 @@ public interface MaybeEmitter<T> {
     void setCancellable(@Nullable Cancellable c);
 
     /**
-     * Returns true if the downstream cancelled the sequence.
-     * @return true if the downstream cancelled the sequence
+     * Returns true if the downstream disposed the sequence or the
+     * emitter was terminated via {@link #onSuccess(Object)}, {@link #onError(Throwable)},
+     * {@link #onComplete} or a
+     * successful {@link #tryOnError(Throwable)}.
+     * <p>This method is thread-safe.
+     * @return true if the downstream disposed the sequence or the emitter was terminated
      */
     boolean isDisposed();
 

src/main/java/io/reactivex/ObservableEmitter.java

@@ -21,10 +21,29 @@
  * Abstraction over an RxJava {@link Observer} that allows associating
  * a resource with it.
  * <p>
- * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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 <T> the value type to emit
  */
@@ -45,8 +64,11 @@ public interface ObservableEmitter<T> extends Emitter<T> {
     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)}.
+     * <p>This method is thread-safe.
+     * @return true if the downstream disposed the sequence or the emitter was terminated
      */
     boolean isDisposed();
 

src/main/java/io/reactivex/SingleEmitter.java

@@ -21,9 +21,29 @@
  * Abstraction over an RxJava {@link SingleObserver} that allows associating
  * a resource with it.
  * <p>
- * 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.
  * <p>
- * 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)}.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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 <T> the value type to emit
  */
@@ -56,8 +76,11 @@ public interface SingleEmitter<T> {
     void setCancellable(@Nullable Cancellable c);
 
     /**
-     * Returns true if the downstream cancelled the sequence.
-     * @return true if the downstream cancelled the sequence
+     * Returns true if the downstream disposed the sequence or the
+     * emitter was terminated via {@link #onSuccess(Object)}, {@link #onError(Throwable)},
+     * or a successful {@link #tryOnError(Throwable)}.
+     * <p>This method is thread-safe.
+     * @return true if the downstream disposed the sequence or the emitter was terminated
      */
     boolean isDisposed();