Skip to content

Commit

Permalink
2.x: improve autoConnect() Javadoc + add its marble (#5756)
Browse files Browse the repository at this point in the history
  • Loading branch information
@akarnokd
akarnokd authored Dec 7, 2017
1 parent 564c3dc commit ec40a5e
Show file tree
Hide file tree
Showing 2 changed files with 72 additions and 6 deletions.
40 changes: 37 additions & 3 deletions src/main/java/io/reactivex/flowables/ConnectableFlowable.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,19 +78,45 @@ public Flowable<T> refCount() {
}

/**
* Returns a Flowable that automatically connects to this ConnectableFlowable
* Returns a Flowable that automatically connects (at most once) to this ConnectableFlowable
* when the first Subscriber subscribes.
* <p>
* <img width="640" height="392" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.f.png" alt="">
* <p>
* The connection happens after the first subscription and happens at most once
* during the lifetime of the returned Flowable. If this ConnectableFlowable
* terminates, the connection is never renewed, no matter how Subscribers come
* and go. Use {@link #refCount()} to renew a connection or dispose an active
* connection when all {@code Subscriber}s have cancelled their {@code Subscription}s.
* <p>
* This overload does not allow disconnecting the connection established via
* {@link #connect(Consumer)}. Use the {@link #autoConnect(int, Consumer)} overload
* to gain access to the {@code Disposable} representing the only connection.
*
* @return a Flowable that automatically connects to this ConnectableFlowable
* when the first Subscriber subscribes
* @see #refCount()
* @see #autoConnect(int, Consumer)
*/
@NonNull
public Flowable<T> autoConnect() {
return autoConnect(1);
}
/**
* Returns a Flowable that automatically connects to this ConnectableFlowable
* Returns a Flowable that automatically connects (at most once) to this ConnectableFlowable
* when the specified number of Subscribers subscribe to it.
* <p>
* <img width="640" height="392" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.f.png" alt="">
* <p>
* The connection happens after the given number of subscriptions and happens at most once
* during the lifetime of the returned Flowable. If this ConnectableFlowable
* terminates, the connection is never renewed, no matter how Subscribers come
* and go. Use {@link #refCount()} to renew a connection or dispose an active
* connection when all {@code Subscriber}s have cancelled their {@code Subscription}s.
* <p>
* This overload does not allow disconnecting the connection established via
* {@link #connect(Consumer)}. Use the {@link #autoConnect(int, Consumer)} overload
* to gain access to the {@code Disposable} representing the only connection.
*
* @param numberOfSubscribers the number of subscribers to await before calling connect
* on the ConnectableFlowable. A non-positive value indicates
Expand All @@ -104,9 +130,17 @@ public Flowable<T> autoConnect(int numberOfSubscribers) {
}

/**
* Returns a Flowable that automatically connects to this ConnectableFlowable
* Returns a Flowable that automatically connects (at most once) to this ConnectableFlowable
* when the specified number of Subscribers subscribe to it and calls the
* specified callback with the Subscription associated with the established connection.
* <p>
* <img width="640" height="392" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.f.png" alt="">
* <p>
* The connection happens after the given number of subscriptions and happens at most once
* during the lifetime of the returned Flowable. If this ConnectableFlowable
* terminates, the connection is never renewed, no matter how Subscribers come
* and go. Use {@link #refCount()} to renew a connection or dispose an active
* connection when all {@code Subscriber}s have cancelled their {@code Subscription}s.
*
* @param numberOfSubscribers the number of subscribers to await before calling connect
* on the ConnectableFlowable. A non-positive value indicates
Expand Down
38 changes: 35 additions & 3 deletions src/main/java/io/reactivex/observables/ConnectableObservable.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,20 @@ public Observable<T> refCount() {
}

/**
* Returns an Observable that automatically connects to this ConnectableObservable
* Returns an Observable that automatically connects (at most once) to this ConnectableObservable
* when the first Observer subscribes.
* <p>
* <img width="640" height="348" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.o.png" alt="">
* <p>
* The connection happens after the first subscription and happens at most once
* during the lifetime of the returned Observable. If this ConnectableObservable
* terminates, the connection is never renewed, no matter how Observers come
* and go. Use {@link #refCount()} to renew a connection or dispose an active
* connection when all {@code Observers}s have disposed their {@code Disposable}s.
* <p>
* This overload does not allow disconnecting the connection established via
* {@link #connect(Consumer)}. Use the {@link #autoConnect(int, Consumer)} overload
* to gain access to the {@code Disposable} representing the only connection.
*
* @return an Observable that automatically connects to this ConnectableObservable
* when the first Observer subscribes
Expand All @@ -89,8 +101,20 @@ public Observable<T> autoConnect() {
}

/**
* Returns an Observable that automatically connects to this ConnectableObservable
* Returns an Observable that automatically connects (at most once) to this ConnectableObservable
* when the specified number of Observers subscribe to it.
* <p>
* <img width="640" height="348" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.o.png" alt="">
* <p>
* The connection happens after the given number of subscriptions and happens at most once
* during the lifetime of the returned Observable. If this ConnectableObservable
* terminates, the connection is never renewed, no matter how Observers come
* and go. Use {@link #refCount()} to renew a connection or dispose an active
* connection when all {@code Observers}s have disposed their {@code Disposable}s.
* <p>
* This overload does not allow disconnecting the connection established via
* {@link #connect(Consumer)}. Use the {@link #autoConnect(int, Consumer)} overload
* to gain access to the {@code Disposable} representing the only connection.
*
* @param numberOfSubscribers the number of subscribers to await before calling connect
* on the ConnectableObservable. A non-positive value indicates
Expand All @@ -104,9 +128,17 @@ public Observable<T> autoConnect(int numberOfSubscribers) {
}

/**
* Returns an Observable that automatically connects to this ConnectableObservable
* Returns an Observable that automatically connects (at most once) to this ConnectableObservable
* when the specified number of Subscribers subscribe to it and calls the
* specified callback with the Subscription associated with the established connection.
* <p>
* <img width="640" height="348" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.o.png" alt="">
* <p>
* The connection happens after the given number of subscriptions and happens at most once
* during the lifetime of the returned Observable. If this ConnectableObservable
* terminates, the connection is never renewed, no matter how Observers come
* and go. Use {@link #refCount()} to renew a connection or dispose an active
* connection when all {@code Observers}s have disposed their {@code Disposable}s.
*
* @param numberOfSubscribers the number of subscribers to await before calling connect
* on the ConnectableObservable. A non-positive value indicates
Expand Down

0 comments on commit ec40a5e

Please sign in to comment.