Skip to content

Commit

Permalink
Merge pull request #280 from DavidMGross/master
Browse files Browse the repository at this point in the history 
Diagrams and some new javadoc content for Observable subclasses
  • Loading branch information
@benjchristensen
benjchristensen committed May 28, 2013
2 parents bb79c2b + 0c19e4e commit 52640f5
Show file tree
Hide file tree
Showing 2 changed files with 52 additions and 0 deletions.
35 changes: 35 additions & 0 deletions rxjava-core/src/main/java/rx/observables/BlockingObservable.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,13 @@
* Extension of {@link Observable} that provides blocking operators.
* <p>
* Constructud via {@link #from(Observable)} or {@link Observable#toBlockingObservable()}
* <p>
* 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:
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/legend.png">
* <p>
* For more information see the <a href="https://github.com/Netflix/RxJava/wiki/Observable">RxJava Wiki</a>
*
* @param <T>
*/
Expand All @@ -49,6 +56,8 @@ public Subscription call(Observer<T> observer) {

/**
* Returns an iterator that iterates all values of the observable.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.toIterator.png">
*
* @param source
* an observable sequence to get an iterator for.
Expand All @@ -62,6 +71,8 @@ public static <T> Iterator<T> toIterator(Observable<T> source) {

/**
* Returns the last element of an observable sequence with a specified source.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.last.png">
*
* @param source
* the source Observable
Expand Down Expand Up @@ -156,6 +167,8 @@ public Boolean call(T args) {

/**
* Samples the most recent value in an observable sequence.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.mostRecent.png">
*
* @param source
* the source observable sequence.
Expand All @@ -171,6 +184,8 @@ public static <T> Iterable<T> mostRecent(Observable<T> source, T initialValue) {

/**
* Samples the next value (blocking without buffering) from in an observable sequence.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.next.png">
*
* @param items
* the source observable sequence.
Expand Down Expand Up @@ -203,6 +218,8 @@ private static <T> T _singleOrDefault(BlockingObservable<T> 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.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.single.png">
*
* @param source
* the source Observable
Expand Down Expand Up @@ -302,6 +319,8 @@ public static <T> Future<T> toFuture(final Observable<T> source) {

/**
* Converts an observable sequence to an Iterable.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.toIterable.png">
*
* @param source
* the source Observable
Expand Down Expand Up @@ -331,6 +350,8 @@ private Subscription protectivelyWrapAndSubscribe(Observer<T> o) {
* NOTE: This will block even if the Observable is asynchronous.
* <p>
* 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.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.forEach.png">
*
* @param onNext
* {@link Action1}
Expand Down Expand Up @@ -395,6 +416,8 @@ public void onNext(T args) {
* NOTE: This will block even if the Observable is asynchronous.
* <p>
* 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.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.forEach.png">
*
* @param o
* onNext {@link Action1 action}
Expand Down Expand Up @@ -426,6 +449,8 @@ public void call(Object args) {

/**
* Returns an iterator that iterates all values of the observable.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.getIterator.png">
*
* @return the iterator that could be used to iterate over the elements of the observable.
*/
Expand All @@ -435,6 +460,8 @@ public Iterator<T> getIterator() {

/**
* Returns the last element of an observable sequence with a specified source.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.last.png">
*
* @return the last element in the observable sequence.
*/
Expand Down Expand Up @@ -527,6 +554,8 @@ public T lastOrDefault(T defaultValue, Object predicate) {

/**
* Samples the most recent value in an observable sequence.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.mostRecent.png">
*
* @param initialValue
* the initial value that will be yielded by the enumerable sequence if no element has been sampled yet.
Expand All @@ -538,6 +567,8 @@ public Iterable<T> mostRecent(T initialValue) {

/**
* Samples the next value (blocking without buffering) from in an observable sequence.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.next.png">
*
* @return iterable that blocks upon each iteration until the next element in the observable source sequence becomes available.
*/
Expand All @@ -547,6 +578,8 @@ public Iterable<T> next() {

/**
* Returns the only element of an observable sequence and throws an exception if there is not exactly one element in the observable sequence.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.single.png">
*
* @return The single element in the observable sequence.
*/
Expand Down Expand Up @@ -642,6 +675,8 @@ public Future<T> toFuture() {

/**
* Converts an observable sequence to an Iterable.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.toIterable.png">
*
* @return Observable converted to Iterable.
*/
Expand Down
17 changes: 17 additions & 0 deletions rxjava-core/src/main/java/rx/observables/ConnectableObservable.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
* <p>
* <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/publishConnect.png">
* <p>
* For more information see the <a href="https://github.com/Netflix/RxJava/wiki/Observable">RxJava Wiki</a>
*
* @param <T>
*/

public abstract class ConnectableObservable<T> extends Observable<T> {

protected ConnectableObservable(Func1<Observer<T>, 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();

}

0 comments on commit 52640f5

Please sign in to comment.