From 0c19e4e070787035f40705c46180a0f868e80847 Mon Sep 17 00:00:00 2001 From: "David M. Gross" Date: Tue, 28 May 2013 13:35:02 -0700 Subject: [PATCH] Diagrams and some new docs for Observable subclasses Some marble or marblish diagrams and a bit of new documentation for the BlockingObservable and ConnectableObservable subclasses. --- .../rx/observables/BlockingObservable.java | 35 +++++++++++++++++++ .../rx/observables/ConnectableObservable.java | 17 +++++++++ 2 files changed, 52 insertions(+) diff --git a/rxjava-core/src/main/java/rx/observables/BlockingObservable.java b/rxjava-core/src/main/java/rx/observables/BlockingObservable.java index 691a40edb8..05e4c60ae4 100644 --- a/rxjava-core/src/main/java/rx/observables/BlockingObservable.java +++ b/rxjava-core/src/main/java/rx/observables/BlockingObservable.java @@ -32,6 +32,13 @@ * Extension of {@link Observable} that provides blocking operators. *

* Constructud via {@link #from(Observable)} or {@link Observable#toBlockingObservable()} + *

+ * The documentation for this interface makes use of a form of marble diagram that has been + * modified to illustrate blocking operators. The following legend explains marble diagrams: + *

+ * + *

+ * For more information see the RxJava Wiki * * @param */ @@ -49,6 +56,8 @@ public Subscription call(Observer observer) { /** * Returns an iterator that iterates all values of the observable. + *

+ * * * @param source * an observable sequence to get an iterator for. @@ -62,6 +71,8 @@ public static Iterator toIterator(Observable source) { /** * Returns the last element of an observable sequence with a specified source. + *

+ * * * @param source * the source Observable @@ -156,6 +167,8 @@ public Boolean call(T args) { /** * Samples the most recent value in an observable sequence. + *

+ * * * @param source * the source observable sequence. @@ -171,6 +184,8 @@ public static Iterable mostRecent(Observable source, T initialValue) { /** * Samples the next value (blocking without buffering) from in an observable sequence. + *

+ * * * @param items * the source observable sequence. @@ -203,6 +218,8 @@ private static T _singleOrDefault(BlockingObservable source, boolean hasD /** * Returns the only element of an observable sequence and throws an exception if there is not exactly one element in the observable sequence. + *

+ * * * @param source * the source Observable @@ -302,6 +319,8 @@ public static Future toFuture(final Observable source) { /** * Converts an observable sequence to an Iterable. + *

+ * * * @param source * the source Observable @@ -331,6 +350,8 @@ private Subscription protectivelyWrapAndSubscribe(Observer o) { * NOTE: This will block even if the Observable is asynchronous. *

* This is similar to {@link #subscribe(Observer)} but blocks. Because it blocks it does not need the {@link Observer#onCompleted()} or {@link Observer#onError(Exception)} methods. + *

+ * * * @param onNext * {@link Action1} @@ -395,6 +416,8 @@ public void onNext(T args) { * NOTE: This will block even if the Observable is asynchronous. *

* This is similar to {@link #subscribe(Observer)} but blocks. Because it blocks it does not need the {@link Observer#onCompleted()} or {@link Observer#onError(Exception)} methods. + *

+ * * * @param o * onNext {@link Action1 action} @@ -426,6 +449,8 @@ public void call(Object args) { /** * Returns an iterator that iterates all values of the observable. + *

+ * * * @return the iterator that could be used to iterate over the elements of the observable. */ @@ -435,6 +460,8 @@ public Iterator getIterator() { /** * Returns the last element of an observable sequence with a specified source. + *

+ * * * @return the last element in the observable sequence. */ @@ -527,6 +554,8 @@ public T lastOrDefault(T defaultValue, Object predicate) { /** * Samples the most recent value in an observable sequence. + *

+ * * * @param initialValue * the initial value that will be yielded by the enumerable sequence if no element has been sampled yet. @@ -538,6 +567,8 @@ public Iterable mostRecent(T initialValue) { /** * Samples the next value (blocking without buffering) from in an observable sequence. + *

+ * * * @return iterable that blocks upon each iteration until the next element in the observable source sequence becomes available. */ @@ -547,6 +578,8 @@ public Iterable next() { /** * Returns the only element of an observable sequence and throws an exception if there is not exactly one element in the observable sequence. + *

+ * * * @return The single element in the observable sequence. */ @@ -642,6 +675,8 @@ public Future toFuture() { /** * Converts an observable sequence to an Iterable. + *

+ * * * @return Observable converted to Iterable. */ diff --git a/rxjava-core/src/main/java/rx/observables/ConnectableObservable.java b/rxjava-core/src/main/java/rx/observables/ConnectableObservable.java index 486fd29bbe..183c6a9ef0 100644 --- a/rxjava-core/src/main/java/rx/observables/ConnectableObservable.java +++ b/rxjava-core/src/main/java/rx/observables/ConnectableObservable.java @@ -20,12 +20,29 @@ import rx.Subscription; import rx.util.functions.Func1; +/** + * A Connectable Observable resembles an ordinary Observable, except that it does not begin + * emitting a sequence of values when it is subscribed to, but only when its connect() method is + * called. In this way you can wait for all intended observers to subscribe to the Observable + * before the Observable begins emitting values. + *

+ * + *

+ * For more information see the RxJava Wiki + * + * @param + */ + public abstract class ConnectableObservable extends Observable { protected ConnectableObservable(Func1, Subscription> onSubscribe) { super(onSubscribe); } + /** + * Call a Connectable Observable's connect() method to instruct it to begin emitting the + * objects from its underlying Observable to its subscribing observers. + */ public abstract Subscription connect(); }