|
34 | 34 | import io.reactivex.schedulers.*; |
35 | 35 |
|
36 | 36 | /** |
37 | | - * The Observable class that is designed similar to the Reactive-Streams Pattern, minus the backpressure, |
38 | | - * and offers factory methods, intermediate operators and the ability to consume reactive dataflows. |
| 37 | + * The Observable class is the non-backpressured, optionally multi-valued base reactive class that |
| 38 | + * offers factory methods, intermediate operators and the ability to consume synchronous |
| 39 | + * and/or asynchronous reactive dataflows. |
39 | 40 | * <p> |
40 | | - * Reactive-Streams operates with {@code ObservableSource}s which {@code Observable} extends. Many operators |
41 | | - * therefore accept general {@code ObservableSource}s directly and allow direct interoperation with other |
42 | | - * Reactive-Streams implementations. |
| 41 | + * Many operators in the class accept {@code ObservableSource}(s), the base reactive interface |
| 42 | + * for such non-backpressured flows, which {@code Observable} itself implements as well. |
43 | 43 | * <p> |
44 | 44 | * The Observable's operators, by default, run with a buffer size of 128 elements (see {@link Flowable#bufferSize()}, |
45 | 45 | * that can be overridden globally via the system parameter {@code rx2.buffer-size}. Most operators, however, have |
|
49 | 49 | * <p> |
50 | 50 | * <img width="640" height="317" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/legend.png" alt=""> |
51 | 51 | * <p> |
52 | | - * For more information see the <a href="http://reactivex.io/documentation/ObservableSource.html">ReactiveX |
53 | | - * documentation</a>. |
54 | | - * |
| 52 | + * The design of this class was derived from the |
| 53 | + * <a href="https://github.com/reactive-streams/reactive-streams-jvm">Reactive-Streams design and specification</a> |
| 54 | + * by removing any backpressure-related infrastructure and implementation detail, replacing the |
| 55 | + * {@code org.reactivestreams.Subscription} with {@link Disposable} as the primary means to cancel |
| 56 | + * a flow. |
| 57 | + * <p> |
| 58 | + * The {@code Observable} follows the protocol |
| 59 | + * <pre><code> |
| 60 | + * onSubscribe onNext* (onError | onComplete)? |
| 61 | + * </code></pre> |
| 62 | + * where |
| 63 | + * the stream can be disposed through the {@code Disposable} instance provided to consumers through |
| 64 | + * {@code Observer.onSubscribe}. |
| 65 | + * <p> |
| 66 | + * Unlike the {@code Observable} of version 1.x, {@link #subscribe(Observer)} does not allow external cancellation |
| 67 | + * of a subscription and the {@code Observer} instance is expected to expose such capability. |
| 68 | + * <p>Example: |
| 69 | + * <pre><code> |
| 70 | + * Disposable d = Observable.just("Hello world!") |
| 71 | + * .delay(1, TimeUnit.SECONDS) |
| 72 | + * .subscribeWith(new DisposableObserver<String>() { |
| 73 | + * @Override public void onStart() { |
| 74 | + * System.out.println("Start!"); |
| 75 | + * } |
| 76 | + * @Override public void onNext(Integer t) { |
| 77 | + * System.out.println(t); |
| 78 | + * } |
| 79 | + * @Override public void onError(Throwable t) { |
| 80 | + * t.printStackTrace(); |
| 81 | + * } |
| 82 | + * @Override public void onComplete() { |
| 83 | + * System.out.println("Done!"); |
| 84 | + * } |
| 85 | + * }); |
| 86 | + * |
| 87 | + * Thread.sleep(500); |
| 88 | + * // the sequence now can be cancelled via dispose() |
| 89 | + * d.dispose(); |
| 90 | + * </code></pre> |
| 91 | + * |
55 | 92 | * @param <T> |
56 | 93 | * the type of the items emitted by the Observable |
| 94 | + * @see Flowable |
| 95 | + * @see io.reactivex.observers.DisposableObserver |
57 | 96 | */ |
58 | 97 | public abstract class Observable<T> implements ObservableSource<T> { |
59 | 98 |
|
|
0 commit comments