From 7fcf5a999beb953e9f95e328d413e3a20fd5952b Mon Sep 17 00:00:00 2001 From: akarnokd Date: Thu, 21 Nov 2013 22:31:52 +0100 Subject: [PATCH 1/3] Operation: Join Issue #56 --- rxjava-core/src/main/java/rx/Observable.java | 23 +- .../main/java/rx/operators/OperationJoin.java | 277 ++++++++++++++++ .../java/rx/operators/OperationJoinTest.java | 310 ++++++++++++++++++ 3 files changed, 609 insertions(+), 1 deletion(-) create mode 100644 rxjava-core/src/main/java/rx/operators/OperationJoin.java create mode 100644 rxjava-core/src/test/java/rx/operators/OperationJoinTest.java diff --git a/rxjava-core/src/main/java/rx/Observable.java b/rxjava-core/src/main/java/rx/Observable.java index 53327b371d..9f5f399ed0 100644 --- a/rxjava-core/src/main/java/rx/Observable.java +++ b/rxjava-core/src/main/java/rx/Observable.java @@ -51,6 +51,7 @@ import rx.operators.OperationFirstOrDefault; import rx.operators.OperationGroupBy; import rx.operators.OperationInterval; +import rx.operators.OperationJoin; import rx.operators.OperationLast; import rx.operators.OperationMap; import rx.operators.OperationMaterialize; @@ -5662,5 +5663,25 @@ private boolean isInternalImplementation(Object o) { return isInternal; } } - + /** + * Correlates the elements of two sequences based on overlapping durations. + * @param right The right observable sequence to join elements for. + * @param leftDurationSelector A function to select the duration of each + * element of this observable sequence, used to + * determine overlap. + * @param rightDurationSelector A function to select the duration of each + * element of the right observable sequence, + * used to determine overlap. + * @param resultSelector A function invoked to compute a result element + * for any two overlapping elements of the left and + * right observable sequences. + * @return An observable sequence that contains result elements computed + * from source elements that have an overlapping duration. + * @see MSDN: Observable.Join + */ + public Observable join(Observable right, Func1> leftDurationSelector, + Func1> rightDurationSelector, + Func2 resultSelector) { + return create(new OperationJoin(this, right, leftDurationSelector, rightDurationSelector, resultSelector)); + } } diff --git a/rxjava-core/src/main/java/rx/operators/OperationJoin.java b/rxjava-core/src/main/java/rx/operators/OperationJoin.java new file mode 100644 index 0000000000..b75b8498b0 --- /dev/null +++ b/rxjava-core/src/main/java/rx/operators/OperationJoin.java @@ -0,0 +1,277 @@ +/** + * Copyright 2013 Netflix, Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package rx.operators; + +import java.util.HashMap; +import java.util.Map; +import rx.Observable; +import rx.Observable.OnSubscribeFunc; +import rx.Observer; +import rx.Subscription; +import rx.subscriptions.CompositeSubscription; +import rx.subscriptions.SerialSubscription; +import rx.util.functions.Func1; +import rx.util.functions.Func2; + +/** + * Correlates the elements of two sequences based on overlapping durations. + */ +public class OperationJoin implements OnSubscribeFunc { + final Observable left; + final Observable right; + final Func1> leftDurationSelector; + final Func1> rightDurationSelector; + final Func2 resultSelector; + public OperationJoin( + Observable left, + Observable right, + Func1> leftDurationSelector, + Func1> rightDurationSelector, + Func2 resultSelector) { + this.left = left; + this.right = right; + this.leftDurationSelector = leftDurationSelector; + this.rightDurationSelector = rightDurationSelector; + this.resultSelector = resultSelector; + } + + @Override + public Subscription onSubscribe(Observer t1) { + SerialSubscription cancel = new SerialSubscription(); + ResultSink result = new ResultSink(t1, cancel); + cancel.setSubscription(result.run()); + return cancel; + } + /** Manage the left and right sources. */ + class ResultSink { + final Object gate = new Object(); + final CompositeSubscription group = new CompositeSubscription(); + boolean leftDone; + int leftId; + final Map leftMap = new HashMap(); + boolean rightDone; + int rightId; + final Map rightMap = new HashMap(); + final Observer observer; + final Subscription cancel; + public ResultSink(Observer observer, Subscription cancel) { + this.observer = observer; + this.cancel = cancel; + } + public Subscription run() { + SerialSubscription leftCancel = new SerialSubscription(); + SerialSubscription rightCancel = new SerialSubscription(); + + group.add(leftCancel); + group.add(rightCancel); + + leftCancel.setSubscription(left.subscribe(new LeftObserver(leftCancel))); + rightCancel.setSubscription(right.subscribe(new RightObserver(rightCancel))); + + return group; + } + /** Observes the left values. */ + class LeftObserver implements Observer { + final Subscription self; + public LeftObserver(Subscription self) { + this.self = self; + } + protected void expire(int id, Subscription resource) { + synchronized (gate) { + if (leftMap.remove(id) != null && leftMap.isEmpty() && leftDone) { + observer.onCompleted(); + cancel.unsubscribe(); + } + } + group.remove(resource); + } + @Override + public void onNext(TLeft args) { + int id; + synchronized (gate) { + id = leftId++; + leftMap.put(id, args); + } + SerialSubscription md = new SerialSubscription(); + group.add(md); + + Observable duration; + try { + duration = leftDurationSelector.call(args); + } catch (Throwable t) { + observer.onError(t); + cancel.unsubscribe(); + return; + } + + md.setSubscription(duration.subscribe(new LeftDurationObserver(id, md))); + + synchronized (gate) { + for (TRight r : rightMap.values()) { + R result; + try { + result = resultSelector.call(args, r); + } catch (Throwable t) { + observer.onError(t); + cancel.unsubscribe(); + return; + } + observer.onNext(result); + } + } + } + @Override + public void onError(Throwable e) { + synchronized (gate) { + observer.onError(e); + cancel.unsubscribe(); + } + } + @Override + public void onCompleted() { + synchronized (gate) { + leftDone = true; + if (rightDone || leftMap.isEmpty()) { + observer.onCompleted(); + cancel.unsubscribe(); + } else { + self.unsubscribe(); + } + } + } + /** Observes the left duration. */ + class LeftDurationObserver implements Observer { + final int id; + final Subscription handle; + public LeftDurationObserver(int id, Subscription handle) { + this.id = id; + this.handle = handle; + } + + @Override + public void onNext(TLeftDuration args) { + expire(id, handle); + } + + @Override + public void onError(Throwable e) { + LeftObserver.this.onError(e); + } + + @Override + public void onCompleted() { + expire(id, handle); + } + + } + } + /** Observes the right values. */ + class RightObserver implements Observer { + final Subscription self; + public RightObserver(Subscription self) { + this.self = self; + } + void expire(int id, Subscription resource) { + synchronized (gate) { + if (rightMap.remove(id) != null && rightMap.isEmpty() && rightDone) { + observer.onCompleted(); + cancel.unsubscribe(); + } + } + group.remove(resource); + } + @Override + public void onNext(TRight args) { + int id = 0; + synchronized (gate) { + id = rightId++; + rightMap.put(id, args); + } + SerialSubscription md = new SerialSubscription(); + group.add(md); + + Observable duration; + try { + duration = rightDurationSelector.call(args); + } catch (Throwable t) { + observer.onError(t); + cancel.unsubscribe(); + return; + } + + md.setSubscription(duration.subscribe(new RightDurationObserver(id, md))); + + synchronized (gate) { + for (TLeft lv : leftMap.values()) { + R result; + try { + result = resultSelector.call(lv, args); + } catch (Throwable t) { + observer.onError(t); + cancel.unsubscribe(); + return; + } + observer.onNext(result); + } + } + } + @Override + public void onError(Throwable e) { + synchronized (gate) { + observer.onError(e); + cancel.unsubscribe(); + } + } + @Override + public void onCompleted() { + synchronized (gate) { + rightDone = true; + if (leftDone || rightMap.isEmpty()) { + observer.onCompleted(); + cancel.unsubscribe(); + } else { + self.unsubscribe(); + } + } + } + /** Observe the right duration. */ + class RightDurationObserver implements Observer { + final int id; + final Subscription handle; + public RightDurationObserver(int id, Subscription handle) { + this.id = id; + this.handle = handle; + } + + @Override + public void onNext(TRightDuration args) { + expire(id, handle); + } + + @Override + public void onError(Throwable e) { + RightObserver.this.onError(e); + } + + @Override + public void onCompleted() { + expire(id, handle); + } + + } + } + } +} diff --git a/rxjava-core/src/test/java/rx/operators/OperationJoinTest.java b/rxjava-core/src/test/java/rx/operators/OperationJoinTest.java new file mode 100644 index 0000000000..c96cbb1f93 --- /dev/null +++ b/rxjava-core/src/test/java/rx/operators/OperationJoinTest.java @@ -0,0 +1,310 @@ +/** + * Copyright 2013 Netflix, Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package rx.operators; + +import java.util.Collection; +import org.junit.Before; +import org.junit.Test; +import static org.mockito.Matchers.any; +import org.mockito.Mock; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.times; +import static org.mockito.Mockito.verify; +import org.mockito.MockitoAnnotations; +import rx.Observable; +import rx.Observer; +import rx.subjects.PublishSubject; +import rx.util.functions.Action1; +import rx.util.functions.Func1; +import rx.util.functions.Func2; + +public class OperationJoinTest { + @Mock + Observer observer; + + Func2 add = new Func2() { + @Override + public Integer call(Integer t1, Integer t2) { + return t1 + t2; + } + }; + Func1> just(final Observable observable) { + return new Func1>() { + @Override + public Observable call(Integer t1) { + return observable; + } + }; + } + Action1 toList(final Collection out) { + return new Action1() { + @Override + public void call(Integer t1) { + out.add(t1); + } + }; + } + @Before + public void before() { + MockitoAnnotations.initMocks(this); + } + @Test + public void normal1() { + PublishSubject source1 = PublishSubject.create(); + PublishSubject source2 = PublishSubject.create(); + + Observable m = source1.join(source2, + just(Observable.never()), + just(Observable.never()), add); + + m.subscribe(observer); + + source1.onNext(1); + source1.onNext(2); + source1.onNext(4); + + source2.onNext(16); + source2.onNext(32); + source2.onNext(64); + + source1.onCompleted(); + source2.onCompleted(); + + verify(observer, times(1)).onNext(17); + verify(observer, times(1)).onNext(18); + verify(observer, times(1)).onNext(20); + verify(observer, times(1)).onNext(33); + verify(observer, times(1)).onNext(34); + verify(observer, times(1)).onNext(36); + verify(observer, times(1)).onNext(65); + verify(observer, times(1)).onNext(66); + verify(observer, times(1)).onNext(68); + + verify(observer, times(1)).onCompleted(); + verify(observer, never()).onError(any(Throwable.class)); + } + @Test + public void normal1WithDuration() { + PublishSubject source1 = PublishSubject.create(); + PublishSubject source2 = PublishSubject.create(); + + PublishSubject duration1 = PublishSubject.create(); + + Observable m = source1.join(source2, + just(duration1), + just(Observable.never()), add); + m.subscribe(observer); + + source1.onNext(1); + source1.onNext(2); + source2.onNext(16); + + duration1.onNext(1); + + source1.onNext(4); + source1.onNext(8); + + source1.onCompleted(); + source2.onCompleted(); + + verify(observer, times(1)).onNext(17); + verify(observer, times(1)).onNext(18); + verify(observer, times(1)).onNext(20); + verify(observer, times(1)).onNext(24); + + verify(observer, times(1)).onCompleted(); + verify(observer, never()).onError(any(Throwable.class)); + + } + @Test + public void normal2() { + PublishSubject source1 = PublishSubject.create(); + PublishSubject source2 = PublishSubject.create(); + + Observable m = source1.join(source2, + just(Observable.never()), + just(Observable.never()), add); + + m.subscribe(observer); + + source1.onNext(1); + source1.onNext(2); + source1.onCompleted(); + + source2.onNext(16); + source2.onNext(32); + source2.onNext(64); + + source2.onCompleted(); + + verify(observer, times(1)).onNext(17); + verify(observer, times(1)).onNext(18); + verify(observer, times(1)).onNext(33); + verify(observer, times(1)).onNext(34); + verify(observer, times(1)).onNext(65); + verify(observer, times(1)).onNext(66); + + verify(observer, times(1)).onCompleted(); + verify(observer, never()).onError(any(Throwable.class)); + } + @Test + public void leftThrows() { + PublishSubject source1 = PublishSubject.create(); + PublishSubject source2 = PublishSubject.create(); + + Observable m = source1.join(source2, + just(Observable.never()), + just(Observable.never()), add); + + m.subscribe(observer); + + source2.onNext(1); + source1.onError(new RuntimeException("Forced failure")); + + verify(observer, times(1)).onError(any(Throwable.class)); + verify(observer, never()).onCompleted(); + verify(observer, never()).onNext(any()); + } + @Test + public void rightThrows() { + PublishSubject source1 = PublishSubject.create(); + PublishSubject source2 = PublishSubject.create(); + + Observable m = source1.join(source2, + just(Observable.never()), + just(Observable.never()), add); + + m.subscribe(observer); + + source1.onNext(1); + source2.onError(new RuntimeException("Forced failure")); + + verify(observer, times(1)).onError(any(Throwable.class)); + verify(observer, never()).onCompleted(); + verify(observer, never()).onNext(any()); + } + @Test + public void leftDurationThrows() { + PublishSubject source1 = PublishSubject.create(); + PublishSubject source2 = PublishSubject.create(); + + Observable duration1 = Observable.error(new RuntimeException("Forced failure")); + + Observable m = source1.join(source2, + just(duration1), + just(Observable.never()), add); + m.subscribe(observer); + + source1.onNext(1); + + + verify(observer, times(1)).onError(any(Throwable.class)); + verify(observer, never()).onCompleted(); + verify(observer, never()).onNext(any()); + } + @Test + public void rightDurationThrows() { + PublishSubject source1 = PublishSubject.create(); + PublishSubject source2 = PublishSubject.create(); + + Observable duration1 = Observable.error(new RuntimeException("Forced failure")); + + Observable m = source1.join(source2, + just(Observable.never()), + just(duration1), add); + m.subscribe(observer); + + source2.onNext(1); + + + verify(observer, times(1)).onError(any(Throwable.class)); + verify(observer, never()).onCompleted(); + verify(observer, never()).onNext(any()); + } + @Test + public void leftDurationSelectorThrows() { + PublishSubject source1 = PublishSubject.create(); + PublishSubject source2 = PublishSubject.create(); + + Func1> fail = new Func1>() { + @Override + public Observable call(Integer t1) { + throw new RuntimeException("Forced failure"); + } + }; + + Observable m = source1.join(source2, + fail, + just(Observable.never()), add); + m.subscribe(observer); + + source1.onNext(1); + + + verify(observer, times(1)).onError(any(Throwable.class)); + verify(observer, never()).onCompleted(); + verify(observer, never()).onNext(any()); + } + @Test + public void rightDurationSelectorThrows() { + PublishSubject source1 = PublishSubject.create(); + PublishSubject source2 = PublishSubject.create(); + + Func1> fail = new Func1>() { + @Override + public Observable call(Integer t1) { + throw new RuntimeException("Forced failure"); + } + }; + + Observable m = source1.join(source2, + just(Observable.never()), + fail, add); + m.subscribe(observer); + + source2.onNext(1); + + + verify(observer, times(1)).onError(any(Throwable.class)); + verify(observer, never()).onCompleted(); + verify(observer, never()).onNext(any()); + } + @Test + public void resultSelectorThrows() { + PublishSubject source1 = PublishSubject.create(); + PublishSubject source2 = PublishSubject.create(); + + Func2 fail = new Func2() { + @Override + public Integer call(Integer t1, Integer t2) { + throw new RuntimeException("Forced failure"); + } + }; + + Observable m = source1.join(source2, + just(Observable.never()), + just(Observable.never()), fail); + m.subscribe(observer); + + source1.onNext(1); + source2.onNext(2); + + + verify(observer, times(1)).onError(any(Throwable.class)); + verify(observer, never()).onCompleted(); + verify(observer, never()).onNext(any()); + } +} From ff5656b361e92170bc4a8b208a0487e0c5c70a35 Mon Sep 17 00:00:00 2001 From: akarnokd Date: Thu, 21 Nov 2013 22:34:13 +0100 Subject: [PATCH 2/3] Removed unused test function --- .../src/test/java/rx/operators/OperationJoinTest.java | 8 -------- 1 file changed, 8 deletions(-) diff --git a/rxjava-core/src/test/java/rx/operators/OperationJoinTest.java b/rxjava-core/src/test/java/rx/operators/OperationJoinTest.java index c96cbb1f93..8f841ebb50 100644 --- a/rxjava-core/src/test/java/rx/operators/OperationJoinTest.java +++ b/rxjava-core/src/test/java/rx/operators/OperationJoinTest.java @@ -49,14 +49,6 @@ public Observable call(Integer t1) { } }; } - Action1 toList(final Collection out) { - return new Action1() { - @Override - public void call(Integer t1) { - out.add(t1); - } - }; - } @Before public void before() { MockitoAnnotations.initMocks(this); From a4b1b5fb546708e427652c53cf1060dcaf600b2b Mon Sep 17 00:00:00 2001 From: akarnokd Date: Fri, 22 Nov 2013 23:42:09 +0100 Subject: [PATCH 3/3] Merge upstream/master into OperationJoin2 Conflicts: rxjava-core/src/main/java/rx/Observable.java --- rxjava-core/src/main/java/rx/Observable.java | 11914 +++++++++-------- 1 file changed, 5968 insertions(+), 5946 deletions(-) diff --git a/rxjava-core/src/main/java/rx/Observable.java b/rxjava-core/src/main/java/rx/Observable.java index f510bf1a1a..06a08ef576 100644 --- a/rxjava-core/src/main/java/rx/Observable.java +++ b/rxjava-core/src/main/java/rx/Observable.java @@ -1,5946 +1,5968 @@ -/** - * Copyright 2013 Netflix, Inc. - * - * Licensed under the Apache License, Version 2.0 (the "License"); you may not - * use this file except in compliance with the License. You may obtain a copy of - * the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - * License for the specific language governing permissions and limitations - * under the License. - */ -package rx; - -import static rx.util.functions.Functions.*; - -import java.util.ArrayList; -import java.util.Arrays; -import java.util.Comparator; -import java.util.List; -import java.util.concurrent.ConcurrentHashMap; -import java.util.concurrent.Future; -import java.util.concurrent.TimeUnit; - -import rx.concurrency.Schedulers; -import rx.joins.Pattern2; -import rx.joins.Plan0; -import rx.observables.BlockingObservable; -import rx.observables.ConnectableObservable; -import rx.observables.GroupedObservable; -import rx.operators.OperationAll; -import rx.operators.OperationAmb; -import rx.operators.OperationAny; -import rx.operators.OperationAverage; -import rx.operators.OperationBuffer; -import rx.operators.OperationCache; -import rx.operators.OperationCast; -import rx.operators.OperationCombineLatest; -import rx.operators.OperationConcat; -import rx.operators.OperationDebounce; -import rx.operators.OperationDefaultIfEmpty; -import rx.operators.OperationDefer; -import rx.operators.OperationDematerialize; -import rx.operators.OperationDistinct; -import rx.operators.OperationDistinctUntilChanged; -import rx.operators.OperationDoOnEach; -import rx.operators.OperationElementAt; -import rx.operators.OperationFilter; -import rx.operators.OperationFinally; -import rx.operators.OperationFirstOrDefault; -import rx.operators.OperationGroupBy; -import rx.operators.OperationInterval; -import rx.operators.OperationJoinPatterns; -import rx.operators.OperationLast; -import rx.operators.OperationMap; -import rx.operators.OperationMaterialize; -import rx.operators.OperationMerge; -import rx.operators.OperationMergeDelayError; -import rx.operators.OperationMinMax; -import rx.operators.OperationMulticast; -import rx.operators.OperationObserveOn; -import rx.operators.OperationOnErrorResumeNextViaFunction; -import rx.operators.OperationOnErrorResumeNextViaObservable; -import rx.operators.OperationOnErrorReturn; -import rx.operators.OperationOnExceptionResumeNextViaObservable; -import rx.operators.OperationParallel; -import rx.operators.OperationParallelMerge; -import rx.operators.OperationRetry; -import rx.operators.OperationSample; -import rx.operators.OperationScan; -import rx.operators.OperationSkip; -import rx.operators.OperationSkipLast; -import rx.operators.OperationSkipWhile; -import rx.operators.OperationSubscribeOn; -import rx.operators.OperationSum; -import rx.operators.OperationSwitch; -import rx.operators.OperationSynchronize; -import rx.operators.OperationTake; -import rx.operators.OperationTakeLast; -import rx.operators.OperationTakeUntil; -import rx.operators.OperationTakeWhile; -import rx.operators.OperationThrottleFirst; -import rx.operators.OperationTimeInterval; -import rx.operators.OperationTimeout; -import rx.operators.OperationTimestamp; -import rx.operators.OperationToObservableFuture; -import rx.operators.OperationToObservableIterable; -import rx.operators.OperationToObservableList; -import rx.operators.OperationToObservableSortedList; -import rx.operators.OperationUsing; -import rx.operators.OperationWindow; -import rx.operators.OperationZip; -import rx.operators.SafeObservableSubscription; -import rx.operators.SafeObserver; -import rx.plugins.RxJavaErrorHandler; -import rx.plugins.RxJavaObservableExecutionHook; -import rx.plugins.RxJavaPlugins; -import rx.subjects.AsyncSubject; -import rx.subjects.PublishSubject; -import rx.subjects.ReplaySubject; -import rx.subjects.Subject; -import rx.subscriptions.Subscriptions; -import rx.util.Closing; -import rx.util.OnErrorNotImplementedException; -import rx.util.Opening; -import rx.util.Range; -import rx.util.TimeInterval; -import rx.util.Timestamped; -import rx.util.functions.Action0; -import rx.util.functions.Action1; -import rx.util.functions.Func0; -import rx.util.functions.Func1; -import rx.util.functions.Func2; -import rx.util.functions.Func3; -import rx.util.functions.Func4; -import rx.util.functions.Func5; -import rx.util.functions.Func6; -import rx.util.functions.Func7; -import rx.util.functions.Func8; -import rx.util.functions.Func9; -import rx.util.functions.FuncN; -import rx.util.functions.Function; - -/** - * The Observable interface that implements the Reactive Pattern. - *

- * This interface provides overloaded methods for subscribing as well as - * delegate methods to the various operators. - *

- * The documentation for this interface makes use of marble diagrams. The - * following legend explains these diagrams: - *

- * - *

- * For more information see the - * RxJava Wiki - * - * @param the type of the item emitted by the Observable - */ -public class Observable { - - private final static ConcurrentHashMap internalClassMap = new ConcurrentHashMap(); - - /** - * Executed when 'subscribe' is invoked. - */ - private final OnSubscribeFunc onSubscribe; - - /** - * Function interface for work to be performed when an {@link Observable} - * is subscribed to via {@link Observable#subscribe(Observer)} - * - * @param - */ - public static interface OnSubscribeFunc extends Function { - - public Subscription onSubscribe(Observer t1); - - } - - /** - * Observable with Function to execute when subscribed to. - *

- * NOTE: Use {@link #create(OnSubscribeFunc)} to create an Observable - * instead of this constructor unless you specifically have a need for - * inheritance. - * - * @param onSubscribe {@link OnSubscribeFunc} to be executed when - * {@link #subscribe(Observer)} is called - */ - protected Observable(OnSubscribeFunc onSubscribe) { - this.onSubscribe = onSubscribe; - } - - private final static RxJavaObservableExecutionHook hook = RxJavaPlugins.getInstance().getObservableExecutionHook(); - - /** - * An {@link Observer} must call an Observable's {@code subscribe} method in - * order to receive items and notifications from the Observable. - *

- * A typical implementation of {@code subscribe} does the following: - *

    - *
  1. It stores a reference to the Observer in a collection object, such as - * a {@code List} object.
  2. - *
  3. It returns a reference to the {@link Subscription} interface. This - * enables Observers to unsubscribe, that is, to stop receiving items - * and notifications before the Observable stops sending them, which - * also invokes the Observer's {@link Observer#onCompleted onCompleted} - * method.
  4. - *

- * An Observable<T> instance is responsible for accepting - * all subscriptions and notifying all Observers. Unless the documentation - * for a particular Observable<T> implementation - * indicates otherwise, Observers should make no assumptions about the order - * in which multiple Observers will receive their notifications. - *

- * For more information see the - * RxJava Wiki - * - * @param observer the Observer - * @return a {@link Subscription} reference with which the {@link Observer} - * can stop receiving items before the Observable has finished - * sending them - * @throws IllegalArgumentException if the {@link Observer} provided as the - * argument to {@code subscribe()} is - * {@code null} - */ - public Subscription subscribe(Observer observer) { - // allow the hook to intercept and/or decorate - OnSubscribeFunc onSubscribeFunction = hook.onSubscribeStart(this, onSubscribe); - // validate and proceed - if (observer == null) { - throw new IllegalArgumentException("observer can not be null"); - } - if (onSubscribeFunction == null) { - throw new IllegalStateException("onSubscribe function can not be null."); - // the subscribe function can also be overridden but generally that's not the appropriate approach so I won't mention that in the exception - } - try { - /** - * See https://github.com/Netflix/RxJava/issues/216 for discussion on "Guideline 6.4: Protect calls to user code from within an operator" - */ - if (isInternalImplementation(observer)) { - Subscription s = onSubscribeFunction.onSubscribe(observer); - if (s == null) { - // this generally shouldn't be the case on a 'trusted' onSubscribe but in case it happens - // we want to gracefully handle it the same as AtomicObservableSubscription does - return hook.onSubscribeReturn(this, Subscriptions.empty()); - } else { - return hook.onSubscribeReturn(this, s); - } - } else { - SafeObservableSubscription subscription = new SafeObservableSubscription(); - subscription.wrap(onSubscribeFunction.onSubscribe(new SafeObserver(subscription, observer))); - return hook.onSubscribeReturn(this, subscription); - } - } catch (OnErrorNotImplementedException e) { - // special handling when onError is not implemented ... we just rethrow - throw e; - } catch (Throwable e) { - // if an unhandled error occurs executing the onSubscribe we will propagate it - try { - observer.onError(hook.onSubscribeError(this, e)); - } catch (OnErrorNotImplementedException e2) { - // special handling when onError is not implemented ... we just rethrow - throw e2; - } catch (Throwable e2) { - // if this happens it means the onError itself failed (perhaps an invalid function implementation) - // so we are unable to propagate the error correctly and will just throw - RuntimeException r = new RuntimeException("Error occurred attempting to subscribe [" + e.getMessage() + "] and then again while trying to pass to onError.", e2); - hook.onSubscribeError(this, r); - throw r; - } - return Subscriptions.empty(); - } - } - - /** - * An {@link Observer} must call an Observable's {@code subscribe} method in - * order to receive items and notifications from the Observable. - *

- * A typical implementation of {@code subscribe} does the following: - *

    - *
  1. It stores a reference to the Observer in a collection object, such as - * a {@code List} object.
  2. - *
  3. It returns a reference to the {@link Subscription} interface. This - * enables Observers to unsubscribe, that is, to stop receiving items - * and notifications before the Observable stops sending them, which - * also invokes the Observer's {@link Observer#onCompleted onCompleted} - * method.
  4. - *

- * An {@code Observable} instance is responsible for accepting all - * subscriptions and notifying all Observers. Unless the documentation for a - * particular {@code Observable} implementation indicates otherwise, - * Observers should make no assumptions about the order in which multiple - * Observers will receive their notifications. - *

- * For more information see the - * RxJava Wiki - * - * @param observer the Observer - * @param scheduler the {@link Scheduler} on which Observers subscribe to - * the Observable - * @return a {@link Subscription} reference with which Observers can stop - * receiving items and notifications before the Observable has - * finished sending them - * @throws IllegalArgumentException if an argument to {@code subscribe()} - * is {@code null} - */ - public Subscription subscribe(Observer observer, Scheduler scheduler) { - return subscribeOn(scheduler).subscribe(observer); - } - - /** - * Protects against errors being thrown from Observer implementations and - * ensures onNext/onError/onCompleted contract compliance. - *

- * See https://github.com/Netflix/RxJava/issues/216 for a discussion on - * "Guideline 6.4: Protect calls to user code from within an operator" - */ - private Subscription protectivelyWrapAndSubscribe(Observer o) { - SafeObservableSubscription subscription = new SafeObservableSubscription(); - return subscription.wrap(subscribe(new SafeObserver(subscription, o))); - } - - /** - * Subscribe and ignore all events. - * - * @return - */ - public Subscription subscribe() { - return protectivelyWrapAndSubscribe(new Observer() { - - @Override - public void onCompleted() { - // do nothing - } - - @Override - public void onError(Throwable e) { - handleError(e); - throw new OnErrorNotImplementedException(e); - } - - @Override - public void onNext(T args) { - // do nothing - } - - }); - } - - /** - * An {@link Observer} must call an Observable's {@code subscribe} method - * in order to receive items and notifications from the Observable. - * - * @param onNext - * @return - */ - public Subscription subscribe(final Action1 onNext) { - if (onNext == null) { - throw new IllegalArgumentException("onNext can not be null"); - } - - /** - * Wrapping since raw functions provided by the user are being invoked. - * - * See https://github.com/Netflix/RxJava/issues/216 for discussion on "Guideline 6.4: Protect calls to user code from within an operator" - */ - return protectivelyWrapAndSubscribe(new Observer() { - - @Override - public void onCompleted() { - // do nothing - } - - @Override - public void onError(Throwable e) { - handleError(e); - throw new OnErrorNotImplementedException(e); - } - - @Override - public void onNext(T args) { - onNext.call(args); - } - - }); - } - - /** - * An {@link Observer} must call an Observable's {@code subscribe} method in - * order to receive items and notifications from the Observable. - * - * @param onNext - * @param scheduler - * @return - */ - public Subscription subscribe(final Action1 onNext, Scheduler scheduler) { - return subscribeOn(scheduler).subscribe(onNext); - } - - /** - * An {@link Observer} must call an Observable's {@code subscribe} method in - * order to receive items and notifications from the Observable. - * - * @param onNext - * @param onError - * @return - */ - public Subscription subscribe(final Action1 onNext, final Action1 onError) { - if (onNext == null) { - throw new IllegalArgumentException("onNext can not be null"); - } - if (onError == null) { - throw new IllegalArgumentException("onError can not be null"); - } - - /** - * Wrapping since raw functions provided by the user are being invoked. - * - * See https://github.com/Netflix/RxJava/issues/216 for discussion on "Guideline 6.4: Protect calls to user code from within an operator" - */ - return protectivelyWrapAndSubscribe(new Observer() { - - @Override - public void onCompleted() { - // do nothing - } - - @Override - public void onError(Throwable e) { - handleError(e); - onError.call(e); - } - - @Override - public void onNext(T args) { - onNext.call(args); - } - - }); - } - - /** - * An {@link Observer} must call an Observable's {@code subscribe} method in - * order to receive items and notifications from the Observable. - * - * @param onNext - * @param onError - * @param scheduler - * @return - */ - public Subscription subscribe(final Action1 onNext, final Action1 onError, Scheduler scheduler) { - return subscribeOn(scheduler).subscribe(onNext, onError); - } - - /** - * An {@link Observer} must call an Observable's {@code subscribe} method in - * order to receive items and notifications from the Observable. - * - * @param onNext - * @param onError - * @param onComplete - * @return - */ - public Subscription subscribe(final Action1 onNext, final Action1 onError, final Action0 onComplete) { - if (onNext == null) { - throw new IllegalArgumentException("onNext can not be null"); - } - if (onError == null) { - throw new IllegalArgumentException("onError can not be null"); - } - if (onComplete == null) { - throw new IllegalArgumentException("onComplete can not be null"); - } - - /** - * Wrapping since raw functions provided by the user are being invoked. - * - * See https://github.com/Netflix/RxJava/issues/216 for discussion on "Guideline 6.4: Protect calls to user code from within an operator" - */ - return protectivelyWrapAndSubscribe(new Observer() { - - @Override - public void onCompleted() { - onComplete.call(); - } - - @Override - public void onError(Throwable e) { - handleError(e); - onError.call(e); - } - - @Override - public void onNext(T args) { - onNext.call(args); - } - - }); - } - - /** - * An {@link Observer} must call an Observable's {@code subscribe} method in - * order to receive items and notifications from the Observable. - * - * @param onNext - * @param onError - * @param onComplete - * @param scheduler - * @return - */ - public Subscription subscribe(final Action1 onNext, final Action1 onError, final Action0 onComplete, Scheduler scheduler) { - return subscribeOn(scheduler).subscribe(onNext, onError, onComplete); - } - - /** - * Returns a {@link ConnectableObservable} that upon connection causes the - * source Observable to push results into the specified subject. - * - * @param subject the {@link Subject} for the {@link ConnectableObservable} - * to push source items into - * @param result type - * @return a {@link ConnectableObservable} that upon connection causes the - * source Observable to push results into the specified - * {@link Subject} - * @see Observable.publish() and Observable.multicast() - */ - public ConnectableObservable multicast(Subject subject) { - return OperationMulticast.multicast(this, subject); - } - - /** - * Allow the {@link RxJavaErrorHandler} to receive the exception from - * onError. - * - * @param e - */ - private void handleError(Throwable e) { - // onError should be rare so we'll only fetch when needed - RxJavaPlugins.getInstance().getErrorHandler().handleError(e); - } - - /** - * An Observable that never sends any information to an {@link Observer}. - * - * This Observable is useful primarily for testing purposes. - * - * @param the type of item emitted by the Observable - */ - private static class NeverObservable extends Observable { - public NeverObservable() { - super(new OnSubscribeFunc() { - - @Override - public Subscription onSubscribe(Observer t1) { - return Subscriptions.empty(); - } - - }); - } - } - - /** - * An Observable that invokes {@link Observer#onError onError} when the - * {@link Observer} subscribes to it. - * - * @param the type of item emitted by the Observable - */ - private static class ThrowObservable extends Observable { - - public ThrowObservable(final Throwable exception) { - super(new OnSubscribeFunc() { - - /** - * Accepts an {@link Observer} and calls its - * {@link Observer#onError onError} method. - * - * @param observer an {@link Observer} of this Observable - * @return a reference to the subscription - */ - @Override - public Subscription onSubscribe(Observer observer) { - observer.onError(exception); - return Subscriptions.empty(); - } - - }); - } - - } - - /** - * Creates an Observable that will execute the given function when an - * {@link Observer} subscribes to it. - *

- * - *

- * Write the function you pass to create so that it behaves as - * an Observable: It should invoke the Observer's - * {@link Observer#onNext onNext}, {@link Observer#onError onError}, and - * {@link Observer#onCompleted onCompleted} methods appropriately. - *

- * A well-formed Observable must invoke either the Observer's - * onCompleted method exactly once or its onError - * method exactly once. - *

- * See Rx Design - * Guidelines (PDF) for detailed information. - * - * @param the type of the items that this Observable emits - * @param func a function that accepts an {@code Observer}, invokes its - * {@code onNext}, {@code onError}, and {@code onCompleted} - * methods as appropriate, and returns a {@link Subscription} to - * allow the Observer to cancel the subscription - * @return an Observable that, when an {@link Observer} subscribes to it, - * will execute the given function - * @see create() - */ - public static Observable create(OnSubscribeFunc func) { - return new Observable(func); - } - - /** - * Returns an Observable that emits no data to the {@link Observer} and - * immediately invokes its {@link Observer#onCompleted onCompleted} method. - *

- * - * - * @param the type of the items (ostensibly) emitted by the Observable - * @return an Observable that returns no data to the {@link Observer} and - * immediately invokes the {@link Observer}'s - * {@link Observer#onCompleted() onCompleted} method - * @see empty() - * @see MSDN: Observable.Empty Method - */ - public static Observable empty() { - return from(new ArrayList()); - } - - /** - * Returns an Observable that emits no data to the {@link Observer} and - * immediately invokes its {@link Observer#onCompleted onCompleted} method - * with the specified scheduler. - *

- * - * - * @param scheduler the scheduler to call the - {@link Observer#onCompleted onCompleted} method - * @param the type of the items (ostensibly) emitted by the Observable - * @return an Observable that returns no data to the {@link Observer} and - * immediately invokes the {@link Observer}'s - * {@link Observer#onCompleted() onCompleted} method with the - * specified scheduler - * @see empty() - * @see MSDN: Observable.Empty Method (IScheduler) - */ - public static Observable empty(Scheduler scheduler) { - return Observable. empty().subscribeOn(scheduler); - } - - /** - * Returns an Observable that invokes an {@link Observer}'s - * {@link Observer#onError onError} method when the Observer subscribes to - * it. - *

- * - * - * @param exception the particular error to report - * @param the type of the items (ostensibly) emitted by the Observable - * @return an Observable that invokes the {@link Observer}'s - * {@link Observer#onError onError} method when the Observer - * subscribes to it - * @see error() - * @see MSDN: Observable.Throw Method - */ - public static Observable error(Throwable exception) { - return new ThrowObservable(exception); - } - - /** - * Returns an Observable that invokes an {@link Observer}'s - * {@link Observer#onError onError} method with the specified scheduler. - *

- * - * - * @param exception the particular error to report - * @param scheduler the scheduler to call the - * {@link Observer#onError onError} method - * @param the type of the items (ostensibly) emitted by the Observable - * @return an Observable that invokes the {@link Observer}'s - * {@link Observer#onError onError} method with the specified - * scheduler - * @see error() - * @see MSDN: Observable.Throw Method - */ - public static Observable error(Throwable exception, Scheduler scheduler) { - return Observable. error(exception).subscribeOn(scheduler); - } - - /** - * Converts an {@link Iterable} sequence into an Observable. - *

- * - *

- * Note: the entire iterable sequence is immediately emitted each time an - * {@link Observer} subscribes. Since this occurs before the - * {@link Subscription} is returned, it is not possible to unsubscribe from - * the sequence before it completes. - * - * @param iterable the source {@link Iterable} sequence - * @param the type of items in the {@link Iterable} sequence and the - * type of items to be emitted by the resulting Observable - * @return an Observable that emits each item in the source {@link Iterable} - * sequence - * @see from() - */ - public static Observable from(Iterable iterable) { - return create(OperationToObservableIterable.toObservableIterable(iterable)); - } - - /** - * Converts an {@link Iterable} sequence into an Observable with the specified scheduler. - *

- * - * - * @param iterable the source {@link Iterable} sequence - * @param scheduler the scheduler to emit the items of the iterable - * @param the type of items in the {@link Iterable} sequence and the - * type of items to be emitted by the resulting Observable - * @return an Observable that emits each item in the source {@link Iterable} - * sequence with the specified scheduler - * @see from() - * @see MSDN: Observable.ToObservable - */ - public static Observable from(Iterable iterable, Scheduler scheduler) { - return from(iterable).observeOn(scheduler); - } - - /** - * Converts an Array into an Observable. - *

- * - *

- * Note: the entire array is immediately emitted each time an - * {@link Observer} subscribes. Since this occurs before the - * {@link Subscription} is returned, it is not possible to unsubscribe from - * the sequence before it completes. - * - * @param items the source sequence - * @param the type of items in the Array and the type of items to be - * emitted by the resulting Observable - * @return an Observable that emits each item in the source Array - * @see from() - */ - public static Observable from(T[] items) { - return create(OperationToObservableIterable.toObservableIterable(Arrays.asList(items))); - } - - /** - * Converts an item into an Observable that emits that item. - *

- * - *

- * Note: the item is immediately emitted each time an {@link Observer} - * subscribes. Since this occurs before the {@link Subscription} is - * returned, it is not possible to unsubscribe from the sequence before it - * completes. - * - * @param t1 the item - * @param the type of the item, and the type of the item to be - * emitted by the resulting Observable - * @return an Observable that emits the item - * @see from() - */ - @SuppressWarnings("unchecked") - // suppress unchecked because we are using varargs inside the method - public static Observable from(T t1) { - return from(Arrays.asList(t1)); - } - - /** - * Converts a series of items into an Observable. - *

- * - *

- * Note: the items will be immediately emitted each time an {@link Observer} - * subscribes. Since this occurs before the {@link Subscription} is - * returned, it is not possible to unsubscribe from the sequence before it - * completes. - * - * @param t1 first item - * @param t2 second item - * @param the type of items, and the type of items to be emitted by the - * resulting Observable - * @return an Observable that emits each item - * @see from() - */ - @SuppressWarnings("unchecked") - // suppress unchecked because we are using varargs inside the method - public static Observable from(T t1, T t2) { - return from(Arrays.asList(t1, t2)); - } - - /** - * Converts a series of items into an Observable. - *

- * - *

- * Note: the items will be immediately emitted each time an {@link Observer} - * subscribes. Since this occurs before the {@link Subscription} is - * returned, it is not possible to unsubscribe from the sequence before it - * completes. - * - * @param t1 first item - * @param t2 second item - * @param t3 third item - * @param the type of items, and the type of items to be emitted by the - * resulting Observable - * @return an Observable that emits each item - * @see from() - */ - @SuppressWarnings("unchecked") - // suppress unchecked because we are using varargs inside the method - public static Observable from(T t1, T t2, T t3) { - return from(Arrays.asList(t1, t2, t3)); - } - - /** - * Converts a series of items into an Observable. - *

- * - *

- * Note: the items will be immediately emitted each time an {@link Observer} - * subscribes. Since this occurs before the {@link Subscription} is - * returned, it is not possible to unsubscribe from the sequence before it - * completes. - * - * @param t1 first item - * @param t2 second item - * @param t3 third item - * @param t4 fourth item - * @param the type of items, and the type of items to be emitted by the - * resulting Observable - * @return an Observable that emits each item - * @see from() - */ - @SuppressWarnings("unchecked") - // suppress unchecked because we are using varargs inside the method - public static Observable from(T t1, T t2, T t3, T t4) { - return from(Arrays.asList(t1, t2, t3, t4)); - } - - /** - * Converts a series of items into an Observable. - *

- * - *

- * Note: the items will be immediately emitted each time an {@link Observer} - * subscribes. Since this occurs before the {@link Subscription} is - * returned, it is not possible to unsubscribe from the sequence before it - * completes. - * - * @param t1 first item - * @param t2 second item - * @param t3 third item - * @param t4 fourth item - * @param t5 fifth item - * @param the type of items, and the type of items to be emitted by the - * resulting Observable - * @return an Observable that emits each item - * @see from() - */ - @SuppressWarnings("unchecked") - // suppress unchecked because we are using varargs inside the method - public static Observable from(T t1, T t2, T t3, T t4, T t5) { - return from(Arrays.asList(t1, t2, t3, t4, t5)); - } - - /** - * Converts a series of items into an Observable. - *

- * - *

- * Note: the items will be immediately emitted each time an {@link Observer} - * subscribes. Since this occurs before the {@link Subscription} is - * returned, it is not possible to unsubscribe from the sequence before it - * completes. - * - * @param t1 first item - * @param t2 second item - * @param t3 third item - * @param t4 fourth item - * @param t5 fifth item - * @param t6 sixth item - * @param the type of items, and the type of items to be emitted by the - * resulting Observable - * @return an Observable that emits each item - * @see from() - */ - @SuppressWarnings("unchecked") - // suppress unchecked because we are using varargs inside the method - public static Observable from(T t1, T t2, T t3, T t4, T t5, T t6) { - return from(Arrays.asList(t1, t2, t3, t4, t5, t6)); - } - - /** - * Converts a series of items into an Observable. - *

- * - *

- * Note: the items will be immediately emitted each time an {@link Observer} - * subscribes. Since this occurs before the {@link Subscription} is - * returned, it is not possible to unsubscribe from the sequence before it - * completes. - * - * @param t1 first item - * @param t2 second item - * @param t3 third item - * @param t4 fourth item - * @param t5 fifth item - * @param t6 sixth item - * @param t7 seventh item - * @param the type of items, and the type of items to be emitted by the - * resulting Observable - * @return an Observable that emits each item - * @see from() - */ - @SuppressWarnings("unchecked") - // suppress unchecked because we are using varargs inside the method - public static Observable from(T t1, T t2, T t3, T t4, T t5, T t6, T t7) { - return from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7)); - } - - /** - * Converts a series of items into an Observable. - *

- * - *

- * Note: the items will be immediately emitted each time an {@link Observer} - * subscribes. Since this occurs before the {@link Subscription} is - * returned, it is not possible to unsubscribe from the sequence before it - * completes. - * - * @param t1 first item - * @param t2 second item - * @param t3 third item - * @param t4 fourth item - * @param t5 fifth item - * @param t6 sixth item - * @param t7 seventh item - * @param t8 eighth item - * @param the type of items, and the type of items to be emitted by the - * resulting Observable - * @return an Observable that emits each item - * @see from() - */ - @SuppressWarnings("unchecked") - // suppress unchecked because we are using varargs inside the method - public static Observable from(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8) { - return from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7, t8)); - } - - /** - * Converts a series of items into an Observable. - *

- * - *

- * Note: the items will be immediately emitted each time an {@link Observer} - * subscribes. Since this occurs before the {@link Subscription} is - * returned, it is not possible to unsubscribe from the sequence before it - * completes. - * - * @param t1 first item - * @param t2 second item - * @param t3 third item - * @param t4 fourth item - * @param t5 fifth item - * @param t6 sixth item - * @param t7 seventh item - * @param t8 eighth item - * @param t9 ninth item - * @param the type of items, and the type of items to be emitted by the - * resulting Observable - * @return an Observable that emits each item - * @see from() - */ - @SuppressWarnings("unchecked") - // suppress unchecked because we are using varargs inside the method - public static Observable from(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8, T t9) { - return from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7, t8, t9)); - } - - /** - * Converts a series of items into an Observable. - *

- * - *

- * Note: the items will be immediately emitted each time an {@link Observer} - * subscribes. Since this occurs before the {@link Subscription} is - * returned, it is not possible to unsubscribe from the sequence before it - * completes. - * - * @param t1 first item - * @param t2 second item - * @param t3 third item - * @param t4 fourth item - * @param t5 fifth item - * @param t6 sixth item - * @param t7 seventh item - * @param t8 eighth item - * @param t9 ninth item - * @param t10 tenth item - * @param the type of items, and the type of items to be emitted by the - * resulting Observable - * @return an Observable that emits each item - * @see from() - */ - @SuppressWarnings("unchecked") - // suppress unchecked because we are using varargs inside the method - public static Observable from(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8, T t9, T t10) { - return from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10)); - } - - /** - * Generates an Observable that emits a sequence of integers within a - * specified range. - *

- * - *

- * Note: the entire range is immediately emitted each time an - * {@link Observer} subscribes. Since this occurs before the - * {@link Subscription} is returned, it is not possible to unsubscribe from - * the sequence before it completes. - * - * @param start the value of the first integer in the sequence - * @param count the number of sequential integers to generate - * @return an Observable that emits a range of sequential integers - * @see range() - * @see Observable.Range Method (Int32, Int32) - */ - public static Observable range(int start, int count) { - return from(Range.createWithCount(start, count)); - } - - /** - * Generates an Observable that emits a sequence of integers within a - * specified range with the specified scheduler. - *

- * - * @param start the value of the first integer in the sequence - * @param count the number of sequential integers to generate - * @param scheduler the scheduler to run the generator loop on - * @return an Observable that emits a range of sequential integers - * @see range() - * @see Observable.Range Method (Int32, Int32, IScheduler) - */ - public static Observable range(int start, int count, Scheduler scheduler) { - return range(start, count).observeOn(scheduler); - } - - /** - * Returns an Observable that calls an Observable factory to create its - * Observable for each new Observer that subscribes. That is, for each - * subscriber, the actuall Observable is determined by the factory function. - *

- * - *

- * The defer operator allows you to defer or delay emitting items from an - * Observable until such time as an Observer subscribes to the Observable. - * This allows an {@link Observer} to easily obtain updates or a refreshed - * version of the sequence. - * - * @param observableFactory the Observable factory function to invoke for - * each {@link Observer} that subscribes to the - * resulting Observable - * @param the type of the items emitted by the Observable - * @return an Observable whose {@link Observer}s trigger an invocation of - * the given Observable factory function - * @see defer() - */ - public static Observable defer(Func0> observableFactory) { - return create(OperationDefer.defer(observableFactory)); - } - - /** - * Returns an Observable that emits a single item and then completes. - *

- * - *

- * To convert any object into an Observable that emits that object, pass - * that object into the just method. - *

- * This is similar to the {@link #from(java.lang.Object[])} method, except - * that from() will convert an {@link Iterable} object into an - * Observable that emits each of the items in the Iterable, one at a time, - * while the just() method converts an Iterable into an - * Observable that emits the entire Iterable as a single item. - * - * @param value the item to pass to the {@link Observer}'s - * {@link Observer#onNext onNext} method - * @param the type of that item - * @return an Observable that emits a single item and then completes - * @see just() - */ - public static Observable just(T value) { - List list = new ArrayList(); - list.add(value); - - return from(list); - } - - /** - * Returns an Observable that emits a single item and then completes on a - * specified scheduler. - *

- * This is a scheduler version of {@link Observable#just(Object)}. - * - * @param value the item to pass to the {@link Observer}'s - * {@link Observer#onNext onNext} method - * @param the type of that item - * @param scheduler the scheduler to send the single element on - * @return an Observable that emits a single item and then completes on a - * specified scheduler - * @see just() - */ - public static Observable just(T value, Scheduler scheduler) { - return just(value).observeOn(scheduler); - } - - /** - * Flattens a sequence of Observables emitted by an Observable into one - * Observable, without any transformation. - *

- * - *

- * You can combine the items emitted by multiple Observables so that they - * act like a single Observable, by using the {@code merge} method. - * - * @param source an Observable that emits Observables - * @return an Observable that emits items that are the result of flattening - * the items emitted by the Observables emitted by the - * {@code source} Observable - * @see merge() - * @see MSDN: Observable.Merge Method - */ - public static Observable merge(Observable> source) { - return create(OperationMerge.merge(source)); - } - - /** - * Flattens a series of Observables into one Observable, without any - * transformation. - *

- * - *

- * You can combine items emitted by multiple Observables so that they act - * like a single Observable, by using the {@code merge} method. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see merge() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable merge(Observable t1, Observable t2) { - return create(OperationMerge.merge(t1, t2)); - } - - /** - * Flattens a series of Observables into one Observable, without any - * transformation. - *

- * - *

- * You can combine items emitted by multiple Observables so that they act - * like a single Observable, by using the {@code merge} method. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see merge() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable merge(Observable t1, Observable t2, Observable t3) { - return create(OperationMerge.merge(t1, t2, t3)); - } - - /** - * Flattens a series of Observables into one Observable, without any - * transformation. - *

- * - *

- * You can combine items emitted by multiple Observables so that they act - * like a single Observable, by using the {@code merge} method. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @param t4 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see merge() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable merge(Observable t1, Observable t2, Observable t3, Observable t4) { - return create(OperationMerge.merge(t1, t2, t3, t4)); - } - - /** - * Flattens a series of Observables into one Observable, without any - * transformation. - *

- * - *

- * You can combine items emitted by multiple Observables so that they act - * like a single Observable, by using the {@code merge} method. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @param t4 an Observable to be merged - * @param t5 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see merge() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable merge(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5) { - return create(OperationMerge.merge(t1, t2, t3, t4, t5)); - } - - /** - * Flattens a series of Observables into one Observable, without any - * transformation. - *

- * - *

- * You can combine items emitted by multiple Observables so that they act - * like a single Observable, by using the {@code merge} method. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @param t4 an Observable to be merged - * @param t5 an Observable to be merged - * @param t6 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see merge() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable merge(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6) { - return create(OperationMerge.merge(t1, t2, t3, t4, t5, t6)); - } - - /** - * Flattens a series of Observables into one Observable, without any - * transformation. - *

- * - *

- * You can combine items emitted by multiple Observables so that they act - * like a single Observable, by using the {@code merge} method. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @param t4 an Observable to be merged - * @param t5 an Observable to be merged - * @param t6 an Observable to be merged - * @param t7 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see merge() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable merge(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7) { - return create(OperationMerge.merge(t1, t2, t3, t4, t5, t6, t7)); - } - - /** - * Flattens a series of Observables into one Observable, without any - * transformation. - *

- * - *

- * You can combine items emitted by multiple Observables so that they act - * like a single Observable, by using the {@code merge} method. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @param t4 an Observable to be merged - * @param t5 an Observable to be merged - * @param t6 an Observable to be merged - * @param t7 an Observable to be merged - * @param t8 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see merge() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable merge(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7, Observable t8) { - return create(OperationMerge.merge(t1, t2, t3, t4, t5, t6, t7, t8)); - } - - /** - * Flattens a series of Observables into one Observable, without any - * transformation. - *

- * - *

- * You can combine items emitted by multiple Observables so that they act - * like a single Observable, by using the {@code merge} method. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @param t4 an Observable to be merged - * @param t5 an Observable to be merged - * @param t6 an Observable to be merged - * @param t7 an Observable to be merged - * @param t8 an Observable to be merged - * @param t9 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see merge() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable merge(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7, Observable t8, Observable t9) { - return create(OperationMerge.merge(t1, t2, t3, t4, t5, t6, t7, t8, t9)); - } - - /** - * Returns an Observable that emits the items emitted by two or more - * Observables, one after the other. - *

- * - * - * @param observables an Observable that emits Observables - * @return an Observable that emits items that are the result of combining - * the items emitted by the {@code source} Observables, one after - * the other - * @see concat() - * @see MSDN: Observable.Concat Method - */ - public static Observable concat(Observable> observables) { - return create(OperationConcat.concat(observables)); - } - - /** - * Returns an Observable that emits the items emitted by two Observables, - * one after the other. - *

- * - * - * @param t1 an Observable to be concatenated - * @param t2 an Observable to be concatenated - * @return an Observable that emits items that are the result of combining - * the items emitted by the {@code source} Observables, one after - * the other - * @see concat() - * @see MSDN: Observable.Concat Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable concat(Observable t1, Observable t2) { - return create(OperationConcat.concat(t1, t2)); - } - - /** - * Returns an Observable that emits the items emitted by three Observables, - * one after the other. - *

- * - * - * @param t1 an Observable to be concatenated - * @param t2 an Observable to be concatenated - * @param t3 an Observable to be concatenated - * - * @return an Observable that emits items that are the result of combining - * the items emitted by the {@code source} Observables, one after - * the other - * @see concat() - * @see MSDN: Observable.Concat Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable concat(Observable t1, Observable t2, Observable t3) { - return create(OperationConcat.concat(t1, t2, t3)); - } - - /** - * Returns an Observable that emits the items emitted by four Observables, - * one after the other. - *

- * - * - * @param t1 an Observable to be concatenated - * @param t2 an Observable to be concatenated - * @param t3 an Observable to be concatenated - * @param t4 an Observable to be concatenated - * @return an Observable that emits items that are the result of combining - * the items emitted by the {@code source} Observables, one after - * the other - * @see concat() - * @see MSDN: Observable.Concat Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable concat(Observable t1, Observable t2, Observable t3, Observable t4) { - return create(OperationConcat.concat(t1, t2, t3, t4)); - } - - /** - * Returns an Observable that emits the items emitted by five Observables, - * one after the other. - *

- * - * - * @param t1 an Observable to be concatenated - * @param t2 an Observable to be concatenated - * @param t3 an Observable to be concatenated - * @param t4 an Observable to be concatenated - * @param t5 an Observable to be concatenated - * @return an Observable that emits items that are the result of combining - * the items emitted by the {@code source} Observables, one after - * the other - * @see concat() - * @see MSDN: Observable.Concat Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable concat(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5) { - return create(OperationConcat.concat(t1, t2, t3, t4, t5)); - } - - /** - * Returns an Observable that emits the items emitted by six Observables, - * one after the other. - *

- * - * - * @param t1 an Observable to be concatenated - * @param t2 an Observable to be concatenated - * @param t3 an Observable to be concatenated - * @param t4 an Observable to be concatenated - * @param t5 an Observable to be concatenated - * @param t6 an Observable to be concatenated - * @return an Observable that emits items that are the result of combining - * the items emitted by the {@code source} Observables, one after - * the other - * @see concat() - * @see MSDN: Observable.Concat Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable concat(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6) { - return create(OperationConcat.concat(t1, t2, t3, t4, t5, t6)); - } - - /** - * Returns an Observable that emits the items emitted by secven Observables, - * one after the other. - *

- * - * - * @param t1 an Observable to be concatenated - * @param t2 an Observable to be concatenated - * @param t3 an Observable to be concatenated - * @param t4 an Observable to be concatenated - * @param t5 an Observable to be concatenated - * @param t6 an Observable to be concatenated - * @param t7 an Observable to be concatenated - * @return an Observable that emits items that are the result of combining - * the items emitted by the {@code source} Observables, one after - * the other - * @see concat() - * @see MSDN: Observable.Concat Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable concat(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7) { - return create(OperationConcat.concat(t1, t2, t3, t4, t5, t6, t7)); - } - - /** - * Returns an Observable that emits the items emitted by eight Observables, - * one after the other. - *

- * - * - * @param t1 an Observable to be concatenated - * @param t2 an Observable to be concatenated - * @param t3 an Observable to be concatenated - * @param t4 an Observable to be concatenated - * @param t5 an Observable to be concatenated - * @param t6 an Observable to be concatenated - * @param t7 an Observable to be concatenated - * @param t8 an Observable to be concatenated - * @return an Observable that emits items that are the result of combining - * the items emitted by the {@code source} Observables, one after - * the other - * @see concat() - * @see MSDN: Observable.Concat Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable concat(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7, Observable t8) { - return create(OperationConcat.concat(t1, t2, t3, t4, t5, t6, t7, t8)); - } - - /** - * Returns an Observable that emits the items emitted by nine Observables, - * one after the other. - *

- * - * - * @param t1 an Observable to be concatenated - * @param t2 an Observable to be concatenated - * @param t3 an Observable to be concatenated - * @param t4 an Observable to be concatenated - * @param t5 an Observable to be concatenated - * @param t6 an Observable to be concatenated - * @param t7 an Observable to be concatenated - * @param t8 an Observable to be concatenated - * @param t9 an Observable to be concatenated - * @return an Observable that emits items that are the result of combining - * the items emitted by the {@code source} Observables, one after - * the other - * @see concat() - * @see MSDN: Observable.Concat Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable concat(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7, Observable t8, Observable t9) { - return create(OperationConcat.concat(t1, t2, t3, t4, t5, t6, t7, t8, t9)); - } - - /** - * This behaves like {@link #merge(Observable)} except that if any of the - * merged Observables notify of an error via - * {@link Observer#onError onError}, {@code mergeDelayError} will refrain - * from propagating that error notification until all of the merged - * Observables have finished emitting items. - *

- * - *

- * Even if multiple merged Observables send {@code onError} notifications, - * {@code mergeDelayError} will only invoke the {@code onError} method of - * its Observers once. - *

- * This method allows an Observer to receive all successfully emitted items - * from all of the source Observables without being interrupted by an error - * notification from one of them. - * - * @param source an Observable that emits Observables - * @return an Observable that emits items that are the result of flattening - * the items emitted by the Observables emitted by the - * {@code source} Observable - * @see mergeDelayError() - * @see MSDN: Observable.Merge Method - */ - public static Observable mergeDelayError(Observable> source) { - return create(OperationMergeDelayError.mergeDelayError(source)); - } - - /** - * This behaves like {@link #merge(Observable, Observable)} except that if - * any of the merged Observables notify of an error via - * {@link Observer#onError onError}, {@code mergeDelayError} will refrain - * from propagating that error notification until all of the merged - * Observables have finished emitting items. - *

- * - *

- * Even if multiple merged Observables send {@code onError} notifications, - * {@code mergeDelayError} will only invoke the {@code onError} method of - * its Observers once. - *

- * This method allows an Observer to receive all successfully emitted items - * from all of the source Observables without being interrupted by an error - * notification from one of them. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see mergeDelayError() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable mergeDelayError(Observable t1, Observable t2) { - return create(OperationMergeDelayError.mergeDelayError(t1, t2)); - } - - /** - * This behaves like {@link #merge(Observable, Observable, Observable)} - * except that if any of the merged Observables notify of an error via - * {@link Observer#onError onError}, {@code mergeDelayError} will refrain - * from propagating that error notification until all of the merged - * Observables have finished emitting items. - *

- * - *

- * Even if multiple merged Observables send {@code onError} notifications, - * {@code mergeDelayError} will only invoke the {@code onError} method of - * its Observers once. - *

- * This method allows an Observer to receive all successfully emitted items - * from all of the source Observables without being interrupted by an error - * notification from one of them. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see mergeDelayError() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3) { - return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3)); - } - - /** - * This behaves like - * {@link #merge(Observable, Observable, Observable, Observable)} except - * that if any of the merged Observables notify of an error via - * {@link Observer#onError onError}, {@code mergeDelayError} will refrain - * from propagating that error notification until all of the merged - * Observables have finished emitting items. - *

- * - *

- * Even if multiple merged Observables send {@code onError} notifications, - * {@code mergeDelayError} will only invoke the {@code onError} method of - * its Observers once. - *

- * This method allows an Observer to receive all successfully emitted items - * from all of the source Observables without being interrupted by an error - * notification from one of them. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @param t4 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see mergeDelayError() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3, Observable t4) { - return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3, t4)); - } - - /** - * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable)} - * except that if any of the merged Observables notify of an error via - * {@link Observer#onError onError}, {@code mergeDelayError} will refrain - * from propagating that error notification until all of the merged - * Observables have finished emitting items. - *

- * - *

- * Even if multiple merged Observables send {@code onError} notifications, - * {@code mergeDelayError} will only invoke the {@code onError} method of - * its Observers once. - *

- * This method allows an Observer to receive all successfully emitted items - * from all of the source Observables without being interrupted by an error - * notification from one of them. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @param t4 an Observable to be merged - * @param t5 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see mergeDelayError() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5) { - return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3, t4, t5)); - } - - /** - * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable, Observable)} - * except that if any of the merged Observables notify of an error via - * {@link Observer#onError onError}, {@code mergeDelayError} will refrain - * from propagating that error notification until all of the merged - * Observables have finished emitting items. - *

- * - *

- * Even if multiple merged Observables send {@code onError} notifications, - * {@code mergeDelayError} will only invoke the {@code onError} method of - * its Observers once. - *

- * This method allows an Observer to receive all successfully emitted items - * from all of the source Observables without being interrupted by an error - * notification from one of them. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @param t4 an Observable to be merged - * @param t5 an Observable to be merged - * @param t6 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see mergeDelayError() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6) { - return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3, t4, t5, t6)); - } - - /** - * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable, Observable, Observable)} - * except that if any of the merged Observables notify of an error via - * {@link Observer#onError onError}, {@code mergeDelayError} will refrain - * from propagating that error notification until all of the merged - * Observables have finished emitting items. - *

- * - *

- * Even if multiple merged Observables send {@code onError} notifications, - * {@code mergeDelayError} will only invoke the {@code onError} method of - * its Observers once. - *

- * This method allows an Observer to receive all successfully emitted items - * from all of the source Observables without being interrupted by an error - * notification from one of them. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @param t4 an Observable to be merged - * @param t5 an Observable to be merged - * @param t6 an Observable to be merged - * @param t7 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see mergeDelayError() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7) { - return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3, t4, t5, t6, t7)); - } - - /** - * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable, Observable, Observable, Observable)} - * except that if any of the merged Observables notify of an error via - * {@link Observer#onError onError}, {@code mergeDelayError} will refrain - * from propagating that error notification until all of the merged - * Observables have finished emitting items. - *

- * - *

- * Even if multiple merged Observables send {@code onError} notifications, - * {@code mergeDelayError} will only invoke the {@code onError} method of - * its Observers once. - *

- * This method allows an Observer to receive all successfully emitted items - * from all of the source Observables without being interrupted by an error - * notification from one of them. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @param t4 an Observable to be merged - * @param t5 an Observable to be merged - * @param t6 an Observable to be merged - * @param t7 an Observable to be merged - * @param t8 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see mergeDelayError() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7, Observable t8) { - return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3, t4, t5, t6, t7, t8)); - } - - /** - * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable, Observable, Observable, Observable, Observable)} - * except that if any of the merged Observables notify of an error via - * {@link Observer#onError onError}, {@code mergeDelayError} will refrain - * from propagating that error notification until all of the merged - * Observables have finished emitting items. - *

- * - *

- * Even if multiple merged Observables send {@code onError} notifications, - * {@code mergeDelayError} will only invoke the {@code onError} method of - * its Observers once. - *

- * This method allows an Observer to receive all successfully emitted items - * from all of the source Observables without being interrupted by an error - * notification from one of them. - * - * @param t1 an Observable to be merged - * @param t2 an Observable to be merged - * @param t3 an Observable to be merged - * @param t4 an Observable to be merged - * @param t5 an Observable to be merged - * @param t6 an Observable to be merged - * @param t7 an Observable to be merged - * @param t8 an Observable to be merged - * @param t9 an Observable to be merged - * @return an Observable that emits items that are the result of flattening - * the items emitted by the {@code source} Observables - * @see mergeDelayError() - * @see MSDN: Observable.Merge Method - */ - @SuppressWarnings("unchecked") - // suppress because the types are checked by the method signature before using a vararg - public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7, Observable t8, Observable t9) { - return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3, t4, t5, t6, t7, t8, t9)); - } - - /** - * Returns an Observable that never sends any items or notifications to an - * {@link Observer}. - *

- * - *

- * This Observable is useful primarily for testing purposes. - * - * @param the type of items (not) emitted by the Observable - * @return an Observable that never sends any items or notifications to an - * {@link Observer} - * @see never() - */ - public static Observable never() { - return new NeverObservable(); - } - - /** - * Given an Observable that emits Observables, creates a single Observable - * that emits the items emitted by the most recently published of those - * Observables. - *

- * - * - * @param sequenceOfSequences the source Observable that emits Observables - * @return an Observable that emits only the items emitted by the most - * recently published Observable - * @see switchOnNext() - * @deprecated use {@link #switchOnNext} - */ - @Deprecated - public static Observable switchDo(Observable> sequenceOfSequences) { - return create(OperationSwitch.switchDo(sequenceOfSequences)); - } - - /** - * Given an Observable that emits Observables, creates a single Observable - * that emits the items emitted by the most recently published of those - * Observables. - *

- * - * - * @param sequenceOfSequences the source Observable that emits Observables - * @return an Observable that emits only the items emitted by the most - * recently published Observable - * @see switchOnNext() - */ - public static Observable switchOnNext(Observable> sequenceOfSequences) { - return create(OperationSwitch.switchDo(sequenceOfSequences)); - } - - /** - * Accepts an Observable and wraps it in another Observable that ensures - * that the resulting Observable is chronologically well-behaved. - *

- * - *

- * A well-behaved Observable does not interleave its invocations of the - * {@link Observer#onNext onNext}, {@link Observer#onCompleted onCompleted}, - * and {@link Observer#onError onError} methods of its {@link Observer}s; it - * invokes {@code onCompleted} or {@code onError} only once; and it never - * invokes {@code onNext} after invoking either {@code onCompleted} or - * {@code onError}. {@code synchronize} enforces this, and the Observable it - * returns invokes {@code onNext} and {@code onCompleted} or {@code onError} - * synchronously. - * - * @return an Observable that is a chronologically well-behaved version of - * the source Observable, and that synchronously notifies its - * {@link Observer}s - * @see synchronize() - */ - public Observable synchronize() { - return create(OperationSynchronize.synchronize(this)); - } - - /** - * Accepts an Observable and wraps it in another Observable that ensures - * that the resulting Observable is chronologically well-behaved. This is - * accomplished by acquiring a mutual-exclusion lock for the object - * provided as the lock parameter. - *

- * - *

- * A well-behaved Observable does not interleave its invocations of the - * {@link Observer#onNext onNext}, {@link Observer#onCompleted onCompleted}, - * and {@link Observer#onError onError} methods of its {@link Observer}s; it - * invokes {@code onCompleted} or {@code onError} only once; and it never - * invokes {@code onNext} after invoking either {@code onCompleted} or - * {@code onError}. {@code synchronize} enforces this, and the Observable it - * returns invokes {@code onNext} and {@code onCompleted} or {@code onError} - * synchronously. - * - * @param lock the lock object to synchronize each observer call on - * @return an Observable that is a chronologically well-behaved version of - * the source Observable, and that synchronously notifies its - * {@link Observer}s - * @see synchronize() - */ - public Observable synchronize(Object lock) { - return create(OperationSynchronize.synchronize(this, lock)); - } - - /** - * @deprecated use {@link #synchronize()} or {@link #synchronize(Object)} - */ - @Deprecated - public static Observable synchronize(Observable source) { - return create(OperationSynchronize.synchronize(source)); - } - - /** - * Emits an item each time interval (containing a sequential number). - *

- * - * - * @param interval interval size in time units (see below) - * @param unit time units to use for the interval size - * @return an Observable that emits an item each time interval - * @see interval() - * @see MSDN: Observable.Interval - */ - public static Observable interval(long interval, TimeUnit unit) { - return create(OperationInterval.interval(interval, unit)); - } - - /** - * Emits an item each time interval (containing a sequential number). - *

- * - * - * @param interval interval size in time units (see below) - * @param unit time units to use for the interval size - * @param scheduler the scheduler to use for scheduling the items - * @return an Observable that emits an item each time interval - * @see interval() - * @see MSDN: Observable.Interval - */ - public static Observable interval(long interval, TimeUnit unit, Scheduler scheduler) { - return create(OperationInterval.interval(interval, unit, scheduler)); - } - - /** - * Drops items emitted by an Observable that are followed by newer items - * before a timeout value expires. The timer resets on each emission. - *

- * Note: If events keep firing faster than the timeout then no data will be - * emitted. - *

- * - *

- * Information on debounce vs throttle: - *

- *

- * - * @param timeout the time each value has to be "the most recent" of the - * {@link Observable} to ensure that it's not dropped - * @param unit the {@link TimeUnit} for the timeout - * @return an {@link Observable} that filters out items that are too - * quickly followed by newer items - * @see debounce() - * @see #throttleWithTimeout(long, TimeUnit) - */ - public Observable debounce(long timeout, TimeUnit unit) { - return create(OperationDebounce.debounce(this, timeout, unit)); - } - - /** - * Drops items emitted by an Observable that are followed by newer items - * before a timeout value expires. The timer resets on each emission. - *

- * Note: If events keep firing faster than the timeout then no data will be - * emitted. - *

- * - *

- * Information on debounce vs throttle: - *

- *

- * - * @param timeout the time each value has to be "the most recent" of the - * {@link Observable} to ensure that it's not dropped - * @param unit the unit of time for the specified timeout - * @param scheduler the {@link Scheduler} to use internally to manage the - * timers that handle the timeout for each event - * @return an {@link Observable} that filters out items that are too - * quickly followed by newer items - * @see debounce() - * @see #throttleWithTimeout(long, TimeUnit, Scheduler) - */ - public Observable debounce(long timeout, TimeUnit unit, Scheduler scheduler) { - return create(OperationDebounce.debounce(this, timeout, unit, scheduler)); - } - - /** - * Drops items emitted by an Observable that are followed by newer items - * before a timeout value expires. The timer resets on each emission. - *

- * Note: If events keep firing faster than the timeout then no data will be - * emitted. - *

- * - *

- * Information on debounce vs throttle: - *

- *

- * - * @param timeout the time each value has to be "the most recent" of the - * {@link Observable} to ensure that it's not dropped - * @param unit the {@link TimeUnit} for the timeout - * @return an {@link Observable} that filters out items that are too - * quickly followed by newer items - * @see throttleWithTimeout() - * @see #debounce(long, TimeUnit) - */ - public Observable throttleWithTimeout(long timeout, TimeUnit unit) { - return create(OperationDebounce.debounce(this, timeout, unit)); - } - - /** - * Drops items emitted by an Observable that are followed by newer items - * before a timeout value expires. The timer resets on each emission. - *

- * Note: If events keep firing faster than the timeout then no data will be - * emitted. - *

- * - *

- * Information on debounce vs throttle: - *

- *

- * - * @param timeout the time each value has to be "the most recent" of the - * {@link Observable} to ensure that it's not dropped - * @param unit the {@link TimeUnit} for the timeout - * @param scheduler the {@link Scheduler} to use internally to manage the - * timers that handle the timeout for each event - * @return an {@link Observable} that filters out items that are too - * quickly followed by newer items - * @see throttleWithTimeout() - * @see #debounce(long, TimeUnit, Scheduler) - */ - public Observable throttleWithTimeout(long timeout, TimeUnit unit, Scheduler scheduler) { - return create(OperationDebounce.debounce(this, timeout, unit, scheduler)); - } - - /** - * Throttles by skipping items until "skipDuration" passes and then emits - * the next received item. - *

- * This differs from {@link #throttleLast} in that this only tracks passage - * of time whereas {@link #throttleLast} ticks at scheduled intervals. - *

- * - * - * @param windowDuration time to wait before sending another item after - * emitting the last item - * @param unit the unit of time for the specified timeout - * @return an Observable that performs the throttle operation - * @see throttleFirst() - */ - public Observable throttleFirst(long windowDuration, TimeUnit unit) { - return create(OperationThrottleFirst.throttleFirst(this, windowDuration, unit)); - } - - /** - * Throttles by skipping items until "skipDuration" passes and then emits - * the next received item. - *

- * This differs from {@link #throttleLast} in that this only tracks passage - * of time whereas {@link #throttleLast} ticks at scheduled intervals. - *

- * - * - * @param skipDuration time to wait before sending another item after - * emitting the last item - * @param unit the unit of time for the specified timeout - * @param scheduler the {@link Scheduler} to use internally to manage the - * timers that handle timeout for each event - * @return an Observable that performs the throttle operation - * @see throttleFirst() - */ - public Observable throttleFirst(long skipDuration, TimeUnit unit, Scheduler scheduler) { - return create(OperationThrottleFirst.throttleFirst(this, skipDuration, unit, scheduler)); - } - - /** - * Throttles by emitting the last item in each interval defined by - * intervalDuration. - *

- * This differs from {@link #throttleFirst} in that this ticks along at a - * scheduled interval whereas {@link #throttleFirst} does not tick, it just - * tracks passage of time. - *

- * - * - * @param intervalDuration duration of windows within which the last item - * will be emitted - * @param unit the unit of time for the specified interval - * @return an Observable that performs the throttle operation - * @see throttleLast() - * @see #sample(long, TimeUnit) - */ - public Observable throttleLast(long intervalDuration, TimeUnit unit) { - return sample(intervalDuration, unit); - } - - /** - * Throttles by emitting the last item in each interval defined by - * intervalDuration. - *

- * This differs from {@link #throttleFirst} in that this ticks along at a - * scheduled interval whereas {@link #throttleFirst} does not tick, it just - * tracks passage of time. - *

- * - * - * @param intervalDuration duration of windows within which the last item - * will be emitted - * @param unit the unit of time for the specified interval - * @return an Observable that performs the throttle operation - * @see throttleLast() - * @see #sample(long, TimeUnit, Scheduler) - */ - public Observable throttleLast(long intervalDuration, TimeUnit unit, Scheduler scheduler) { - return sample(intervalDuration, unit, scheduler); - } - - /** - * Wraps each item emitted by a source Observable in a {@link Timestamped} - * object. - *

- * - * - * @return an Observable that emits timestamped items from the source - * Observable - * @see timestamp() - */ - public Observable> timestamp() { - return create(OperationTimestamp.timestamp(this)); - } - - /** - * Converts a {@link Future} into an Observable. - *

- * - *

- * You can convert any object that supports the {@link Future} interface - * into an Observable that emits the return value of the {@link Future#get} - * method of that object, by passing the object into the {@code from} - * method. - *

- * Important note: This Observable is blocking; you cannot - * unsubscribe from it. - * - * @param future the source {@link Future} - * @param the type of object that the {@link Future} returns, and also - * the type of item to be emitted by the resulting Observable - * @return an Observable that emits the item from the source Future - * @see from() - */ - public static Observable from(Future future) { - return create(OperationToObservableFuture.toObservableFuture(future)); - } - - /** - * Converts a {@link Future} into an Observable. - *

- * - *

- * You can convert any object that supports the {@link Future} interface - * into an Observable that emits the return value of the {@link Future#get} - * method of that object, by passing the object into the {@code from} - * method. - *

- * - * @param future the source {@link Future} - * @param scheduler the {@link Scheduler} to wait for the Future on. Use a - * Scheduler such as {@link Schedulers#threadPoolForIO()} - * that can block and wait on the future. - * @param the type of object that the {@link Future} returns, and also - * the type of item to be emitted by the resulting Observable - * @return an Observable that emits the item from the source Future - * @see from() - */ - public static Observable from(Future future, Scheduler scheduler) { - return create(OperationToObservableFuture.toObservableFuture(future)).subscribeOn(scheduler); - } - - /** - * Converts a {@link Future} into an Observable with timeout. - *

- * - *

- * You can convert any object that supports the {@link Future} interface - * into an Observable that emits the return value of the {link Future#get} - * method of that object, by passing the object into the {@code from} - * method. - *

- * Important note: This Observable is blocking; you cannot - * unsubscribe from it. - * - * @param future the source {@link Future} - * @param timeout the maximum time to wait before calling get() - * @param unit the {@link TimeUnit} of the timeout argument - * @param the type of object that the {@link Future} returns, and also - * the type of item to be emitted by the resulting Observable - * @return an Observable that emits the item from the source {@link Future} - * @see from() - */ - public static Observable from(Future future, long timeout, TimeUnit unit) { - return create(OperationToObservableFuture.toObservableFuture(future, timeout, unit)); - } - - /** - * Returns an Observable that emits Boolean values that indicate whether the - * pairs of items emitted by two source Observables are equal. - *

- * - * - * @param first the first Observable to compare - * @param second the second Observable to compare - * @param the type of items emitted by each Observable - * @return an Observable that emits Booleans that indicate whether the - * corresponding items emitted by the source Observables are equal - * @see sequenceEqual() - */ - public static Observable sequenceEqual(Observable first, Observable second) { - return sequenceEqual(first, second, new Func2() { - @Override - public Boolean call(T first, T second) { - return first.equals(second); - } - }); - } - - /** - * Returns an Observable that emits Boolean values that indicate whether the - * pairs of items emitted by two source Observables are equal based on the - * results of a specified equality function. - *

- * - * - * @param first the first Observable to compare - * @param second the second Observable to compare - * @param equality a function used to compare items emitted by both - * Observables - * @param the type of items emitted by each Observable - * @return an Observable that emits Booleans that indicate whether the - * corresponding items emitted by the source Observables are equal - * @see sequenceEqual() - */ - public static Observable sequenceEqual(Observable first, Observable second, Func2 equality) { - return zip(first, second, equality); - } - - /** - * Returns an Observable that emits the results of a function of your - * choosing applied to combinations of two items emitted, in sequence, by - * two other Observables. - *

- * - *

- * {@code zip} applies this function in strict sequence, so the first item - * emitted by the new Observable will be the result of the function applied - * to the first item emitted by {@code o1} and the first item emitted by - * {@code o2}; the second item emitted by the new Observable will be the - * result of the function applied to the second item emitted by {@code o1} - * and the second item emitted by {@code o2}; and so forth. - *

- * The resulting {@code Observable} returned from {@code zip} will - * invoke {@link Observer#onNext onNext} as many times as the number of - * {@code onNext} invocations of the source Observable that emits the fewest - * items. - * - * @param o1 the first source Observable - * @param o2 another source Observable - * @param zipFunction a function that, when applied to an item emitted by - * each of the source Observables, results in an item that will - * be emitted by the resulting Observable - * @return an Observable that emits the zipped results - * @see zip() - */ - public static Observable zip(Observable o1, Observable o2, Func2 zipFunction) { - return create(OperationZip.zip(o1, o2, zipFunction)); - } - - /** - * Returns an Observable that emits the results of a function of your - * choosing applied to combinations of three items emitted, in sequence, by - * three other Observables. - *

- * - *

- * {@code zip} applies this function in strict sequence, so the first item - * emitted by the new Observable will be the result of the function applied - * to the first item emitted by {@code o1}, the first item emitted by - * {@code o2}, and the first item emitted by {@code o3}; the second item - * emitted by the new Observable will be the result of the function applied - * to the second item emitted by {@code o1}, the second item emitted by - * {@code o2}, and the second item emitted by {@code o3}; and so forth. - *

- * The resulting {@code Observable} returned from {@code zip} will - * invoke {@link Observer#onNext onNext} as many times as the number of - * {@code onNext} invocations of the source Observable that emits the fewest - * items. - * - * @param o1 the first source Observable - * @param o2 a second source Observable - * @param o3 a third source Observable - * @param zipFunction a function that, when applied to an item emitted by - * each of the source Observables, results in an item - * that will be emitted by the resulting Observable - * @return an Observable that emits the zipped results - * @see zip() - */ - public static Observable zip(Observable o1, Observable o2, Observable o3, Func3 zipFunction) { - return create(OperationZip.zip(o1, o2, o3, zipFunction)); - } - - /** - * Returns an Observable that emits the results of a function of your - * choosing applied to combinations of four items emitted, in sequence, by - * four other Observables. - *

- * - *

- * {@code zip} applies this function in strict sequence, so the first item - * emitted by the new Observable will be the result of the function applied - * to the first item emitted by {@code o1}, the first item emitted by - * {@code o2}, the first item emitted by {@code o3}, and the first item - * emitted by {@code 04}; the second item emitted by the new Observable will - * be the result of the function applied to the second item emitted by each - * of those Observables; and so forth. - *

- * The resulting {@code Observable} returned from {@code zip} will - * invoke {@link Observer#onNext onNext} as many times as the number of - * {@code onNext} invocations of the source Observable that emits the fewest - * items. - * - * @param o1 one source Observable - * @param o2 a second source Observable - * @param o3 a third source Observable - * @param o4 a fourth source Observable - * @param zipFunction a function that, when applied to an item emitted by - * each of the source Observables, results in an item that will - * be emitted by the resulting Observable - * @return an Observable that emits the zipped results - * @see zip() - */ - public static Observable zip(Observable o1, Observable o2, Observable o3, Observable o4, Func4 zipFunction) { - return create(OperationZip.zip(o1, o2, o3, o4, zipFunction)); - } - - /** - * Returns an Observable that emits the results of a function of your - * choosing applied to combinations of five items emitted, in sequence, by - * five other Observables. - *

- * - *

- * {@code zip} applies this function in strict sequence, so the first item - * emitted by the new Observable will be the result of the function applied - * to the first item emitted by {@code o1}, the first item emitted by - * {@code o2}, the first item emitted by {@code o3}, the first item emitted - * by {@code o4}, and the first item emitted by {@code o5}; the second item - * emitted by the new Observable will be the result of the function applied - * to the second item emitted by each of those Observables; and so forth. - *

- * The resulting {@code Observable} returned from {@code zip} will - * invoke {@link Observer#onNext onNext} as many times as the number of - * {@code onNext} invocations of the source Observable that emits the fewest - * items. - * - * @param o1 the first source Observable - * @param o2 a second source Observable - * @param o3 a third source Observable - * @param o4 a fourth source Observable - * @param o5 a fifth source Observable - * @param zipFunction a function that, when applied to an item emitted by - * each of the source Observables, results in an item - * that will be emitted by the resulting Observable - * @return an Observable that emits the zipped results - * @see zip() - */ - public static Observable zip(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Func5 zipFunction) { - return create(OperationZip.zip(o1, o2, o3, o4, o5, zipFunction)); - } - - /** - * Returns an Observable that emits the results of a function of your - * choosing applied to combinations of six items emitted, in sequence, by - * six other Observables. - *

- * - *

- * {@code zip} applies this function in strict sequence, so the first item - * emitted by the new Observable will be the result of the function applied - * to the first item emitted each source Observable, the second item emitted - * by the new Observable will be the result of the function applied to the - * second item emitted by each of those Observables, and so forth. - *

- * The resulting {@code Observable} returned from {@code zip} will - * invoke {@link Observer#onNext onNext} as many times as the number of - * {@code onNext} invocations of the source Observable that emits the fewest - * items. - * - * @param o1 the first source Observable - * @param o2 a second source Observable - * @param o3 a third source Observable - * @param o4 a fourth source Observable - * @param o5 a fifth source Observable - * @param o6 a sixth source Observable - * @param zipFunction a function that, when applied to an item emitted by - * each of the source Observables, results in an item - * that will be emitted by the resulting Observable - * @return an Observable that emits the zipped results - * @see zip() - */ - public static Observable zip(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, - Func6 zipFunction) { - return create(OperationZip.zip(o1, o2, o3, o4, o5, o6, zipFunction)); - } - - /** - * Returns an Observable that emits the results of a function of your - * choosing applied to combinations of seven items emitted, in sequence, by - * seven other Observables. - *

- * - *

- * {@code zip} applies this function in strict sequence, so the first item - * emitted by the new Observable will be the result of the function applied - * to the first item emitted each source Observable, the second item emitted - * by the new Observable will be the result of the function applied to the - * second item emitted by each of those Observables, and so forth. - *

- * The resulting {@code Observable} returned from {@code zip} will - * invoke {@link Observer#onNext onNext} as many times as the number of - * {@code onNext} invocations of the source Observable that emits the fewest - * items. - * - * @param o1 the first source Observable - * @param o2 a second source Observable - * @param o3 a third source Observable - * @param o4 a fourth source Observable - * @param o5 a fifth source Observable - * @param o6 a sixth source Observable - * @param o7 a seventh source Observable - * @param zipFunction a function that, when applied to an item emitted by - * each of the source Observables, results in an item - * that will be emitted by the resulting Observable - * @return an Observable that emits the zipped results - * @see zip() - */ - public static Observable zip(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, - Func7 zipFunction) { - return create(OperationZip.zip(o1, o2, o3, o4, o5, o6, o7, zipFunction)); - } - - /** - * Returns an Observable that emits the results of a function of your - * choosing applied to combinations of eight items emitted, in sequence, by - * eight other Observables. - *

- * - *

- * {@code zip} applies this function in strict sequence, so the first item - * emitted by the new Observable will be the result of the function applied - * to the first item emitted each source Observable, the second item emitted - * by the new Observable will be the result of the function applied to the - * second item emitted by each of those Observables, and so forth. - *

- * The resulting {@code Observable} returned from {@code zip} will - * invoke {@link Observer#onNext onNext} as many times as the number of - * {@code onNext} invocations of the source Observable that emits the fewest - * items. - * - * @param o1 the first source Observable - * @param o2 a second source Observable - * @param o3 a third source Observable - * @param o4 a fourth source Observable - * @param o5 a fifth source Observable - * @param o6 a sixth source Observable - * @param o7 a seventh source Observable - * @param o8 an eighth source Observable - * @param zipFunction a function that, when applied to an item emitted by - * each of the source Observables, results in an item - * that will be emitted by the resulting Observable - * @return an Observable that emits the zipped results - * @see zip() - */ - public static Observable zip(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, Observable o8, - Func8 zipFunction) { - return create(OperationZip.zip(o1, o2, o3, o4, o5, o6, o7, o8, zipFunction)); - } - - /** - * Returns an Observable that emits the results of a function of your - * choosing applied to combinations of nine items emitted, in sequence, by - * nine other Observables. - *

- * - *

- * {@code zip} applies this function in strict sequence, so the first item - * emitted by the new Observable will be the result of the function applied - * to the first item emitted each source Observable, the second item emitted - * by the new Observable will be the result of the function applied to the - * second item emitted by each of those Observables, and so forth. - *

- * The resulting {@code Observable} returned from {@code zip} will - * invoke {@link Observer#onNext onNext} as many times as the number of - * {@code onNext} invocations of the source Observable that emits the fewest - * items. - * - * @param o1 the first source Observable - * @param o2 a second source Observable - * @param o3 a third source Observable - * @param o4 a fourth source Observable - * @param o5 a fifth source Observable - * @param o6 a sixth source Observable - * @param o7 a seventh source Observable - * @param o8 an eighth source Observable - * @param o9 a ninth source Observable - * @param zipFunction a function that, when applied to an item emitted by - * each of the source Observables, results in an item - * that will be emitted by the resulting Observable - * @return an Observable that emits the zipped results - * @see zip() - */ - public static Observable zip(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, Observable o8, - Observable o9, Func9 zipFunction) { - return create(OperationZip.zip(o1, o2, o3, o4, o5, o6, o7, o8, o9, zipFunction)); - } - - /** - * Combines the given Observables, emitting an event containing an - * aggregation of the latest values of each of the source observables each - * time an event is received from one of the source observables, where the - * aggregation is defined by the given function. - *

- * - * - * @param o1 the first source Observable - * @param o2 the second source Observable - * @param combineFunction the aggregation function used to combine the - * source observable values - * @return an Observable that combines the source Observables with the - * given combine function - * @see combineLatest() - */ - public static Observable combineLatest(Observable o1, Observable o2, Func2 combineFunction) { - return create(OperationCombineLatest.combineLatest(o1, o2, combineFunction)); - } - - /** - * Combines the given Observables, emitting an event containing an - * aggregation of the latest values of each of the source observables each - * time an event is received from one of the source observables, where the - * aggregation is defined by the given function. - *

- * - * - * @param o1 the first source Observable - * @param o2 the second source Observable - * @param o3 the third source Observable - * @param combineFunction the aggregation function used to combine the - * source observable values - * @return an Observable that combines the source Observables with the - * given combine function - * @see combineLatest() - */ - public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Func3 combineFunction) { - return create(OperationCombineLatest.combineLatest(o1, o2, o3, combineFunction)); - } - - /** - * Combines the given Observables, emitting an event containing an - * aggregation of the latest values of each of the source observables each - * time an event is received from one of the source observables, where the - * aggregation is defined by the given function. - *

- * - * - * @param o1 the first source Observable - * @param o2 the second source Observable - * @param o3 the third source Observable - * @param o4 the fourth source Observable - * @param combineFunction the aggregation function used to combine the - * source observable values - * @return an Observable that combines the source Observables with the - * given combine function - * @see combineLatest() - */ - public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Observable o4, - Func4 combineFunction) { - return create(OperationCombineLatest.combineLatest(o1, o2, o3, o4, combineFunction)); - } - - /** - * Combines the given Observables, emitting an event containing an - * aggregation of the latest values of each of the source observables each - * time an event is received from one of the source observables, where the - * aggregation is defined by the given function. - *

- * - * - * @param o1 the first source Observable - * @param o2 the second source Observable - * @param o3 the third source Observable - * @param o4 the fourth source Observable - * @param o5 the fifth source Observable - * @param combineFunction the aggregation function used to combine the - * source observable values - * @return an Observable that combines the source Observables with the - * given combine function - * @see combineLatest() - */ - public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, - Func5 combineFunction) { - return create(OperationCombineLatest.combineLatest(o1, o2, o3, o4, o5, combineFunction)); - } - - /** - * Combines the given Observables, emitting an event containing an - * aggregation of the latest values of each of the source observables each - * time an event is received from one of the source observables, where the - * aggregation is defined by the given function. - *

- * - * - * @param o1 the first source Observable - * @param o2 the second source Observable - * @param o3 the third source Observable - * @param o4 the fourth source Observable - * @param o5 the fifth source Observable - * @param o6 the sixth source Observable - * @param combineFunction the aggregation function used to combine the - * source observable values - * @return an Observable that combines the source Observables with the - * given combine function - * @see combineLatest() - */ - public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, - Func6 combineFunction) { - return create(OperationCombineLatest.combineLatest(o1, o2, o3, o4, o5, o6, combineFunction)); - } - - /** - * Combines the given Observables, emitting an event containing an - * aggregation of the latest values of each of the source observables each - * time an event is received from one of the source observables, where the - * aggregation is defined by the given function. - *

- * - * - * @param o1 the first source Observable - * @param o2 the second source Observable - * @param o3 the third source Observable - * @param o4 the fourth source Observable - * @param o5 the fifth source Observable - * @param o6 the sixth source Observable - * @param o7 the seventh source Observable - * @param combineFunction the aggregation function used to combine the - * source observable values - * @return an Observable that combines the source Observables with the - * given combine function - * @see combineLatest() - */ - public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, - Func7 combineFunction) { - return create(OperationCombineLatest.combineLatest(o1, o2, o3, o4, o5, o6, o7, combineFunction)); - } - - /** - * Combines the given Observables, emitting an event containing an - * aggregation of the latest values of each of the source observables each - * time an event is received from one of the source observables, where the - * aggregation is defined by the given function. - *

- * - * - * @param o1 the first source Observable - * @param o2 the second source Observable - * @param o3 the third source Observable - * @param o4 the fourth source Observable - * @param o5 the fifth source Observable - * @param o6 the sixth source Observable - * @param o7 the seventh source Observable - * @param o8 the eighth source Observable - * @param combineFunction the aggregation function used to combine the - * source observable values - * @return an Observable that combines the source Observables with the - * given combine function - * @see combineLatest() - */ - public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, Observable o8, - Func8 combineFunction) { - return create(OperationCombineLatest.combineLatest(o1, o2, o3, o4, o5, o6, o7, o8, combineFunction)); - } - - /** - * Combines the given Observables, emitting an event containing an - * aggregation of the latest values of each of the source observables each - * time an event is received from one of the source observables, where the - * aggregation is defined by the given function. - *

- * - * - * @param o1 the first source Observable - * @param o2 the second source Observable - * @param o3 the third source Observable - * @param o4 the fourth source Observable - * @param o5 the fifth source Observable - * @param o6 the sixth source Observable - * @param o7 the seventh source Observable - * @param o8 the eighth source Observable - * @param o9 the ninth source Observable - * @param combineFunction the aggregation function used to combine the - * source observable values - * @return an Observable that combines the source Observables with the - * given combine function - * @see combineLatest() - */ - public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, Observable o8, Observable o9, - Func9 combineFunction) { - return create(OperationCombineLatest.combineLatest(o1, o2, o3, o4, o5, o6, o7, o8, o9, combineFunction)); - } - - /** - * Creates an Observable that produces buffers of collected items. - *

- * - *

- * This Observable produces connected, non-overlapping buffers. The current - * buffer is emitted and replaced with a new buffer when the Observable - * produced by the specified bufferClosingSelector produces a - * {@link rx.util.Closing} object. The bufferClosingSelector - * will then be used to create a new Observable to listen for the end of - * the next buffer. - * - * @param bufferClosingSelector the {@link Func0} which is used to produce - * an {@link Observable} for every buffer - * created. When this {@link Observable} - * produces a {@link rx.util.Closing} object, - * the associated buffer is emitted and - * replaced with a new one. - * @return an {@link Observable} which produces connected, non-overlapping - * buffers, which are emitted when the current {@link Observable} - * created with the {@link Func0} argument produces a - * {@link rx.util.Closing} object - * @see buffer() - */ - public Observable> buffer(Func0> bufferClosingSelector) { - return create(OperationBuffer.buffer(this, bufferClosingSelector)); - } - - /** - * Creates an Observable which produces buffers of collected values. - *

- * - *

- * This Observable produces buffers. Buffers are created when the specified - * bufferOpenings Observable produces a {@link rx.util.Opening} - * object. Additionally the bufferClosingSelector argument is - * used to create an Observable which produces {@link rx.util.Closing} - * objects. When this Observable produces such an object, the associated - * buffer is emitted. - * - * @param bufferOpenings the {@link Observable} that, when it produces a - * {@link rx.util.Opening} object, will cause another - * buffer to be created - * @param bufferClosingSelector the {@link Func1} that is used to produce - * an {@link Observable} for every buffer - * created. When this {@link Observable} - * produces a {@link rx.util.Closing} object, - * the associated buffer is emitted. - * @return an {@link Observable} that produces buffers that are created and - * emitted when the specified {@link Observable}s publish certain - * objects - * @see buffer() - */ - public Observable> buffer(Observable bufferOpenings, Func1> bufferClosingSelector) { - return create(OperationBuffer.buffer(this, bufferOpenings, bufferClosingSelector)); - } - - /** - * Creates an Observable that produces buffers of collected items. - *

- * - *

- * This Observable produces connected, non-overlapping buffers, each - * containing count items. When the source Observable completes - * or encounters an error, the current buffer is emitted, and the event is - * propagated. - * - * @param count the maximum size of each buffer before it should be emitted - * @return an {@link Observable} that produces connected, non-overlapping - * buffers containing at most "count" items - * @see buffer() - */ - public Observable> buffer(int count) { - return create(OperationBuffer.buffer(this, count)); - } - - /** - * Creates an Observable which produces buffers of collected items. - *

- * - *

- * This Observable produces buffers every skip items, each - * containing count items. When the source Observable - * completes or encounters an error, the current buffer is emitted, and the - * event is propagated. - * - * @param count the maximum size of each buffer before it should be emitted - * @param skip how many produced items need to be skipped before starting a - * new buffer. Note that when skip and - * count are equal, this is the same operation as - * {@link Observable#buffer(int)}. - * @return an {@link Observable} that produces buffers every - * skip item containing at most count - * items - * @see buffer() - */ - public Observable> buffer(int count, int skip) { - return create(OperationBuffer.buffer(this, count, skip)); - } - - /** - * Creates an Observable that produces buffers of collected values. - *

- * - *

- * This Observable produces connected, non-overlapping buffers, each of a - * fixed duration specified by the timespan argument. When the - * source Observable completes or encounters an error, the current buffer is - * emitted and the event is propagated. - * - * @param timespan the period of time each buffer collects values before it - * should be emitted and replaced with a new buffer - * @param unit the unit of time which applies to the timespan - * argument - * @return an {@link Observable} that produces connected, non-overlapping - * buffers with a fixed duration - * @see buffer() - */ - public Observable> buffer(long timespan, TimeUnit unit) { - return create(OperationBuffer.buffer(this, timespan, unit)); - } - - /** - * Creates an Observable that produces buffers of collected values. - *

- * - *

- * This Observable produces connected, non-overlapping buffers, each of a - * fixed duration specified by the timespan argument. When the - * source Observable completes or encounters an error, the current buffer is - * emitted and the event is propagated. - * - * @param timespan the period of time each buffer collects values before it - * should be emitted and replaced with a new buffer - * @param unit the unit of time which applies to the timespan - * argument - * @param scheduler the {@link Scheduler} to use when determining the end - * and start of a buffer - * @return an {@link Observable} that produces connected, non-overlapping - * buffers with a fixed duration - * @see buffer() - */ - public Observable> buffer(long timespan, TimeUnit unit, Scheduler scheduler) { - return create(OperationBuffer.buffer(this, timespan, unit, scheduler)); - } - - /** - * Creates an Observable that produces buffers of collected items. This - * Observable produces connected, non-overlapping buffers, each of a fixed - * duration specified by the timespan argument or a maximum - * size specified by the count argument (whichever is reached - * first). When the source Observable completes or encounters an error, the - * current buffer is emitted and the event is propagated. - *

- * - * - * @param timespan the period of time each buffer collects values before it - * should be emitted and replaced with a new buffer - * @param unit the unit of time which applies to the timespan - * argument - * @param count the maximum size of each buffer before it should be emitted - * @return an {@link Observable} that produces connected, non-overlapping - * buffers that are emitted after a fixed duration or when the - * buffer reaches maximum capacity (whichever occurs first) - * @see buffer() - */ - public Observable> buffer(long timespan, TimeUnit unit, int count) { - return create(OperationBuffer.buffer(this, timespan, unit, count)); - } - - /** - * Creates an Observable that produces buffers of collected items. This - * Observable produces connected, non-overlapping buffers, each of a fixed - * duration specified by the timespan argument or a maximum - * size specified by the count argument (whichever is reached - * first). When the source Observable completes or encounters an error, the - * current buffer is emitted and the event is propagated. - *

- * - * - * @param timespan the period of time each buffer collects values before it - * should be emitted and replaced with a new buffer - * @param unit the unit of time which applies to the timespan - * argument - * @param count the maximum size of each buffer before it should be emitted - * @param scheduler the {@link Scheduler} to use when determining the end - and start of a buffer - * @return an {@link Observable} that produces connected, non-overlapping - * buffers that are emitted after a fixed duration or when the - * buffer has reached maximum capacity (whichever occurs first) - * @see buffer() - */ - public Observable> buffer(long timespan, TimeUnit unit, int count, Scheduler scheduler) { - return create(OperationBuffer.buffer(this, timespan, unit, count, scheduler)); - } - - /** - * Creates an Observable that produces buffers of collected items. This - * Observable starts a new buffer periodically, as determined by the - * timeshift argument. Each buffer is emitted after a fixed - * timespan, specified by the timespan argument. When the - * source Observable completes or encounters an error, the current buffer is - * emitted and the event is propagated. - *

- * - * - * @param timespan the period of time each buffer collects values before it - * should be emitted - * @param timeshift the period of time after which a new buffer will be - * created - * @param unit the unit of time that applies to the timespan - * and timeshift arguments - * @return an {@link Observable} that produces new buffers periodically and - * emits these after a fixed timespan has elapsed. - * @see buffer() - */ - public Observable> buffer(long timespan, long timeshift, TimeUnit unit) { - return create(OperationBuffer.buffer(this, timespan, timeshift, unit)); - } - - /** - * Creates an Observable that produces buffers of collected items. This - * Observable starts a new buffer periodically, as determined by the - * timeshift argument. Each buffer is emitted after a fixed - * timespan, specified by the timespan argument. When the - * source Observable completes or encounters an error, the current buffer is - * emitted and the event is propagated. - *

- * - * - * @param timespan the period of time each buffer collects values before it - * should be emitted - * @param timeshift the period of time after which a new buffer will be - * created - * @param unit the unit of time that applies to the timespan - * and timeshift arguments - * @param scheduler the {@link Scheduler} to use when determining the end - * and start of a buffer - * @return an {@link Observable} that produces new buffers periodically and - * emits these after a fixed timespan has elapsed - * @see buffer() - */ - public Observable> buffer(long timespan, long timeshift, TimeUnit unit, Scheduler scheduler) { - return create(OperationBuffer.buffer(this, timespan, timeshift, unit, scheduler)); - } - - /** - * Creates an Observable that produces windows of collected items. This - * Observable produces connected, non-overlapping windows. The current - * window is emitted and replaced with a new window when the Observable - * produced by the specified closingSelector produces a - * {@link rx.util.Closing} object. The closingSelector will - * then be used to create a new Observable to listen for the end of the next - * window. - *

- * - * - * @param closingSelector the {@link Func0} used to produce an - * {@link Observable} for every window created. When this - * {@link Observable} emits a {@link rx.util.Closing} object, the - * associated window is emitted and replaced with a new one. - * @return an {@link Observable} that produces connected, non-overlapping - * windows, which are emitted when the current {@link Observable} - * created with the closingSelector argument emits a - * {@link rx.util.Closing} object. - * @see window() - */ - public Observable> window(Func0> closingSelector) { - return create(OperationWindow.window(this, closingSelector)); - } - - /** - * Creates an Observable that produces windows of collected items. This - * Observable produces windows. Chunks are created when the - * windowOpenings Observable produces a {@link rx.util.Opening} - * object. Additionally the closingSelector argument creates an - * Observable that produces {@link rx.util.Closing} objects. When this - * Observable produces such an object, the associated window is emitted. - *

- * - * - * @param windowOpenings the {@link Observable} that, when it produces a - * {@link rx.util.Opening} object, causes another - * window to be created - * @param closingSelector the {@link Func1} that produces an - * {@link Observable} for every window created. When - * this {@link Observable} produces a - * {@link rx.util.Closing} object, the associated - * window is emitted. - * @return an {@link Observable} that produces windows that are created and - * emitted when the specified {@link Observable}s publish certain - * objects - * @see window() - */ - public Observable> window(Observable windowOpenings, Func1> closingSelector) { - return create(OperationWindow.window(this, windowOpenings, closingSelector)); - } - - /** - * Creates an Observable that produces windows of collected items. This - * Observable produces connected, non-overlapping windows, each containing - * count elements. When the source Observable completes or - * encounters an error, the current window is emitted, and the event is - * propagated. - *

- * - * - * @param count the maximum size of each window before it should be emitted - * @return an {@link Observable} that produces connected, non-overlapping - * windows containing at most count items - * @see window() - */ - public Observable> window(int count) { - return create(OperationWindow.window(this, count)); - } - - /** - * Creates an Observable that produces windows of collected items. This - * Observable produces windows every skip items, each - * containing count elements. When the source Observable - * completes or encounters an error, the current window is emitted and the - * event is propagated. - *

- * - * - * @param count the maximum size of each window before it should be emitted - * @param skip how many items need to be skipped before starting a new - * window. Note that if skip and count - * are equal this is the same operation as {@link #window(int)}. - * @return an {@link Observable} that produces windows every "skipped" - * items containing at most count items - * @see window() - */ - public Observable> window(int count, int skip) { - return create(OperationWindow.window(this, count, skip)); - } - - /** - * Creates an Observable that produces windows of collected items. This - * Observable produces connected, non-overlapping windows, each of a fixed - * duration specified by the timespan argument. When the source - * Observable completes or encounters an error, the current window is - * emitted and the event is propagated. - *

- * - * - * @param timespan the period of time each window collects items before it - * should be emitted and replaced with a new window - * @param unit the unit of time that applies to the timespan - * argument - * @return an {@link Observable} that produces connected, non-overlapping - * windows with a fixed duration - * @see window() - */ - public Observable> window(long timespan, TimeUnit unit) { - return create(OperationWindow.window(this, timespan, unit)); - } - - /** - * Creates an Observable that produces windows of collected items. This - * Observable produces connected, non-overlapping windows, each of a fixed - * duration as specified by the timespan argument. When the - * source Observable completes or encounters an error, the current window is - * emitted and the event is propagated. - *

- * - * - * @param timespan the period of time each window collects items before it - * should be emitted and replaced with a new window - * @param unit the unit of time which applies to the timespan - * argument - * @param scheduler the {@link Scheduler} to use when determining the end - * and start of a window - * @return an {@link Observable} that produces connected, non-overlapping - * windows with a fixed duration - * @see window() - */ - public Observable> window(long timespan, TimeUnit unit, Scheduler scheduler) { - return create(OperationWindow.window(this, timespan, unit, scheduler)); - } - - /** - * Creates an Observable that produces windows of collected items. This - * Observable produces connected non-overlapping windows, each of a fixed - * duration as specified by the timespan argument or a maximum - * size as specified by the count argument (whichever is - * reached first). When the source Observable completes or encounters an - * error, the current window is emitted and the event is propagated. - *

- * - * - * @param timespan the period of time each window collects values before it - * should be emitted and replaced with a new window - * @param unit the unit of time that applies to the timespan - * argument - * @param count the maximum size of each window before it should be emitted - * @return an {@link Observable} that produces connected, non-overlapping - * windows that are emitted after a fixed duration or when the - * window has reached maximum capacity (whichever occurs first) - * @see window() - */ - public Observable> window(long timespan, TimeUnit unit, int count) { - return create(OperationWindow.window(this, timespan, unit, count)); - } - - /** - * Creates an Observable that produces windows of collected items. This - * Observable produces connected, non-overlapping windows, each of a fixed - * duration specified by the timespan argument or a maximum - * size specified by the count argument (whichever is reached - * first). When the source Observable completes or encounters an error, the - * current window is emitted and the event is propagated. - *

- * - * - * @param timespan the period of time each window collects values before it - * should be emitted and replaced with a new window - * @param unit the unit of time which applies to the timespan - * argument - * @param count the maximum size of each window before it should be emitted - * @param scheduler the {@link Scheduler} to use when determining the end - * and start of a window. - * @return an {@link Observable} that produces connected non-overlapping - * windows that are emitted after a fixed duration or when the - * window has reached maximum capacity (whichever occurs first). - * @see window() - */ - public Observable> window(long timespan, TimeUnit unit, int count, Scheduler scheduler) { - return create(OperationWindow.window(this, timespan, unit, count, scheduler)); - } - - /** - * Creates an Observable that produces windows of collected items. This - * Observable starts a new window periodically, as determined by the - * timeshift argument. Each window is emitted after a fixed - * timespan, specified by the timespan argument. When the - * source Observable completes or encounters an error, the current window is - * emitted and the event is propagated. - *

- * - * - * @param timespan the period of time each window collects values before it - * should be emitted - * @param timeshift the period of time after which a new window will be - * created - * @param unit the unit of time that applies to the timespan - * and timeshift arguments - * @return an {@link Observable} that produces new windows periodically and - * emits these after a fixed timespan has elapsed - * @see window() - */ - public Observable> window(long timespan, long timeshift, TimeUnit unit) { - return create(OperationWindow.window(this, timespan, timeshift, unit)); - } - - /** - * Creates an Observable that produces windows of collected items. This - * Observable starts a new window periodically, as determined by the - * timeshift argument. Each window is emitted after a fixed - * timespan, specified by the timespan argument. When the - * source Observable completes or encounters an error, the current window is - * emitted and the event is propagated. - *

- * - * - * @param timespan the period of time each window collects values before it - * should be emitted - * @param timeshift the period of time after which a new window will be - * created - * @param unit the unit of time that applies to the timespan - * and timeshift arguments - * @param scheduler the {@link Scheduler} to use when determining the end - * and start of a window - * @return an {@link Observable} that produces new windows periodically and - * emits these after a fixed timespan has elapsed - * @see window() - */ - public Observable> window(long timespan, long timeshift, TimeUnit unit, Scheduler scheduler) { - return create(OperationWindow.window(this, timespan, timeshift, unit, scheduler)); - } - - /** - * Returns an Observable that emits the results of a function of your - * choosing applied to combinations of n items emitted, in sequence, - * by n other Observables as provided by an Iterable. - *

- * {@code zip} applies this function in strict sequence, so the first item - * emitted by the new Observable will be the result of the function applied - * to the first item emitted by all of the source Observables; the second - * item emitted by the new Observable will be the result of the function - * applied to the second item emitted by each of those Observables; and so - * forth. - *

- * The resulting {@code Observable} returned from {@code zip} will - * invoke {@code onNext} as many times as the number of {@code onNext} - * invokations of the source Observable that emits the fewest items. - *

- * - * - * @param ws an Observable of source Observables - * @param zipFunction a function that, when applied to an item emitted by - * each of the source Observables, results in an item - * that will be emitted by the resulting Observable - * @return an Observable that emits the zipped results - * @see zip() - */ - public static Observable zip(Observable> ws, final FuncN zipFunction) { - return ws.toList().mapMany(new Func1>, Observable>() { - @Override - public Observable call(List> wsList) { - return create(OperationZip.zip(wsList, zipFunction)); - } - }); - } - - /** - * Returns an Observable that emits the results of a function of your - * choosing applied to combinations items emitted, in sequence, by a - * collection of other Observables. - *

- * {@code zip} applies this function in strict sequence, so the first item - * emitted by the new Observable will be the result of the function applied - * to the first item emitted by all of the source Observables; the second - * item emitted by the new Observable will be the result of the function - * applied to the second item emitted by each of those Observables; and so - * forth. - *

- * The resulting {@code Observable} returned from {@code zip} will invoke - * {@code onNext} as many times as the number of {@code onNext} invokations - * of the source Observable that emits the fewest items. - *

- * - * - * @param ws a collection of source Observables - * @param zipFunction a function that, when applied to an item emitted by - * each of the source Observables, results in an item - * that will be emitted by the resulting Observable - * @return an Observable that emits the zipped results - * @see zip() - */ - public static Observable zip(Iterable> ws, FuncN zipFunction) { - return create(OperationZip.zip(ws, zipFunction)); - } - - /** - * Filter items emitted by an Observable. - *

- * - * - * @param predicate a function that evaluates the items emitted by the - * source Observable, returning {@code true} if they pass - * the filter - * @return an Observable that emits only those items in the original - * Observable that the filter evaluates as {@code true} - * @see filter() - */ - public Observable filter(Func1 predicate) { - return create(OperationFilter.filter(this, predicate)); - } - - /** - * Returns an Observable that forwards all sequentially distinct items - * emitted from the source Observable. - *

- * - * - * @return an Observable of sequentially distinct items - * @see distinctUntilChanged() - * @see MSDN: Observable.distinctUntilChanged - */ - public Observable distinctUntilChanged() { - return create(OperationDistinctUntilChanged.distinctUntilChanged(this)); - } - - /** - * Returns an Observable that forwards all items emitted from the source - * Observable that are sequentially distinct according to a key selector - * function. - *

- * - * - * @param keySelector a function that projects an emitted item to a key - * value that is used for deciding whether an item is - * sequentially distinct from another one or not - * @return an Observable of sequentially distinct items - * @see distinctUntilChanged() - * @see MSDN: Observable.distinctUntilChanged - */ - public Observable distinctUntilChanged(Func1 keySelector) { - return create(OperationDistinctUntilChanged.distinctUntilChanged(this, keySelector)); - } - - /** - * Returns an Observable that emits all distinct items emitted from the - * source Observable. - *

- * - * - * @return an Observable of distinct items - * @see distinct() - * @see MSDN: Observable.distinct - */ - public Observable distinct() { - return create(OperationDistinct.distinct(this)); - } - - /** - * Returns an Observable that emits all items emitted from the source - * Observable that are distinct according to a key selector function. - *

- * - * - * @param keySelector a function that projects an emitted item to a key - * value that is used to decide whether an item is - * distinct from another one or not - * @return an Observable that emits distinct items - * @see distinct() - * @see MSDN: Observable.distinct - */ - public Observable distinct(Func1 keySelector) { - return create(OperationDistinct.distinct(this, keySelector)); - } - - /** - * Returns the item at a specified index in a sequence. - *

- * - * - * @param index the zero-based index of the item to retrieve - * @return an Observable that emits the item at the specified position in - * the source sequence - * @throws IndexOutOfBoundsException if index is greater than - * or equal to the number of elements in - * the source sequence - * @throws IndexOutOfBoundsException if index is less than 0 - * @see elementAt() - */ - public Observable elementAt(int index) { - return create(OperationElementAt.elementAt(this, index)); - } - - /** - * Returns the item at a specified index in a sequence or the default item - * if the index is out of range. - *

- * - * - * @param index the zero-based index of the item to retrieve - * @param defaultValue the default item - * @return an Observable that emits the item at the specified position in - * the source sequence, or the default item if the index is outside - * the bounds of the source sequence - * @throws IndexOutOfBoundsException if index is less than 0 - * @see elementAtOrDefault() - */ - public Observable elementAtOrDefault(int index, T defaultValue) { - return create(OperationElementAt.elementAtOrDefault(this, index, defaultValue)); - } - - /** - * Returns an {@link Observable} that emits true if any element - * of the source {@link Observable} satisfies the given condition, otherwise - * false. Note: always emits false if the source - * {@link Observable} is empty. - *

- * In Rx.Net this is the any operator but renamed in RxJava to - * better match Java naming idioms. - *

- * - * - * @param predicate the condition to test every element - * @return a subscription function for creating the target Observable - * @see exists() - * @see MSDN: Observable.Any Note: the description in this page is wrong. - */ - public Observable exists(Func1 predicate) { - return create(OperationAny.exists(this, predicate)); - } - - /** - * Determines whether an Observable sequence contains a specified item. - *

- * - * - * @param element the item to search in the sequence - * @return an Observable that emits true if the item is in the - * source sequence - * @see contains() - * @see MSDN: Observable.Contains - */ - public Observable contains(final T element) { - return exists(new Func1() { - public Boolean call(T t1) { - return element == null ? t1 == null : element.equals(t1); - } - }); - } - - /** - * Registers an {@link Action0} to be called when this Observable invokes - * {@link Observer#onCompleted onCompleted} or - * {@link Observer#onError onError}. - *

- * - * - * @param action an {@link Action0} to be invoked when the source - * Observable finishes - * @return an Observable that emits the same items as the source Observable, - * then invokes the {@link Action0} - * @see finallyDo() - * @see MSDN: Observable.Finally Method - */ - public Observable finallyDo(Action0 action) { - return create(OperationFinally.finallyDo(this, action)); - } - - /** - * Creates a new Observable by applying a function that you supply to each - * item emitted by the source Observable, where that function returns an - * Observable, and then merging those resulting Observables and emitting the - * results of this merger. - *

- * - *

- * Note: {@code mapMany} and {@code flatMap} are equivalent. - * - * @param func a function that, when applied to an item emitted by the - * source Observable, returns an Observable - * @return an Observable that emits the result of applying the - * transformation function to each item emitted by the source - * Observable and merging the results of the Observables obtained - * from this transformation. - * @see flatMap() - * @see #mapMany(Func1) - */ - public Observable flatMap(Func1> func) { - return mapMany(func); - } - - /** - * Filter items emitted by an Observable. - *

- * - * - * @param predicate a function that evaluates an item emitted by the source - * Observable, returning {@code true} if it passes the - * filter - * @return an Observable that emits only those items emitted by the original - * Observable that the filter evaluates as {@code true} - * @see where() - * @see #filter(Func1) - */ - public Observable where(Func1 predicate) { - return filter(predicate); - } - - /** - * Returns an Observable that applies the given function to each item - * emitted by an Observable and emits the result. - *

- * - * - * @param func a function to apply to each item emitted by the Observable - * @return an Observable that emits the items from the source Observable, - * transformed by the given function - * @see map() - * @see MSDN: Observable.Select - */ - public Observable map(Func1 func) { - return create(OperationMap.map(this, func)); - } - - /** - * Returns an Observable that applies the given function to each item - * emitted by an Observable and emits the result. - *

- * - * - * @param func a function to apply to each item emitted by the Observable. - * The function takes the index of the emitted item as - * additional parameter. - * @return an Observable that emits the items from the source Observable, - * transformed by the given function - * @see mapWithIndex() - * @see MSDN: Observable.Select - */ - public Observable mapWithIndex(Func2 func) { - return create(OperationMap.mapWithIndex(this, func)); - } - - /** - * Creates a new Observable by applying a function that you supply to each - * item emitted by the source Observable, where that function returns an - * Observable, and then merging those resulting Observables and emitting - * the results of this merger. - *

- * - *

- * Note: mapMany and flatMap are equivalent. - * - * @param func a function that, when applied to an item emitted by the - * source Observable, returns an Observable - * @return an Observable that emits the result of applying the - * transformation function to each item emitted by the source - * Observable and merging the results of the Observables obtained - * from this transformation. - * @see mapMany() - * @see #flatMap(Func1) - */ - public Observable mapMany(Func1> func) { - return create(OperationMap.mapMany(this, func)); - } - - /** - * Turns all of the notifications from a source Observable into - * {@link Observer#onNext onNext} emissions, and marks them with their - * original notification types within {@link Notification} objects. - *

- * - * - * @return an Observable whose items are the result of materializing the - * items and notifications of the source Observable - * @see materialize() - * @see MSDN: Observable.materialize - */ - public Observable> materialize() { - return create(OperationMaterialize.materialize(this)); - } - - /** - * Asynchronously subscribes and unsubscribes Observers on the specified - * {@link Scheduler}. - *

- * - * - * @param scheduler the {@link Scheduler} to perform subscription and - * unsubscription actions on - * @return the source Observable modified so that its subscriptions and - * unsubscriptions happen on the specified {@link Scheduler} - * @see subscribeOn() - */ - public Observable subscribeOn(Scheduler scheduler) { - return create(OperationSubscribeOn.subscribeOn(this, scheduler)); - } - - /** - * Asynchronously notify {@link Observer}s on the specified - * {@link Scheduler}. - *

- * - * - * @param scheduler the {@link Scheduler} to notify {@link Observer}s on - * @return the source Observable modified so that its {@link Observer}s are - * notified on the specified {@link Scheduler} - * @see observeOn() - */ - public Observable observeOn(Scheduler scheduler) { - return create(OperationObserveOn.observeOn(this, scheduler)); - } - - /** - * Returns an Observable that reverses the effect of - * {@link #materialize materialize} by transforming the {@link Notification} - * objects emitted by the source Observable into the items or notifications - * they represent. - *

- * - * - * @return an Observable that emits the items and notifications embedded in - * the {@link Notification} objects emitted by the source Observable - * @throws Throwable if the source Observable is not of type - * {@code Observable>} - * @see dematerialize() - * @see MSDN: Observable.dematerialize - */ - @SuppressWarnings("unchecked") - public Observable dematerialize() { - return create(OperationDematerialize.dematerialize((Observable>) this)); - } - - /** - * Instruct an Observable to pass control to another Observable rather than - * invoking {@link Observer#onError onError} if it encounters an error. - *

- * - *

- * By default, when an Observable encounters an error that prevents it from - * emitting the expected item to its {@link Observer}, the Observable - * invokes its Observer's onError method, and then quits - * without invoking any more of its Observer's methods. The - * onErrorResumeNext method changes this behavior. If you pass - * a function that returns an Observable (resumeFunction) to - * onErrorResumeNext, if the original Observable encounters an - * error, instead of invoking its Observer's onError method, it - * will instead relinquish control to the Observable returned from - * resumeFunction, which will invoke the Observer's - * {@link Observer#onNext onNext} method if it is able to do so. In such a - * case, because no Observable necessarily invokes onError, the - * Observer may never know that an error happened. - *

- * You can use this to prevent errors from propagating or to supply fallback - * data should errors be encountered. - * - * @param resumeFunction a function that returns an Observable that will - * take over if the source Observable encounters an - * error - * @return the original Observable, with appropriately modified behavior - * @see onErrorResumeNext() - */ - public Observable onErrorResumeNext(final Func1> resumeFunction) { - return create(OperationOnErrorResumeNextViaFunction.onErrorResumeNextViaFunction(this, resumeFunction)); - } - - /** - * Instruct an Observable to pass control to another Observable rather than - * invoking {@link Observer#onError onError} if it encounters an error. - *

- * - *

- * By default, when an Observable encounters an error that prevents it from - * emitting the expected item to its {@link Observer}, the Observable - * invokes its Observer's onError method, and then quits - * without invoking any more of its Observer's methods. The - * onErrorResumeNext method changes this behavior. If you pass - * another Observable (resumeSequence) to an Observable's - * onErrorResumeNext method, if the original Observable - * encounters an error, instead of invoking its Observer's - * onError method, it will instead relinquish control to - * resumeSequence which will invoke the Observer's - * {@link Observer#onNext onNext} method if it is able to do so. In such a - * case, because no Observable necessarily invokes onError, the - * Observer may never know that an error happened. - *

- * You can use this to prevent errors from propagating or to supply fallback - * data should errors be encountered. - * - * @param resumeSequence a function that returns an Observable that will - * take over if the source Observable encounters an - * error - * @return the original Observable, with appropriately modified behavior - * @see onErrorResumeNext() - */ - public Observable onErrorResumeNext(final Observable resumeSequence) { - return create(OperationOnErrorResumeNextViaObservable.onErrorResumeNextViaObservable(this, resumeSequence)); - } - - /** - * Instruct an Observable to pass control to another Observable rather than - * invoking {@link Observer#onError onError} if it encounters an error of - * type {@link java.lang.Exception}. - *

- * This differs from {@link #onErrorResumeNext} in that this one does not - * handle {@link java.lang.Throwable} or {@link java.lang.Error} but lets - * those continue through. - *

- * - *

- * By default, when an Observable encounters an error that prevents it from - * emitting the expected item to its {@link Observer}, the Observable - * invokes its Observer's onError method, and then quits - * without invoking any more of its Observer's methods. The - * onErrorResumeNext method changes this behavior. If you pass - * another Observable (resumeSequence) to an Observable's - * onErrorResumeNext method, if the original Observable - * encounters an error, instead of invoking its Observer's - * onError method, it will instead relinquish control to - * resumeSequence which will invoke the Observer's - * {@link Observer#onNext onNext} method if it is able to do so. In such a - * case, because no Observable necessarily invokes onError, - * the Observer may never know that an error happened. - *

- * You can use this to prevent errors from propagating or to supply fallback - * data should errors be encountered. - * - * @param resumeSequence a function that returns an Observable that will - * take over if the source Observable encounters an - * error - * @return the original Observable, with appropriately modified behavior - * @see onExceptionResumeNextViaObservable() - */ - public Observable onExceptionResumeNext(final Observable resumeSequence) { - return create(OperationOnExceptionResumeNextViaObservable.onExceptionResumeNextViaObservable(this, resumeSequence)); - } - - /** - * Instruct an Observable to emit an item (returned by a specified function) - * rather than invoking {@link Observer#onError onError} if it encounters an - * error. - *

- * - *

- * By default, when an Observable encounters an error that prevents it from - * emitting the expected item to its {@link Observer}, the Observable - * invokes its Observer's onError method, and then quits - * without invoking any more of its Observer's methods. The - * onErrorReturn method changes this behavior. If you pass a - * function (resumeFunction) to an Observable's - * onErrorReturn method, if the original Observable encounters - * an error, instead of invoking its Observer's onError method, - * it will instead pass the return value of resumeFunction to - * the Observer's {@link Observer#onNext onNext} method. - *

- * You can use this to prevent errors from propagating or to supply fallback - * data should errors be encountered. - * - * @param resumeFunction a function that returns an item that the new - * Observable will emit if the source Observable - * encounters an error - * @return the original Observable with appropriately modified behavior - * @see onErrorReturn() - */ - public Observable onErrorReturn(Func1 resumeFunction) { - return create(OperationOnErrorReturn.onErrorReturn(this, resumeFunction)); - } - - /** - * Returns an Observable that applies a function of your choosing to the - * first item emitted by a source Observable, then feeds the result of that - * function along with the second item emitted by the source Observable into - * the same function, and so on until all items have been emitted by the - * source Observable, and emits the final result from the final call to your - * function as its sole item. - *

- * - *

- * This technique, which is called "reduce" or "aggregate" here, is - * sometimes called "fold," "accumulate," "compress," or "inject" in other - * programming contexts. Groovy, for instance, has an inject - * method that does a similar operation on lists. - * - * @param accumulator an accumulator function to be invoked on each item - * emitted by the source Observable, whose result will - * be used in the next accumulator call - * @return an Observable that emits a single item that is the result of - * accumulating the output from the source Observable - * @throws IllegalArgumentException if the Observable sequence is empty - * @see reduce() - * @see MSDN: Observable.Aggregate - * @see Wikipedia: Fold (higher-order function) - */ - public Observable reduce(Func2 accumulator) { - /* - * Discussion and confirmation of implementation at https://github.com/Netflix/RxJava/issues/423#issuecomment-27642532 - * - * It should use last() not takeLast(1) since it needs to emit an error if the sequence is empty. - */ - return create(OperationScan.scan(this, accumulator)).last(); - } - - /** - * Returns an Observable that counts the total number of items in the - * source Observable. - *

- * - * - * @return an Observable that emits the number of counted elements of the - * source Observable as its single item - * @see count() - * @see MSDN: Observable.Count - */ - public Observable count() { - return reduce(0, new Func2() { - @Override - public Integer call(Integer t1, T t2) { - return t1 + 1; - } - }); - } - - /** - * Returns an Observable that sums up the integers emitted by the source - * Observable. - *

- * - * - * @param source source Observable to compute the sum of - * @return an Observable that emits the sum of all the items of the - * source Observable as its single item - * @see sum() - * @see MSDN: Observable.Sum - */ - public static Observable sum(Observable source) { - return OperationSum.sum(source); - } - - /** - * Returns an Observable that sums up the longs emitted by the source - * Observable. - *

- * - * - * @param source source Observable to compute the sum of - * @return an Observable that emits the sum of all the items of the - * source Observable as its single item - * @see sumLongs() - * @see MSDN: Observable.Sum - */ - public static Observable sumLongs(Observable source) { - return OperationSum.sumLongs(source); - } - - /** - * Returns an Observable that sums up the floats emitted by the source - * Observable. - *

- * - * - * @param source source Observable to compute the sum of - * @return an Observable that emits the sum of all the items of the - * source Observable as its single item - * @see sumFloats() - * @see MSDN: Observable.Sum - */ - public static Observable sumFloats(Observable source) { - return OperationSum.sumFloats(source); - } - - /** - * Returns an Observable that sums up the doubles emitted by the source - * Observable. - *

- * - * - * @param source source Observable to compute the sum of - * @return an Observable that emits the sum of all the items of the - * source Observable as its single item - * @see sumDoubles() - * @see MSDN: Observable.Sum - */ - public static Observable sumDoubles(Observable source) { - return OperationSum.sumDoubles(source); - } - - /** - * Returns an Observable that computes the average of the integers emitted - * by the source Observable. - *

- * - * - * @param source source observable to compute the average of - * @return an Observable that emits the average of all the items emitted by - * the source Observable as its single item - * @throws IllegalArgumentException if the Observable sequence is empty - * @see average() - * @see MSDN: Observable.Average - */ - public static Observable average(Observable source) { - return OperationAverage.average(source); - } - - /** - * Returns an Observable that computes the average of the longs emitted by - * the source Observable. - *

- * - * - * @param source source observable to compute the average of - * @return an Observable that emits the average of all the items emitted by - * the source Observable as its single item - * @see averageLongs() - * @see MSDN: Observable.Average - */ - public static Observable averageLongs(Observable source) { - return OperationAverage.averageLongs(source); - } - - /** - * Returns an Observable that computes the average of the floats emitted by - * the source Observable. - *

- * - * - * @param source source observable to compute the average of - * @return an Observable that emits the average of all the items emitted by - * the source Observable as its single item - * @see averageFloats() - * @see MSDN: Observable.Average - */ - public static Observable averageFloats(Observable source) { - return OperationAverage.averageFloats(source); - } - - /** - * Returns an Observable that computes the average of the doubles emitted - * by the source Observable. - *

- * - * - * @param source source observable to compute the average of - * @return an Observable that emits the average of all the items emitted by - * the source Observable as its single item - * @see averageDoubles() - * @see MSDN: Observable.Average - */ - public static Observable averageDoubles(Observable source) { - return OperationAverage.averageDoubles(source); - } - - /** - * Returns the minimum item emitted by an Observable. If there are more than - * one minimum items, its returns the last one. - *

- * - * - * @param source an Observable sequence to determine the minimum item of - * @return an Observable that emits the minimum item - * @throws IllegalArgumentException if the source is empty - * @see MSDN: Observable.Min - */ - public static > Observable min(Observable source) { - return OperationMinMax.min(source); - } - - /** - * Returns the minimum item emitted by an Observable according to a - * specified comparator. If there are more than one minimum items, it - * returns the last one. - *

- * - * - * @param comparator the comparer used to compare elements - * @return an Observable that emits the minimum value according to the - * specified comparator - * @throws IllegalArgumentException if the source is empty - * @see min() - * @see MSDN: Observable.Min - */ - public Observable min(Comparator comparator) { - return OperationMinMax.min(this, comparator); - } - - /** - * Returns the items emitted by an Observable sequence with the minimum key - * value. For an empty source, returns an Observable that emits an empty - * List. - *

- * - * - * @param selector the key selector function - * @return an Observable that emits a List of the items with the minimum key - * value - * @see minBy() - * @see MSDN: Observable.MinBy - */ - public > Observable> minBy(Func1 selector) { - return OperationMinMax.minBy(this, selector); - } - - /** - * Returns the elements emitted by an Observable with the minimum key value - * according to the specified comparator. For an empty source, it returns an - * Observable that emits an empty List. - *

- * - * - * @param selector the key selector function - * @param comparator the comparator used to compare key values - * @return an Observable that emits a List of the elements with the minimum - * key value according to the specified comparator - * @see minBy() - * @see MSDN: Observable.MinBy - */ - public Observable> minBy(Func1 selector, Comparator comparator) { - return OperationMinMax.minBy(this, selector, comparator); - } - - /** - * Returns the maximum item emitted by an Observable. If there is more - * than one maximum item, it returns the last one. - *

- * - * - * @param source an Observable to determine the maximum item of - * @return an Observable that emits the maximum element - * @throws IllegalArgumentException if the source is empty - * @see max() - * @see MSDN: Observable.Max - */ - public static > Observable max(Observable source) { - return OperationMinMax.max(source); - } - - /** - * Returns the maximum item emitted by an Observable according to the - * specified comparator. If there is more than one maximum item, it returns - * the last one. - *

- * - * - * @param comparator the comparer used to compare items - * @return an Observable that emits the maximum item according to the - * specified comparator - * @throws IllegalArgumentException if the source is empty - * @see max() - * @see MSDN: Observable.Max - */ - public Observable max(Comparator comparator) { - return OperationMinMax.max(this, comparator); - } - - /** - * Returns the items emitted by an Observable with the maximum key value. - * For an empty source, it returns an Observable that emits an empty List. - *

- * - * - * @param selector the key selector function - * @return an Observable that emits a List of the items with the maximum key - * value - * @see maxBy() - * @see MSDN: Observable.MaxBy - */ - public > Observable> maxBy(Func1 selector) { - return OperationMinMax.maxBy(this, selector); - } - - /** - * Returns the items emitted by an Observable with the maximum key value - * according to the specified comparator. For an empty source, it returns an - * Observable that emits an empty List. - *

- * - * - * @param selector the key selector function - * @param comparator the comparator used to compare key values - * @return an Observable that emits a List of the elements with the maximum - * key value according to the specified comparator - * @see maxBy() - * @see MSDN: Observable.MaxBy - */ - public Observable> maxBy(Func1 selector, Comparator comparator) { - return OperationMinMax.maxBy(this, selector, comparator); - } - - /** - * Returns a {@link ConnectableObservable} that shares a single subscription - * to the underlying Observable that will replay all of its items and - * notifications to any future {@link Observer}. - *

- * - * - * @return a {@link ConnectableObservable} that upon connection causes the - * source Observable to emit items to its {@link Observer}s - * @see replay() - */ - public ConnectableObservable replay() { - return OperationMulticast.multicast(this, ReplaySubject. create()); - } - - /** - * Retry subscription to origin Observable upto given retry count. - *

- * - *

- * If {@link Observer#onError} is invoked the source Observable will be - * re-subscribed to as many times as defined by retryCount. - *

- * Any {@link Observer#onNext} calls received on each attempt will be - * emitted and concatenated together. - *

- * For example, if an Observable fails on first time but emits [1, 2] then - * succeeds the second time and emits [1, 2, 3, 4, 5] then the complete - * output would be [1, 2, 1, 2, 3, 4, 5, onCompleted]. - * - * @param retryCount number of retry attempts before failing - * @return an Observable with retry logic - * @see retry() - */ - public Observable retry(int retryCount) { - return create(OperationRetry.retry(this, retryCount)); - } - - /** - * Retry subscription to origin Observable whenever onError is - * called (infinite retry count). - *

- * - *

- * If {@link Observer#onError} is invoked the source Observable will be - * re-subscribed to. - *

- * Any {@link Observer#onNext} calls received on each attempt will be - * emitted and concatenated together. - *

- * For example, if an Observable fails on first time but emits [1, 2] then - * succeeds the second time and emits [1, 2, 3, 4, 5] then the complete - * output would be [1, 2, 1, 2, 3, 4, 5, onCompleted]. - * - * @return an Observable with retry logic - * @see retry() - */ - public Observable retry() { - return create(OperationRetry.retry(this)); - } - - /** - * This method has similar behavior to {@link #replay} except that this - * auto-subscribes to the source Observable rather than returning a - * {@link ConnectableObservable}. - *

- * - *

- * This is useful when you want an Observable to cache responses and you - * can't control the subscribe/unsubscribe behavior of all the - * {@link Observer}s. - *

- * Note: You sacrifice the ability to unsubscribe from the origin when you - * use the cache() operator so be careful not to use this - * operator on Observables that emit an infinite or very large number of - * items that will use up memory. - * - * @return an Observable that, when first subscribed to, caches all of its - * notifications for the benefit of subsequent subscribers. - * @see cache() - */ - public Observable cache() { - return create(OperationCache.cache(this)); - } - - /** - * Perform work in parallel by sharding an {@code Observable} on a - * {@link Schedulers#threadPoolForComputation()} {@link Scheduler} and - * return an {@code Observable} with the output. - *

- * - * - * @param f a {@link Func1} that applies Observable operators to - * {@code Observable} in parallel and returns an - * {@code Observable} - * @return an Observable with the output of the {@link Func1} executed on a - * {@link Scheduler} - * @see parallel() - */ - public Observable parallel(Func1, Observable> f) { - return OperationParallel.parallel(this, f); - } - - /** - * Perform work in parallel by sharding an {@code Observable} on a - * {@link Scheduler} and return an {@code Observable} with the output. - *

- * - * - * @param f a {@link Func1} that applies Observable operators to - * {@code Observable} in parallel and returns an - * {@code Observable} - * @param s a {@link Scheduler} to perform the work on - * @return an Observable with the output of the {@link Func1} executed on a - * {@link Scheduler} - * @see parallel() - */ - - public Observable parallel(final Func1, Observable> f, final Scheduler s) { - return OperationParallel.parallel(this, f, s); - } - - - /** - * Merges an Observable<Observable<T>> to - * Observable<Observable<T>> with the number of - * inner Observables defined by parallelObservables. - *

- * For example, if the original - * Observable<Observable<T>> has 100 Observables to - * be emitted and parallelObservables is 8, the 100 will be - * grouped onto 8 output Observables. - *

- * This is a mechanism for efficiently processing n number of - * Observables on a smaller m number of resources (typically CPU - * cores). - *

- * - * - * @param parallelObservables the number of Observables to merge into - * @return an Observable of Observables constrained to number defined by - * parallelObservables - * @see parallelMerge() - */ - public static Observable> parallelMerge(Observable> source, int parallelObservables) { - return OperationParallelMerge.parallelMerge(source, parallelObservables); - } - - /** - * Merges an Observable<Observable<T>> to - * Observable<Observable<T>> with the number of - * inner Observables defined by parallelObservables and runs - * each Observable on the defined Scheduler. - *

- * For example, if the original - * Observable<Observable<T>> has 100 Observables to - * be emitted and parallelObservables is 8, the 100 will be - * grouped onto 8 output Observables. - *

- * This is a mechanism for efficiently processing n number of - * Observables on a smaller m number of resources (typically CPU - * cores). - *

- * - * - * @param parallelObservables the number of Observables to merge into - * @return an Observable of Observables constrained to number defined by - * parallelObservables. - * @see parallelMerge() - */ - public static Observable> parallelMerge(Observable> source, int parallelObservables, Scheduler scheduler) { - return OperationParallelMerge.parallelMerge(source, parallelObservables, scheduler); - } - - /** - * Returns a {@link ConnectableObservable}, which waits until its - * {@link ConnectableObservable#connect connect} method is called before it - * begins emitting items to those {@link Observer}s that have subscribed to - * it. - *

- * - * - * @return a {@link ConnectableObservable} that upon connection causes the - * source Observable to emit items to its {@link Observer}s - * @see publish() - */ - public ConnectableObservable publish() { - return OperationMulticast.multicast(this, PublishSubject. create()); - } - - /** - * Returns a {@link ConnectableObservable} that shares a single subscription - * that contains the last notification only. - *

- * - * - * @return a {@link ConnectableObservable} - * @see publishLast() - */ - public ConnectableObservable publishLast() { - return OperationMulticast.multicast(this, AsyncSubject. create()); - } - - /** - * Synonymous with reduce(). - *

- * - * - * @see aggregate() - * @see #reduce(Func2) - */ - public Observable aggregate(Func2 accumulator) { - return reduce(accumulator); - } - - /** - * Returns an Observable that applies a function of your choosing to the - * first item emitted by a source Observable, then feeds the result of that - * function along with the second item emitted by an Observable into the - * same function, and so on until all items have been emitted by the source - * Observable, emitting the final result from the final call to your - * function as its sole item. - *

- * - *

- * This technique, which is called "reduce" or "aggregate" here, is - * sometimes called "fold," "accumulate," "compress," or "inject" in other - * programming contexts. Groovy, for instance, has an inject - * method that does a similar operation on lists. - * - * @param initialValue the initial (seed) accumulator value - * @param accumulator an accumulator function to be invoked on each item - * emitted by the source Observable, the result of which - * will be used in the next accumulator call - * @return an Observable that emits a single item that is the result of - * accumulating the output from the items emitted by the source - * Observable - * @see reduce() - * @see MSDN: Observable.Aggregate - * @see Wikipedia: Fold (higher-order function) - */ - public Observable reduce(R initialValue, Func2 accumulator) { - return create(OperationScan.scan(this, initialValue, accumulator)).takeLast(1); - } - - /** - * Synonymous with reduce(). - *

- * - * - * @see aggregate() - * @see #reduce(Object, Func2) - */ - public Observable aggregate(R initialValue, Func2 accumulator) { - return reduce(initialValue, accumulator); - } - - /** - * Returns an Observable that applies a function of your choosing to the - * first item emitted by a source Observable, then feeds the result of that - * function along with the second item emitted by an Observable into the - * same function, and so on until all items have been emitted by the source - * Observable, emitting the result of each of these iterations. - *

- * - *

- * This sort of function is sometimes called an accumulator. - *

- * Note that when you pass a seed to scan() the resulting - * Observable will emit that seed as its first emitted item. - * - * @param accumulator an accumulator function to be invoked on each item - * emitted by the source Observable, whose result will be - * emitted to {@link Observer}s via - * {@link Observer#onNext onNext} and used in the next - * accumulator call - * @return an Observable that emits the results of each call to the - * accumulator function - * @see scan() - * @see MSDN: Observable.Scan - */ - public Observable scan(Func2 accumulator) { - return create(OperationScan.scan(this, accumulator)); - } - - /** - * Returns an Observable that emits the results of sampling the items - * emitted by the source Observable at a specified time interval. - *

- * - * - * @param period the sampling rate - * @param unit the {@link TimeUnit} in which period is defined - * @return an Observable that emits the results of sampling the items - * emitted by the source Observable at the specified time interval - * @see sample() - */ - public Observable sample(long period, TimeUnit unit) { - return create(OperationSample.sample(this, period, unit)); - } - - /** - * Returns an Observable that emits the results of sampling the items - * emitted by the source Observable at a specified time interval. - *

- * - * - * @param period the sampling rate - * @param unit the {@link TimeUnit} in which period is defined - * @param scheduler the {@link Scheduler} to use when sampling - * @return an Observable that emits the results of sampling the items - * emitted by the source Observable at the specified time interval - * @see sample() - */ - public Observable sample(long period, TimeUnit unit, Scheduler scheduler) { - return create(OperationSample.sample(this, period, unit, scheduler)); - } - - /** - * Returns an Observable that applies a function of your choosing to the - * first item emitted by a source Observable, then feeds the result of that - * function along with the second item emitted by an Observable into the - * same function, and so on until all items have been emitted by the source - * Observable, emitting the result of each of these iterations. - *

- * - *

- * This sort of function is sometimes called an accumulator. - *

- * Note that when you pass a seed to scan() the resulting - * Observable will emit that seed as its first emitted item. - * - * @param initialValue the initial (seed) accumulator value - * @param accumulator an accumulator function to be invoked on each item - * emitted by the source Observable, whose result will be - * emitted to {@link Observer}s via - * {@link Observer#onNext onNext} and used in the next - * accumulator call - * @return an Observable that emits the results of each call to the - * accumulator function - * @see scan() - * @see MSDN: Observable.Scan - */ - public Observable scan(R initialValue, Func2 accumulator) { - return create(OperationScan.scan(this, initialValue, accumulator)); - } - - /** - * Returns an Observable that emits a Boolean that indicates whether all of - * the items emitted by the source Observable satisfy a condition. - *

- * - * - * @param predicate a function that evaluates an item and returns a Boolean - * @return an Observable that emits true if all items emitted - * by the source Observable satisfy the predicate; otherwise, - * false - * @see all() - */ - public Observable all(Func1 predicate) { - return create(OperationAll.all(this, predicate)); - } - - /** - * Returns an Observable that skips the first num items emitted - * by the source Observable and emits the remainder. - *

- * - *

- * You can ignore the first num items emitted by an Observable - * and attend only to those items that come after, by modifying the - * Observable with the skip method. - * - * @param num the number of items to skip - * @return an Observable that is identical to the source Observable except - * that it does not emit the first num items that the - * source emits - * @see skip() - */ - public Observable skip(int num) { - return create(OperationSkip.skip(this, num)); - } - - /** - * Returns an Observable that emits only the very first item emitted by the - * source Observable. - *

- * - * - * @return an Observable that emits only the very first item from the - * source, or none if the source Observable completes without - * emitting a single item - * @see first() - * @see MSDN: Observable.First - */ - public Observable first() { - return take(1); - } - - /** - * Returns an Observable that emits only the very first item emitted by the - * source Observable that satisfies a given condition. - *

- * - * - * @param predicate the condition any source emitted item has to satisfy - * @return an Observable that emits only the very first item satisfying the - * given condition from the source, or none if the source Observable - * completes without emitting a single matching item - * @see first() - * @see MSDN: Observable.First - */ - public Observable first(Func1 predicate) { - return skipWhile(not(predicate)).take(1); - } - - /** - * Returns an Observable that emits only the very first item emitted by the - * source Observable, or a default value. - *

- * - * - * @param defaultValue the default value to emit if the source Observable - * doesn't emit anything - * @return an Observable that emits only the very first item from the - * source, or a default value if the source Observable completes - * without emitting a single item - * @see firstOrDefault() - * @see MSDN: Observable.FirstOrDefault - */ - public Observable firstOrDefault(T defaultValue) { - return create(OperationFirstOrDefault.firstOrDefault(this, defaultValue)); - } - - /** - * Returns an Observable that emits only the very first item emitted by the - * source Observable that satisfies a given condition, or a default value - * otherwise. - *

- * - * - * @param predicate the condition any source emitted item has to satisfy - * @param defaultValue the default value to emit if the source Observable - * doesn't emit anything that satisfies the given condition - * @return an Observable that emits only the very first item from the source - * that satisfies the given condition, or a default value otherwise - * @see firstOrDefault() - * @see MSDN: Observable.FirstOrDefault - */ - public Observable firstOrDefault(Func1 predicate, T defaultValue) { - return create(OperationFirstOrDefault.firstOrDefault(this, predicate, defaultValue)); - } - - /** - * Returns the elements of the specified sequence or the specified default - * value in a singleton sequence if the sequence is empty. - *

- * - * - * @param defaultValue the value to return if the sequence is empty - * @return an Observable that emits the specified default value if the - * source is empty; otherwise, the items emitted by the source - * @see defaultIfEmpty() - * @see MSDN: Observable.DefaultIfEmpty - */ - public Observable defaultIfEmpty(T defaultValue) { - return create(OperationDefaultIfEmpty.defaultIfEmpty(this, defaultValue)); - } - - /** - * Returns an Observable that emits only the first num items - * emitted by the source Observable. - *

- * - *

- * This method returns an Observable that will invoke a subscribing - * {@link Observer}'s {@link Observer#onNext onNext} function a maximum of - * num times before invoking - * {@link Observer#onCompleted onCompleted}. - * - * @param num the number of items to emit - * @return an Observable that emits only the first num items - * from the source Observable, or all of the items from the source - * Observable if that Observable emits fewer than num - * items - * @see take() - */ - public Observable take(final int num) { - return create(OperationTake.take(this, num)); - } - - /** - * Returns an Observable that emits items emitted by the source Observable - * so long as a specified condition is true. - *

- * - * - * @param predicate a function that evaluates an item emitted by the source - * Observable and returns a Boolean - * @return an Observable that emits the items from the source Observable so - * long as each item satisfies the condition defined by - * predicate - * @see takeWhile() - */ - public Observable takeWhile(final Func1 predicate) { - return create(OperationTakeWhile.takeWhile(this, predicate)); - } - - /** - * Returns an Observable that emits the items emitted by a source Observable - * so long as a given predicate remains true, where the predicate can - * operate on both the item and its index relative to the complete sequence. - *

- * - * - * @param predicate a function to test each item emitted by the source - * Observable for a condition; the second parameter of the - * function represents the index of the source item - * @return an Observable that emits items from the source Observable so long - * as the predicate continues to return true for each - * item, then completes - * @see takeWhileWithIndex() - */ - public Observable takeWhileWithIndex(final Func2 predicate) { - return create(OperationTakeWhile.takeWhileWithIndex(this, predicate)); - } - - /** - * Returns an Observable that emits only the very first item emitted by the - * source Observable. - *

- * - * - * @return an Observable that emits only the very first item from the - * source, or none if the source Observable completes without - * emitting a single item - * @see first() - * @see MSDN: Observable.First - * @see #first() - */ - public Observable takeFirst() { - return first(); - } - - /** - * Returns an Observable that emits only the very first item emitted by the - * source Observable that satisfies a given condition. - *

- * - * - * @param predicate the condition any source emitted item has to satisfy - * @return an Observable that emits only the very first item satisfying the - * given condition from the source, or none if the source Observable - * completes without emitting a single matching item - * @see first() - * @see MSDN: Observable.First - * @see #first(Func1) - */ - public Observable takeFirst(Func1 predicate) { - return first(predicate); - } - - /** - * Returns an Observable that emits only the last count items - * emitted by the source Observable. - *

- * - * - * @param count the number of items to emit from the end of the sequence - * emitted by the source Observable - * @return an Observable that emits only the last count items - * emitted by the source Observable - * @see takeLast() - */ - public Observable takeLast(final int count) { - return create(OperationTakeLast.takeLast(this, count)); - } - - /** - * Returns an Observable that emits the items from the source Observable - * only until the other Observable emits an item. - *

- * - * - * @param other the Observable whose first emitted item will cause - * takeUntil to stop emitting items from the - * source Observable - * @param the type of items emitted by other - * @return an Observable that emits the items of the source Observable until - * such time as other emits its first item - * @see takeUntil() - */ - public Observable takeUntil(Observable other) { - return OperationTakeUntil.takeUntil(this, other); - } - - /** - * Returns an Observable that bypasses all items from the source Observable - * as long as the specified condition holds true, but emits all further - * source items as soon as the condition becomes false. - *

- * - * - * @param predicate a function to test each item emitted from the source - * Observable for a condition. It receives the emitted item - * as the first parameter and the index of the emitted item - * as a second parameter. - * @return an Observable that emits all items from the source Observable as - * soon as the condition becomes false - * @see skipWhileWithIndex() - * @see MSDN: Observable.SkipWhile - */ - public Observable skipWhileWithIndex(Func2 predicate) { - return create(OperationSkipWhile.skipWhileWithIndex(this, predicate)); - } - - /** - * Returns an Observable that bypasses all items from the source Observable - * as long as the specified condition holds true, but emits all further - * source items as soon as the condition becomes false. - *

- * - * - * @param predicate a function to test each item emitted from the source - * Observable for a condition - * @return an Observable that emits all items from the source Observable as - * soon as the condition becomes false - * @see skipWhile() - * @see MSDN: Observable.SkipWhile - */ - public Observable skipWhile(Func1 predicate) { - return create(OperationSkipWhile.skipWhile(this, predicate)); - } - - /** - * Bypasses a specified number of items at the end of an Observable - * sequence. - *

- * This operator accumulates a queue with a length enough to store the first - * count items. As more items are received, items are taken - * from the front of the queue and produced on the result sequence. This - * causes elements to be delayed. - *

- * - * - * @param count number of elements to bypass at the end of the source - * sequence - * @return an Observable sequence emitting the source sequence items - * except for the bypassed ones at the end - * @throws IndexOutOfBoundsException if count is less than zero - * @see skipLast() - * @see MSDN: Observable.SkipLast - */ - public Observable skipLast(int count) { - return create(OperationSkipLast.skipLast(this, count)); - } - - /** - * Returns an Observable that emits a single item, a list composed of all - * the items emitted by the source Observable. - *

- * - *

- * Normally, an Observable that returns multiple items will do so by - * invoking its {@link Observer}'s {@link Observer#onNext onNext} method for - * each such item. You can change this behavior, instructing the Observable - * to compose a list of all of these items and then to invoke the Observer's - * onNext function once, passing it the entire list, by calling - * the Observable's toList method prior to calling its - * {@link #subscribe} method. - *

- * Be careful not to use this operator on Observables that emit infinite or - * very large numbers of items, as you do not have the option to - * unsubscribe. - * - * @return an Observable that emits a single item: a List containing all of - * the items emitted by the source Observable. - * @see toList() - */ - public Observable> toList() { - return create(OperationToObservableList.toObservableList(this)); - } - - /** - * Return an Observable that emits the items emitted by the source - * Observable, in a sorted order (each item emitted by the Observable must - * implement {@link Comparable} with respect to all other items in the - * sequence). - *

- * - * - * @throws ClassCastException if any item emitted by the Observable does not - * implement {@link Comparable} with respect to - * all other items emitted by the Observable - * @return an Observable that emits the items from the source Observable in - * sorted order - * @see toSortedList() - */ - public Observable> toSortedList() { - return create(OperationToObservableSortedList.toSortedList(this)); - } - - /** - * Return an Observable that emits the items emitted by the source - * Observable, in a sorted order based on a specified comparison function - *

- * - * - * @param sortFunction a function that compares two items emitted by the - * source Observable and returns an Integer that - * indicates their sort order - * @return an Observable that emits the items from the source Observable in - * sorted order - * @see toSortedList() - */ - public Observable> toSortedList(Func2 sortFunction) { - return create(OperationToObservableSortedList.toSortedList(this, sortFunction)); - } - - /** - * Emit a specified set of items before beginning to emit items from the - * source Observable. - *

- * - * - * @param values Iterable of the items you want the modified Observable to - * emit first - * @return an Observable that exhibits the modified behavior - * @see startWith() - */ - public Observable startWith(Iterable values) { - return concat(Observable. from(values), this); - } - - /** - * Emit a specified set of items with the specified scheduler before - * beginning to emit items from the source Observable. - *

- * - * - * @param values iterable of the items you want the modified Observable to - * emit first - * @param scheduler the scheduler to emit the prepended values on - * @return an Observable that exhibits the modified behavior - * @see startWith() - * @see MSDN: Observable.StartWith - */ - public Observable startWith(Iterable values, Scheduler scheduler) { - return concat(from(values, scheduler), this); - } - - /** - * Emit a specified array of items with the specified scheduler before - * beginning to emit items from the source Observable. - *

- * - * - * @param values the items you want the modified Observable to emit first - * @param scheduler the scheduler to emit the prepended values on - * @return an Observable that exhibits the modified behavior - * @see startWith() - * @see MSDN: Observable.StartWith - */ - public Observable startWith(T[] values, Scheduler scheduler) { - return startWith(Arrays.asList(values), scheduler); - } - - /** - * Emit a specified item before beginning to emit items from the source - * Observable. - *

- * - * - * @param t1 item to emit - * @return an Observable that exhibits the modified behavior - * @see startWith() - */ - public Observable startWith(T t1) { - return concat(Observable. from(t1), this); - } - - /** - * Emit a specified set of items before beginning to emit items from the - * source Observable. - *

- * - * - * @param t1 first item to emit - * @param t2 second item to emit - * @return an Observable that exhibits the modified behavior - * @see startWith() - */ - public Observable startWith(T t1, T t2) { - return concat(Observable. from(t1, t2), this); - } - - /** - * Emit a specified set of items before beginning to emit items from the - * source Observable. - *

- * - * - * @param t1 first item to emit - * @param t2 second item to emit - * @param t3 third item to emit - * @return an Observable that exhibits the modified behavior - * @see startWith() - */ - public Observable startWith(T t1, T t2, T t3) { - return concat(Observable. from(t1, t2, t3), this); - } - - /** - * Emit a specified set of items before beginning to emit items from the - * source Observable. - *

- * - * - * @param t1 first item to emit - * @param t2 second item to emit - * @param t3 third item to emit - * @param t4 fourth item to emit - * @return an Observable that exhibits the modified behavior - * @see startWith() - */ - public Observable startWith(T t1, T t2, T t3, T t4) { - return concat(Observable. from(t1, t2, t3, t4), this); - } - - /** - * Emit a specified set of items before beginning to emit items from the - * source Observable. - *

- * - * - * @param t1 first item to emit - * @param t2 second item to emit - * @param t3 third item to emit - * @param t4 fourth item to emit - * @param t5 fifth item to emit - * @return an Observable that exhibits the modified behavior - * @see startWith() - */ - public Observable startWith(T t1, T t2, T t3, T t4, T t5) { - return concat(Observable. from(t1, t2, t3, t4, t5), this); - } - - /** - * Emit a specified set of items before beginning to emit items from the - * source Observable. - *

- * - * - * @param t1 first item to emit - * @param t2 second item to emit - * @param t3 third item to emit - * @param t4 fourth item to emit - * @param t5 fifth item to emit - * @param t6 sixth item to emit - * @return an Observable that exhibits the modified behavior - * @see startWith() - */ - public Observable startWith(T t1, T t2, T t3, T t4, T t5, T t6) { - return concat(Observable. from(t1, t2, t3, t4, t5, t6), this); - } - - /** - * Emit a specified set of items before beginning to emit items from the - * source Observable. - *

- * - * - * @param t1 first item to emit - * @param t2 second item to emit - * @param t3 third item to emit - * @param t4 fourth item to emit - * @param t5 fifth item to emit - * @param t6 sixth item to emit - * @param t7 seventh item to emit - * @return an Observable that exhibits the modified behavior - * @see startWith() - */ - public Observable startWith(T t1, T t2, T t3, T t4, T t5, T t6, T t7) { - return concat(Observable. from(t1, t2, t3, t4, t5, t6, t7), this); - } - - /** - * Emit a specified set of items before beginning to emit items from the - * source Observable. - *

- * - * - * @param t1 first item to emit - * @param t2 second item to emit - * @param t3 third item to emit - * @param t4 fourth item to emit - * @param t5 fifth item to emit - * @param t6 sixth item to emit - * @param t7 seventh item to emit - * @param t8 eighth item to emit - * @return an Observable that exhibits the modified behavior - * @see startWith() - */ - public Observable startWith(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8) { - return concat(Observable. from(t1, t2, t3, t4, t5, t6, t7, t8), this); - } - - /** - * Emit a specified set of items before beginning to emit items from the - * source Observable. - *

- * - * - * @param t1 first item to emit - * @param t2 second item to emit - * @param t3 third item to emit - * @param t4 fourth item to emit - * @param t5 fifth item to emit - * @param t6 sixth item to emit - * @param t7 seventh item to emit - * @param t8 eighth item to emit - * @param t9 ninth item to emit - * @return an Observable that exhibits the modified behavior - * @see startWith() - */ - public Observable startWith(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8, T t9) { - return concat(Observable. from(t1, t2, t3, t4, t5, t6, t7, t8, t9), this); - } - - /** - * Groups the items emitted by an Observable according to a specified - * criterion, and emits these grouped items as {@link GroupedObservable}s, - * one GroupedObservable per group. - *

- * - * - * @param keySelector a function that extracts the key from an item - * @param elementSelector a function to map a source item to an item in a - * {@link GroupedObservable} - * @param the key type - * @param the type of items emitted by the resulting - * {@link GroupedObservable}s - * @return an Observable that emits {@link GroupedObservable}s, each of - * which corresponds to a unique key value and emits items - * representing items from the source Observable that share that key - * value - * @see groupBy - */ - public Observable> groupBy(final Func1 keySelector, final Func1 elementSelector) { - return create(OperationGroupBy.groupBy(this, keySelector, elementSelector)); - } - - /** - * Groups the items emitted by an Observable according to a specified - * criterion, and emits these grouped items as {@link GroupedObservable}s, - * one GroupedObservable per group. - *

- * - * - * @param keySelector a function that extracts the key for each item - * @param the key type - * @return an Observable that emits {@link GroupedObservable}s, each of - * which corresponds to a unique key value and emits items - * representing items from the source Observable that share that key - * value - * @see groupBy - */ - public Observable> groupBy(final Func1 keySelector) { - return create(OperationGroupBy.groupBy(this, keySelector)); - } - - /** - * Returns an {@link Observable} that emits true if the source - * {@link Observable} is empty, otherwise false. - *

- * In Rx.Net this is negated as the any operator but renamed in - * RxJava to better match Java naming idioms. - *

- * - * - * @return an Observable that emits a Boolean - * @see isEmpty() - * @see MSDN: Observable.Any - */ - public Observable isEmpty() { - return create(OperationAny.isEmpty(this)); - } - - /** - * Returns an {@link Observable} that emits the last item emitted by the - * source or an IllegalArgumentException if the source - * {@link Observable} is empty. - *

- * - * - * @return - * @see last() - */ - public Observable last() { - return create(OperationLast.last(this)); - } - - /** - * Converts an Observable into a {@link BlockingObservable} (an Observable - * with blocking operators). - * - * @return - * @see Blocking Observable Operators - */ - public BlockingObservable toBlockingObservable() { - return BlockingObservable.from(this); - } - - /** - * Converts the items emitted by an Observable to the specified type. - *

- * - * - * @param klass the target class type which the items will be converted to - * @return an Observable that emits each item from the source Observable - * converted to the specified type - * @see cast() - * @see MSDN: Observable.Cast - */ - public Observable cast(final Class klass) { - return create(OperationCast.cast(this, klass)); - } - - /** - * Filters the items emitted by an Observable based on the specified type. - *

- * - * - * @param klass the class type to filter the items emitted by the source - * Observable - * @return an Observable that emits items from the source Observable of - * type klass. - * @see ofClass() - * @see MSDN: Observable.OfType - */ - public Observable ofType(final Class klass) { - return filter(new Func1() { - public Boolean call(T t) { - return klass.isInstance(t); - } - }).cast(klass); - } - - /** - * Ignores all items emitted by an Observable and only calls - * onCompleted or onError. - *

- * - * - * @return an empty Observable that only calls onCompleted or - * onError - * @see ignoreElements() - * @see MSDN: Observable.IgnoreElements - */ - public Observable ignoreElements() { - return filter(alwaysFalse()); - } - - /** - * Applies a timeout policy for each element in the observable sequence, - * using the specified scheduler to run timeout timers. If the next element - * isn't received within the specified timeout duration starting from its - * predecessor, a TimeoutException is propagated to the observer. - *

- * - * - * @param timeout maximum duration between values before a timeout occurs - * @param timeUnit the unit of time which applies to the - * timeout argument. - * @return the source Observable with a TimeoutException in - * case of a timeout - * @see timeout() - * @see MSDN: Observable.Timeout - */ - public Observable timeout(long timeout, TimeUnit timeUnit) { - return create(OperationTimeout.timeout(this, timeout, timeUnit)); - } - - /** - * Applies a timeout policy for each element in the observable sequence, - * using the specified scheduler to run timeout timers. If the next element - * isn't received within the specified timeout duration starting from its - * predecessor, the other observable sequence is used to produce future - * messages from that point on. - *

- * - * - * @param timeout maximum duration between values before a timeout occurs - * @param timeUnit the unit of time which applies to the - * timeout argument - * @param other sequence to return in case of a timeout - * @return the source sequence switching to the other sequence in case of a - * timeout - * @see timeout() - * @see MSDN: Observable.Timeout - */ - public Observable timeout(long timeout, TimeUnit timeUnit, Observable other) { - return create(OperationTimeout.timeout(this, timeout, timeUnit, other)); - } - - /** - * Applies a timeout policy for each element in the observable sequence, - * using the specified scheduler to run timeout timers. If the next element - * isn't received within the specified timeout duration starting from its - * predecessor, a TimeoutException is propagated to the observer. - *

- * - * - * @param timeout maximum duration between values before a timeout occurs - * @param timeUnit the unit of time which applies to the - * timeout argument - * @param scheduler Scheduler to run the timeout timers on - * @return the source sequence with a TimeoutException in case - * of a timeout - * @see timeout() - * @see MSDN: Observable.Timeout - */ - public Observable timeout(long timeout, TimeUnit timeUnit, Scheduler scheduler) { - return create(OperationTimeout.timeout(this, timeout, timeUnit, scheduler)); - } - - /** - * Applies a timeout policy for each element in the observable sequence, - * using the specified scheduler to run timeout timers. If the next element - * isn't received within the specified timeout duration starting from its - * predecessor, the other observable sequence is used to produce future - * messages from that point on. - *

- * - * - * @param timeout maximum duration between values before a timeout occurs - * @param timeUnit the unit of time which applies to the - * timeout argument - * @param other sequence to return in case of a timeout - * @param scheduler Scheduler to run the timeout timers on - * @return the source sequence switching to the other sequence in case of a - * timeout - * @see timeout() - * @see MSDN: Observable.Timeout - */ - public Observable timeout(long timeout, TimeUnit timeUnit, Observable other, Scheduler scheduler) { - return create(OperationTimeout.timeout(this, timeout, timeUnit, other, scheduler)); - } - - /** - * Records the time interval between consecutive items emitted by an - * Observable. - *

- * - * - * @return an Observable that emits time interval information items - * @see timeInterval() - * @see MSDN: Observable.TimeInterval - */ - public Observable> timeInterval() { - return create(OperationTimeInterval.timeInterval(this)); - } - - /** - * Records the time interval between consecutive items emitted by an - * Observable, using the specified Scheduler to compute time intervals. - *

- * - * - * @param scheduler Scheduler used to compute time intervals - * @return an Observable that emits time interval information items - * @see timeInterval() - * @see MSDN: Observable.TimeInterval - */ - public Observable> timeInterval(Scheduler scheduler) { - return create(OperationTimeInterval.timeInterval(this, scheduler)); - } - - /** - * Constructs an Observable that depends on a resource object. - *

- * - * - * @param resourceFactory the factory function to obtain a resource object - * that depends on the Observable - * @param observableFactory the factory function to obtain an Observable - * @return the Observable whose lifetime controls the lifetime of the - * dependent resource object - * @see using() - * @see MSDN: Observable.Using - */ - public static Observable using(Func0 resourceFactory, Func1> observableFactory) { - return create(OperationUsing.using(resourceFactory, observableFactory)); - } - - /** - * Propagates the Observable sequence that reacts first. - *

- * - * - * @param o1 an Observable competing to react first - * @param o2 an Observable competing to react first - * @return an Observable that reflects whichever of the given Observables - * reacted first - * @see amb() - * @see MSDN: Observable.Amb - */ - public static Observable amb(Observable o1, Observable o2) { - return create(OperationAmb.amb(o1, o2)); - } - - /** - * Propagates the Observable sequence that reacts first. - *

- * - * - * @param o1 an Observable competing to react first - * @param o2 an Observable competing to react first - * @param o3 an Observable competing to react first - * @return an Observable that reflects whichever of the given Observables - * reacted first - * @see amb() - * @see MSDN: Observable.Amb - */ - public static Observable amb(Observable o1, Observable o2, Observable o3) { - return create(OperationAmb.amb(o1, o2, o3)); - } - - /** - * Propagates the observable sequence that reacts first. - *

- * - * - * @param o1 an Observable competing to react first - * @param o2 an Observable competing to react first - * @param o3 an Observable competing to react first - * @param o4 an Observable competing to react first - * @return an Observable that reflects whichever of the given Observables - * reacted first - * @see amb() - * @see MSDN: Observable.Amb - */ - public static Observable amb(Observable o1, Observable o2, Observable o3, Observable o4) { - return create(OperationAmb.amb(o1, o2, o3, o4)); - } - - /** - * Propagates the Observable sequence that reacts first. - *

- * - * - * @param o1 an Observable competing to react first - * @param o2 an Observable competing to react first - * @param o3 an Observable competing to react first - * @param o4 an Observable competing to react first - * @param o5 an Observable competing to react first - * @return an Observable that reflects whichever of the given Observables - * reacted first - * @see amb() - * @see MSDN: Observable.Amb - */ - public static Observable amb(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5) { - return create(OperationAmb.amb(o1, o2, o3, o4, o5)); - } - - /** - * Propagates the observable sequence that reacts first. - *

- * - * - * @param o1 an Observable competing to react first - * @param o2 an Observable competing to react first - * @param o3 an Observable competing to react first - * @param o4 an Observable competing to react first - * @param o5 an Observable competing to react first - * @param o6 an Observable competing to react first - * @return an Observable that reflects whichever of the given Observables - * reacted first - * @see amb() - * @see MSDN: Observable.Amb - */ - public static Observable amb(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6) { - return create(OperationAmb.amb(o1, o2, o3, o4, o5, o6)); - } - - /** - * Propagates the observable sequence that reacts first. - *

- * - * - * @param o1 an Observable competing to react first - * @param o2 an Observable competing to react first - * @param o3 an Observable competing to react first - * @param o4 an Observable competing to react first - * @param o5 an Observable competing to react first - * @param o6 an Observable competing to react first - * @param o7 an Observable competing to react first - * @return an Observable that reflects whichever of the given Observables - * reacted first - * @see amb() - * @see MSDN: Observable.Amb - */ - public static Observable amb(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7) { - return create(OperationAmb.amb(o1, o2, o3, o4, o5, o6, o7)); - } - - /** - * Propagates the observable sequence that reacts first. - *

- * - * - * @param o1 an Observable competing to react first - * @param o2 an Observable competing to react first - * @param o3 an Observable competing to react first - * @param o4 an Observable competing to react first - * @param o5 an Observable competing to react first - * @param o6 an Observable competing to react first - * @param o7 an Observable competing to react first - * @param o8 an observable competing to react first - * @return an Observable that reflects whichever of the given Observables - * reacted first - * @see amb() - * @see MSDN: Observable.Amb - */ - public static Observable amb(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, Observable o8) { - return create(OperationAmb.amb(o1, o2, o3, o4, o5, o6, o7, o8)); - } - - /** - * Propagates the observable sequence that reacts first. - *

- * - * - * @param o1 an Observable competing to react first - * @param o2 an Observable competing to react first - * @param o3 an Observable competing to react first - * @param o4 an Observable competing to react first - * @param o5 an Observable competing to react first - * @param o6 an Observable competing to react first - * @param o7 an Observable competing to react first - * @param o8 an Observable competing to react first - * @param o9 an Observable competing to react first - * @return an Observable that reflects whichever of the given Observables - * reacted first - * @see amb() - * @see MSDN: Observable.Amb - */ - public static Observable amb(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, Observable o8, Observable o9) { - return create(OperationAmb.amb(o1, o2, o3, o4, o5, o6, o7, o8, o9)); - } - - /** - * Propagates the observable sequence that reacts first. - *

- * - * - * @param sources Observable sources competing to react first - * @return an Observable that reflects whichever of the given Observables - * reacted first - * @see amb() - * @see MSDN: Observable.Amb - */ - public static Observable amb(Iterable> sources) { - return create(OperationAmb.amb(sources)); - } - - /** - * Invokes an action for each item emitted by the Observable. - *

- * - * - * @param observer the action to invoke for each item emitted in the source - * sequence - * @return the source sequence with the side-effecting behavior applied - * @see doOnEach() - * @see MSDN: Observable.Do - */ - public Observable doOnEach(Observer observer) { - return create(OperationDoOnEach.doOnEach(this, observer)); - } - - /** - * Invokes an action for each item emitted by an Observable. - *

- * - * - * @param onNext the action to invoke for each item in the source - * sequence - * @return the source sequence with the side-effecting behavior applied - * @see doOnEach() - * @see MSDN: Observable.Do - */ - public Observable doOnEach(final Action1 onNext) { - Observer observer = new Observer() { - @Override - public void onCompleted() {} - - @Override - public void onError(Throwable e) {} - - @Override - public void onNext(T args) { - onNext.call(args); - } - - }; - - - return create(OperationDoOnEach.doOnEach(this, observer)); - } - - /** - * Invokes an action if onError is called from the Observable. - *

- * - * - * @param onError the action to invoke if onError is invoked - * @return the source sequence with the side-effecting behavior applied - * @see doOnError() - * @see MSDN: Observable.Do - */ - public Observable doOnError(final Action1 onError) { - Observer observer = new Observer() { - @Override - public void onCompleted() {} - - @Override - public void onError(Throwable e) { - onError.call(e); - } - - @Override - public void onNext(T args) { } - - }; - - - return create(OperationDoOnEach.doOnEach(this, observer)); - } - - /** - * Invokes an action when onCompleted is called by the - * Observable. - *

- * - * - * @param onCompleted the action to invoke when onCompleted is - * called - * @return the source sequence with the side-effecting behavior applied - * @see doOnCompleted() - * @see MSDN: Observable.Do - */ - public Observable doOnCompleted(final Action0 onCompleted) { - Observer observer = new Observer() { - @Override - public void onCompleted() { - onCompleted.call(); - } - - @Override - public void onError(Throwable e) { } - - @Override - public void onNext(T args) { } - - }; - - - return create(OperationDoOnEach.doOnEach(this, observer)); - } - - /** - * Invokes an action for each item emitted by an Observable. - * - * @param onNext the action to invoke for each item in the source sequence - * @param onError the action to invoke when the source Observable calls - * onError - * @return the source sequence with the side-effecting behavior applied - * @see doOnEach() - * @see MSDN: Observable.Do - */ - public Observable doOnEach(final Action1 onNext, final Action1 onError) { - Observer observer = new Observer() { - @Override - public void onCompleted() {} - - @Override - public void onError(Throwable e) { - onError.call(e); - } - - @Override - public void onNext(T args) { - onNext.call(args); - } - - }; - - - return create(OperationDoOnEach.doOnEach(this, observer)); - } - - /** - * Invokes an action for each item emitted by an Observable. - * - * @param onNext the action to invoke for each item in the source sequence - * @param onError the action to invoke when the source Observable calls - * onError - * @param onCompleted the action to invoke when the source Observable calls - * onCompleted - * @return the source sequence with the side-effecting behavior applied - * @see doOnEach() - * @see MSDN: Observable.Do - */ - public Observable doOnEach(final Action1 onNext, final Action1 onError, final Action0 onCompleted) { - Observer observer = new Observer() { - @Override - public void onCompleted() { - onCompleted.call(); - } - - @Override - public void onError(Throwable e) { - onError.call(e); - } - - @Override - public void onNext(T args) { - onNext.call(args); - } - - }; - - - return create(OperationDoOnEach.doOnEach(this, observer)); - } - - /** - * Whether a given {@link Function} is an internal implementation inside - * rx.* packages or not. - *

- * For why this is being used see - * https://github.com/Netflix/RxJava/issues/216 for discussion on - * "Guideline 6.4: Protect calls to user code from within an operator" - * - * Note: If strong reasons for not depending on package names comes up then - * the implementation of this method can change to looking for a marker - * interface. - * - * @param o - * @return {@code true} if the given function is an internal implementation, - * and {@code false} otherwise. - */ - private boolean isInternalImplementation(Object o) { - if (o == null) { - return true; - } - // prevent double-wrapping (yeah it happens) - if (o instanceof SafeObserver) { - return true; - } - - Class clazz = o.getClass(); - if (internalClassMap.containsKey(clazz)) { - //don't need to do reflection - return internalClassMap.get(clazz); - } else { - // we treat the following package as "internal" and don't wrap it - Package p = o.getClass().getPackage(); // it can be null - Boolean isInternal = (p != null && p.getName().startsWith("rx.operators")); - internalClassMap.put(clazz, isInternal); - return isInternal; - } - } - - /** - * Creates a pattern that matches when both Observable sequences have an - * available item. - *

- * - * - * @param right Observable sequence to match with the left sequence - * @return Pattern object that matches when both Observable sequences have - * an available item - * @throws NullPointerException if right is null - * @see and() - * @see MSDN: Observable.And - */ - public Pattern2 and(Observable right) { - return OperationJoinPatterns.and(this, right); - } - - /** - * Matches when the Observable sequence has an available item and - * projects the item by invoking the selector function. - *

- * - * - * @param selector Selector that will be invoked for elements in the source - * sequence - * @return Plan that produces the projected results, to be fed (with other - * plans) to the When operator - * @throws NullPointerException if selector is null - * @see then() - * @see MSDN: Observable.Then - */ - public Plan0 then(Func1 selector) { - return OperationJoinPatterns.then(this, selector); - } - - /** - * Joins together the results from several patterns. - *

- * - * - * @param plans a series of plans created by use of the Then operator on - * patterns - * @return an Observable sequence with the results from matching several - * patterns - * @throws NullPointerException if plans is null - * @see when() - * @see MSDN: Observable.When - */ - public static Observable when(Plan0... plans) { - return create(OperationJoinPatterns.when(plans)); - } - - /** - * Joins together the results from several patterns. - *

- * - * - * @param plans a series of plans created by use of the Then operator on - * patterns - * @return an Observable sequence with the results from matching several - * patterns - * @throws NullPointerException if plans is null - * @see when() - * @see MSDN: Observable.When - */ - public static Observable when(Iterable> plans) { - if (plans == null) { - throw new NullPointerException("plans"); - } - return create(OperationJoinPatterns.when(plans)); - } - - /** - * Joins the results from a pattern. - *

- * - * - * @param p1 the plan to join - * @return an Observable sequence with the results from matching a pattern - * @see when() - * @see MSDN: Observable.When - */ - @SuppressWarnings("unchecked") - public static Observable when(Plan0 p1) { - return create(OperationJoinPatterns.when(p1)); - } - - /** - * Joins together the results from several patterns. - *

- * - * - * @param p1 a plan - * @param p2 a plan - * @return an Observable sequence with the results from matching several - * patterns - * @see when() - * @see MSDN: Observable.When - */ - @SuppressWarnings("unchecked") - public static Observable when(Plan0 p1, Plan0 p2) { - return create(OperationJoinPatterns.when(p1, p2)); - } - - /** - * Joins together the results from several patterns. - *

- * - * - * @param p1 a plan - * @param p2 a plan - * @param p3 a plan - * @return an Observable sequence with the results from matching several - * patterns - * @see when() - * @see MSDN: Observable.When - */ - @SuppressWarnings("unchecked") - public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3) { - return create(OperationJoinPatterns.when(p1, p2, p3)); - } - - /** - * Joins together the results from several patterns. - *

- * - * - * @param p1 a plan - * @param p2 a plan - * @param p3 a plan - * @param p4 a plan - * @return an Observable sequence with the results from matching several - * patterns - * @see when() - * @see MSDN: Observable.When - */ - @SuppressWarnings("unchecked") - public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3, Plan0 p4) { - return create(OperationJoinPatterns.when(p1, p2, p3, p4)); - } - - /** - * Joins together the results from several patterns. - *

- * - * - * @param p1 a plan - * @param p2 a plan - * @param p3 a plan - * @param p4 a plan - * @param p5 a plan - * @return an Observable sequence with the results from matching several - * patterns - * @see when() - * @see MSDN: Observable.When - */ - @SuppressWarnings("unchecked") - public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3, Plan0 p4, Plan0 p5) { - return create(OperationJoinPatterns.when(p1, p2, p3, p4, p5)); - } - - /** - * Joins together the results from several patterns. - *

- * - * - * @param p1 a plan - * @param p2 a plan - * @param p3 a plan - * @param p4 a plan - * @param p5 a plan - * @param p6 a plan - * @return an Observable sequence with the results from matching several - * patterns - * @see when() - * @see MSDN: Observable.When - */ - @SuppressWarnings("unchecked") - public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3, Plan0 p4, Plan0 p5, Plan0 p6) { - return create(OperationJoinPatterns.when(p1, p2, p3, p4, p5, p6)); - } - - /** - * Joins together the results from several patterns. - *

- * - * - * @param p1 a plan - * @param p2 a plan - * @param p3 a plan - * @param p4 a plan - * @param p5 a plan - * @param p6 a plan - * @param p7 a plan - * @return an Observable sequence with the results from matching several - * patterns - * @see when() - * @see MSDN: Observable.When - */ - @SuppressWarnings("unchecked") - public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3, Plan0 p4, Plan0 p5, Plan0 p6, Plan0 p7) { - return create(OperationJoinPatterns.when(p1, p2, p3, p4, p5, p6, p7)); - } - - /** - * Joins together the results from several patterns. - *

- * - * - * @param p1 a plan - * @param p2 a plan - * @param p3 a plan - * @param p4 a plan - * @param p5 a plan - * @param p6 a plan - * @param p7 a plan - * @param p8 a plan - * @return an Observable sequence with the results from matching several - * patterns - * @see when() - * @see MSDN: Observable.When - */ - @SuppressWarnings("unchecked") - public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3, Plan0 p4, Plan0 p5, Plan0 p6, Plan0 p7, Plan0 p8) { - return create(OperationJoinPatterns.when(p1, p2, p3, p4, p5, p6, p7, p8)); - } - - /** - * Joins together the results from several patterns. - *

- * - * - * @param p1 a plan - * @param p2 a plan - * @param p3 a plan - * @param p4 a plan - * @param p5 a plan - * @param p6 a plan - * @param p7 a plan - * @param p8 a plan - * @param p9 a plan - * @return an Observable sequence with the results from matching several - * patterns - * @see when() - * @see MSDN: Observable.When - */ - @SuppressWarnings("unchecked") - public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3, Plan0 p4, Plan0 p5, Plan0 p6, Plan0 p7, Plan0 p8, Plan0 p9) { - return create(OperationJoinPatterns.when(p1, p2, p3, p4, p5, p6, p7, p8, p9)); - } -} - +/** + * Copyright 2013 Netflix, Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not + * use this file except in compliance with the License. You may obtain a copy of + * the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations + * under the License. + */ +package rx; + +import static rx.util.functions.Functions.*; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Comparator; +import java.util.List; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.Future; +import java.util.concurrent.TimeUnit; + +import rx.concurrency.Schedulers; +import rx.joins.Pattern2; +import rx.joins.Plan0; +import rx.observables.BlockingObservable; +import rx.observables.ConnectableObservable; +import rx.observables.GroupedObservable; +import rx.operators.OperationAll; +import rx.operators.OperationAmb; +import rx.operators.OperationAny; +import rx.operators.OperationAverage; +import rx.operators.OperationBuffer; +import rx.operators.OperationCache; +import rx.operators.OperationCast; +import rx.operators.OperationCombineLatest; +import rx.operators.OperationConcat; +import rx.operators.OperationDebounce; +import rx.operators.OperationDefaultIfEmpty; +import rx.operators.OperationDefer; +import rx.operators.OperationDematerialize; +import rx.operators.OperationDistinct; +import rx.operators.OperationDistinctUntilChanged; +import rx.operators.OperationDoOnEach; +import rx.operators.OperationElementAt; +import rx.operators.OperationFilter; +import rx.operators.OperationFinally; +import rx.operators.OperationFirstOrDefault; +import rx.operators.OperationGroupBy; +import rx.operators.OperationInterval; +import rx.operators.OperationJoin; +import rx.operators.OperationJoinPatterns; +import rx.operators.OperationLast; +import rx.operators.OperationMap; +import rx.operators.OperationMaterialize; +import rx.operators.OperationMerge; +import rx.operators.OperationMergeDelayError; +import rx.operators.OperationMinMax; +import rx.operators.OperationMulticast; +import rx.operators.OperationObserveOn; +import rx.operators.OperationOnErrorResumeNextViaFunction; +import rx.operators.OperationOnErrorResumeNextViaObservable; +import rx.operators.OperationOnErrorReturn; +import rx.operators.OperationOnExceptionResumeNextViaObservable; +import rx.operators.OperationParallel; +import rx.operators.OperationParallelMerge; +import rx.operators.OperationRetry; +import rx.operators.OperationSample; +import rx.operators.OperationScan; +import rx.operators.OperationSkip; +import rx.operators.OperationSkipLast; +import rx.operators.OperationSkipWhile; +import rx.operators.OperationSubscribeOn; +import rx.operators.OperationSum; +import rx.operators.OperationSwitch; +import rx.operators.OperationSynchronize; +import rx.operators.OperationTake; +import rx.operators.OperationTakeLast; +import rx.operators.OperationTakeUntil; +import rx.operators.OperationTakeWhile; +import rx.operators.OperationThrottleFirst; +import rx.operators.OperationTimeInterval; +import rx.operators.OperationTimeout; +import rx.operators.OperationTimestamp; +import rx.operators.OperationToObservableFuture; +import rx.operators.OperationToObservableIterable; +import rx.operators.OperationToObservableList; +import rx.operators.OperationToObservableSortedList; +import rx.operators.OperationUsing; +import rx.operators.OperationWindow; +import rx.operators.OperationZip; +import rx.operators.SafeObservableSubscription; +import rx.operators.SafeObserver; +import rx.plugins.RxJavaErrorHandler; +import rx.plugins.RxJavaObservableExecutionHook; +import rx.plugins.RxJavaPlugins; +import rx.subjects.AsyncSubject; +import rx.subjects.PublishSubject; +import rx.subjects.ReplaySubject; +import rx.subjects.Subject; +import rx.subscriptions.Subscriptions; +import rx.util.Closing; +import rx.util.OnErrorNotImplementedException; +import rx.util.Opening; +import rx.util.Range; +import rx.util.TimeInterval; +import rx.util.Timestamped; +import rx.util.functions.Action0; +import rx.util.functions.Action1; +import rx.util.functions.Func0; +import rx.util.functions.Func1; +import rx.util.functions.Func2; +import rx.util.functions.Func3; +import rx.util.functions.Func4; +import rx.util.functions.Func5; +import rx.util.functions.Func6; +import rx.util.functions.Func7; +import rx.util.functions.Func8; +import rx.util.functions.Func9; +import rx.util.functions.FuncN; +import rx.util.functions.Function; + +/** + * The Observable interface that implements the Reactive Pattern. + *

+ * This interface provides overloaded methods for subscribing as well as + * delegate methods to the various operators. + *

+ * The documentation for this interface makes use of marble diagrams. The + * following legend explains these diagrams: + *

+ * + *

+ * For more information see the + * RxJava Wiki + * + * @param the type of the item emitted by the Observable + */ +public class Observable { + + private final static ConcurrentHashMap internalClassMap = new ConcurrentHashMap(); + + /** + * Executed when 'subscribe' is invoked. + */ + private final OnSubscribeFunc onSubscribe; + + /** + * Function interface for work to be performed when an {@link Observable} + * is subscribed to via {@link Observable#subscribe(Observer)} + * + * @param + */ + public static interface OnSubscribeFunc extends Function { + + public Subscription onSubscribe(Observer t1); + + } + + /** + * Observable with Function to execute when subscribed to. + *

+ * NOTE: Use {@link #create(OnSubscribeFunc)} to create an Observable + * instead of this constructor unless you specifically have a need for + * inheritance. + * + * @param onSubscribe {@link OnSubscribeFunc} to be executed when + * {@link #subscribe(Observer)} is called + */ + protected Observable(OnSubscribeFunc onSubscribe) { + this.onSubscribe = onSubscribe; + } + + private final static RxJavaObservableExecutionHook hook = RxJavaPlugins.getInstance().getObservableExecutionHook(); + + /** + * An {@link Observer} must call an Observable's {@code subscribe} method in + * order to receive items and notifications from the Observable. + *

+ * A typical implementation of {@code subscribe} does the following: + *

    + *
  1. It stores a reference to the Observer in a collection object, such as + * a {@code List} object.
  2. + *
  3. It returns a reference to the {@link Subscription} interface. This + * enables Observers to unsubscribe, that is, to stop receiving items + * and notifications before the Observable stops sending them, which + * also invokes the Observer's {@link Observer#onCompleted onCompleted} + * method.
  4. + *

+ * An Observable<T> instance is responsible for accepting + * all subscriptions and notifying all Observers. Unless the documentation + * for a particular Observable<T> implementation + * indicates otherwise, Observers should make no assumptions about the order + * in which multiple Observers will receive their notifications. + *

+ * For more information see the + * RxJava Wiki + * + * @param observer the Observer + * @return a {@link Subscription} reference with which the {@link Observer} + * can stop receiving items before the Observable has finished + * sending them + * @throws IllegalArgumentException if the {@link Observer} provided as the + * argument to {@code subscribe()} is + * {@code null} + */ + public Subscription subscribe(Observer observer) { + // allow the hook to intercept and/or decorate + OnSubscribeFunc onSubscribeFunction = hook.onSubscribeStart(this, onSubscribe); + // validate and proceed + if (observer == null) { + throw new IllegalArgumentException("observer can not be null"); + } + if (onSubscribeFunction == null) { + throw new IllegalStateException("onSubscribe function can not be null."); + // the subscribe function can also be overridden but generally that's not the appropriate approach so I won't mention that in the exception + } + try { + /** + * See https://github.com/Netflix/RxJava/issues/216 for discussion on "Guideline 6.4: Protect calls to user code from within an operator" + */ + if (isInternalImplementation(observer)) { + Subscription s = onSubscribeFunction.onSubscribe(observer); + if (s == null) { + // this generally shouldn't be the case on a 'trusted' onSubscribe but in case it happens + // we want to gracefully handle it the same as AtomicObservableSubscription does + return hook.onSubscribeReturn(this, Subscriptions.empty()); + } else { + return hook.onSubscribeReturn(this, s); + } + } else { + SafeObservableSubscription subscription = new SafeObservableSubscription(); + subscription.wrap(onSubscribeFunction.onSubscribe(new SafeObserver(subscription, observer))); + return hook.onSubscribeReturn(this, subscription); + } + } catch (OnErrorNotImplementedException e) { + // special handling when onError is not implemented ... we just rethrow + throw e; + } catch (Throwable e) { + // if an unhandled error occurs executing the onSubscribe we will propagate it + try { + observer.onError(hook.onSubscribeError(this, e)); + } catch (OnErrorNotImplementedException e2) { + // special handling when onError is not implemented ... we just rethrow + throw e2; + } catch (Throwable e2) { + // if this happens it means the onError itself failed (perhaps an invalid function implementation) + // so we are unable to propagate the error correctly and will just throw + RuntimeException r = new RuntimeException("Error occurred attempting to subscribe [" + e.getMessage() + "] and then again while trying to pass to onError.", e2); + hook.onSubscribeError(this, r); + throw r; + } + return Subscriptions.empty(); + } + } + + /** + * An {@link Observer} must call an Observable's {@code subscribe} method in + * order to receive items and notifications from the Observable. + *

+ * A typical implementation of {@code subscribe} does the following: + *

    + *
  1. It stores a reference to the Observer in a collection object, such as + * a {@code List} object.
  2. + *
  3. It returns a reference to the {@link Subscription} interface. This + * enables Observers to unsubscribe, that is, to stop receiving items + * and notifications before the Observable stops sending them, which + * also invokes the Observer's {@link Observer#onCompleted onCompleted} + * method.
  4. + *

+ * An {@code Observable} instance is responsible for accepting all + * subscriptions and notifying all Observers. Unless the documentation for a + * particular {@code Observable} implementation indicates otherwise, + * Observers should make no assumptions about the order in which multiple + * Observers will receive their notifications. + *

+ * For more information see the + * RxJava Wiki + * + * @param observer the Observer + * @param scheduler the {@link Scheduler} on which Observers subscribe to + * the Observable + * @return a {@link Subscription} reference with which Observers can stop + * receiving items and notifications before the Observable has + * finished sending them + * @throws IllegalArgumentException if an argument to {@code subscribe()} + * is {@code null} + */ + public Subscription subscribe(Observer observer, Scheduler scheduler) { + return subscribeOn(scheduler).subscribe(observer); + } + + /** + * Protects against errors being thrown from Observer implementations and + * ensures onNext/onError/onCompleted contract compliance. + *

+ * See https://github.com/Netflix/RxJava/issues/216 for a discussion on + * "Guideline 6.4: Protect calls to user code from within an operator" + */ + private Subscription protectivelyWrapAndSubscribe(Observer o) { + SafeObservableSubscription subscription = new SafeObservableSubscription(); + return subscription.wrap(subscribe(new SafeObserver(subscription, o))); + } + + /** + * Subscribe and ignore all events. + * + * @return + */ + public Subscription subscribe() { + return protectivelyWrapAndSubscribe(new Observer() { + + @Override + public void onCompleted() { + // do nothing + } + + @Override + public void onError(Throwable e) { + handleError(e); + throw new OnErrorNotImplementedException(e); + } + + @Override + public void onNext(T args) { + // do nothing + } + + }); + } + + /** + * An {@link Observer} must call an Observable's {@code subscribe} method + * in order to receive items and notifications from the Observable. + * + * @param onNext + * @return + */ + public Subscription subscribe(final Action1 onNext) { + if (onNext == null) { + throw new IllegalArgumentException("onNext can not be null"); + } + + /** + * Wrapping since raw functions provided by the user are being invoked. + * + * See https://github.com/Netflix/RxJava/issues/216 for discussion on "Guideline 6.4: Protect calls to user code from within an operator" + */ + return protectivelyWrapAndSubscribe(new Observer() { + + @Override + public void onCompleted() { + // do nothing + } + + @Override + public void onError(Throwable e) { + handleError(e); + throw new OnErrorNotImplementedException(e); + } + + @Override + public void onNext(T args) { + onNext.call(args); + } + + }); + } + + /** + * An {@link Observer} must call an Observable's {@code subscribe} method in + * order to receive items and notifications from the Observable. + * + * @param onNext + * @param scheduler + * @return + */ + public Subscription subscribe(final Action1 onNext, Scheduler scheduler) { + return subscribeOn(scheduler).subscribe(onNext); + } + + /** + * An {@link Observer} must call an Observable's {@code subscribe} method in + * order to receive items and notifications from the Observable. + * + * @param onNext + * @param onError + * @return + */ + public Subscription subscribe(final Action1 onNext, final Action1 onError) { + if (onNext == null) { + throw new IllegalArgumentException("onNext can not be null"); + } + if (onError == null) { + throw new IllegalArgumentException("onError can not be null"); + } + + /** + * Wrapping since raw functions provided by the user are being invoked. + * + * See https://github.com/Netflix/RxJava/issues/216 for discussion on "Guideline 6.4: Protect calls to user code from within an operator" + */ + return protectivelyWrapAndSubscribe(new Observer() { + + @Override + public void onCompleted() { + // do nothing + } + + @Override + public void onError(Throwable e) { + handleError(e); + onError.call(e); + } + + @Override + public void onNext(T args) { + onNext.call(args); + } + + }); + } + + /** + * An {@link Observer} must call an Observable's {@code subscribe} method in + * order to receive items and notifications from the Observable. + * + * @param onNext + * @param onError + * @param scheduler + * @return + */ + public Subscription subscribe(final Action1 onNext, final Action1 onError, Scheduler scheduler) { + return subscribeOn(scheduler).subscribe(onNext, onError); + } + + /** + * An {@link Observer} must call an Observable's {@code subscribe} method in + * order to receive items and notifications from the Observable. + * + * @param onNext + * @param onError + * @param onComplete + * @return + */ + public Subscription subscribe(final Action1 onNext, final Action1 onError, final Action0 onComplete) { + if (onNext == null) { + throw new IllegalArgumentException("onNext can not be null"); + } + if (onError == null) { + throw new IllegalArgumentException("onError can not be null"); + } + if (onComplete == null) { + throw new IllegalArgumentException("onComplete can not be null"); + } + + /** + * Wrapping since raw functions provided by the user are being invoked. + * + * See https://github.com/Netflix/RxJava/issues/216 for discussion on "Guideline 6.4: Protect calls to user code from within an operator" + */ + return protectivelyWrapAndSubscribe(new Observer() { + + @Override + public void onCompleted() { + onComplete.call(); + } + + @Override + public void onError(Throwable e) { + handleError(e); + onError.call(e); + } + + @Override + public void onNext(T args) { + onNext.call(args); + } + + }); + } + + /** + * An {@link Observer} must call an Observable's {@code subscribe} method in + * order to receive items and notifications from the Observable. + * + * @param onNext + * @param onError + * @param onComplete + * @param scheduler + * @return + */ + public Subscription subscribe(final Action1 onNext, final Action1 onError, final Action0 onComplete, Scheduler scheduler) { + return subscribeOn(scheduler).subscribe(onNext, onError, onComplete); + } + + /** + * Returns a {@link ConnectableObservable} that upon connection causes the + * source Observable to push results into the specified subject. + * + * @param subject the {@link Subject} for the {@link ConnectableObservable} + * to push source items into + * @param result type + * @return a {@link ConnectableObservable} that upon connection causes the + * source Observable to push results into the specified + * {@link Subject} + * @see Observable.publish() and Observable.multicast() + */ + public ConnectableObservable multicast(Subject subject) { + return OperationMulticast.multicast(this, subject); + } + + /** + * Allow the {@link RxJavaErrorHandler} to receive the exception from + * onError. + * + * @param e + */ + private void handleError(Throwable e) { + // onError should be rare so we'll only fetch when needed + RxJavaPlugins.getInstance().getErrorHandler().handleError(e); + } + + /** + * An Observable that never sends any information to an {@link Observer}. + * + * This Observable is useful primarily for testing purposes. + * + * @param the type of item emitted by the Observable + */ + private static class NeverObservable extends Observable { + public NeverObservable() { + super(new OnSubscribeFunc() { + + @Override + public Subscription onSubscribe(Observer t1) { + return Subscriptions.empty(); + } + + }); + } + } + + /** + * An Observable that invokes {@link Observer#onError onError} when the + * {@link Observer} subscribes to it. + * + * @param the type of item emitted by the Observable + */ + private static class ThrowObservable extends Observable { + + public ThrowObservable(final Throwable exception) { + super(new OnSubscribeFunc() { + + /** + * Accepts an {@link Observer} and calls its + * {@link Observer#onError onError} method. + * + * @param observer an {@link Observer} of this Observable + * @return a reference to the subscription + */ + @Override + public Subscription onSubscribe(Observer observer) { + observer.onError(exception); + return Subscriptions.empty(); + } + + }); + } + + } + + /** + * Creates an Observable that will execute the given function when an + * {@link Observer} subscribes to it. + *

+ * + *

+ * Write the function you pass to create so that it behaves as + * an Observable: It should invoke the Observer's + * {@link Observer#onNext onNext}, {@link Observer#onError onError}, and + * {@link Observer#onCompleted onCompleted} methods appropriately. + *

+ * A well-formed Observable must invoke either the Observer's + * onCompleted method exactly once or its onError + * method exactly once. + *

+ * See Rx Design + * Guidelines (PDF) for detailed information. + * + * @param the type of the items that this Observable emits + * @param func a function that accepts an {@code Observer}, invokes its + * {@code onNext}, {@code onError}, and {@code onCompleted} + * methods as appropriate, and returns a {@link Subscription} to + * allow the Observer to cancel the subscription + * @return an Observable that, when an {@link Observer} subscribes to it, + * will execute the given function + * @see create() + */ + public static Observable create(OnSubscribeFunc func) { + return new Observable(func); + } + + /** + * Returns an Observable that emits no data to the {@link Observer} and + * immediately invokes its {@link Observer#onCompleted onCompleted} method. + *

+ * + * + * @param the type of the items (ostensibly) emitted by the Observable + * @return an Observable that returns no data to the {@link Observer} and + * immediately invokes the {@link Observer}'s + * {@link Observer#onCompleted() onCompleted} method + * @see empty() + * @see MSDN: Observable.Empty Method + */ + public static Observable empty() { + return from(new ArrayList()); + } + + /** + * Returns an Observable that emits no data to the {@link Observer} and + * immediately invokes its {@link Observer#onCompleted onCompleted} method + * with the specified scheduler. + *

+ * + * + * @param scheduler the scheduler to call the + {@link Observer#onCompleted onCompleted} method + * @param the type of the items (ostensibly) emitted by the Observable + * @return an Observable that returns no data to the {@link Observer} and + * immediately invokes the {@link Observer}'s + * {@link Observer#onCompleted() onCompleted} method with the + * specified scheduler + * @see empty() + * @see MSDN: Observable.Empty Method (IScheduler) + */ + public static Observable empty(Scheduler scheduler) { + return Observable. empty().subscribeOn(scheduler); + } + + /** + * Returns an Observable that invokes an {@link Observer}'s + * {@link Observer#onError onError} method when the Observer subscribes to + * it. + *

+ * + * + * @param exception the particular error to report + * @param the type of the items (ostensibly) emitted by the Observable + * @return an Observable that invokes the {@link Observer}'s + * {@link Observer#onError onError} method when the Observer + * subscribes to it + * @see error() + * @see MSDN: Observable.Throw Method + */ + public static Observable error(Throwable exception) { + return new ThrowObservable(exception); + } + + /** + * Returns an Observable that invokes an {@link Observer}'s + * {@link Observer#onError onError} method with the specified scheduler. + *

+ * + * + * @param exception the particular error to report + * @param scheduler the scheduler to call the + * {@link Observer#onError onError} method + * @param the type of the items (ostensibly) emitted by the Observable + * @return an Observable that invokes the {@link Observer}'s + * {@link Observer#onError onError} method with the specified + * scheduler + * @see error() + * @see MSDN: Observable.Throw Method + */ + public static Observable error(Throwable exception, Scheduler scheduler) { + return Observable. error(exception).subscribeOn(scheduler); + } + + /** + * Converts an {@link Iterable} sequence into an Observable. + *

+ * + *

+ * Note: the entire iterable sequence is immediately emitted each time an + * {@link Observer} subscribes. Since this occurs before the + * {@link Subscription} is returned, it is not possible to unsubscribe from + * the sequence before it completes. + * + * @param iterable the source {@link Iterable} sequence + * @param the type of items in the {@link Iterable} sequence and the + * type of items to be emitted by the resulting Observable + * @return an Observable that emits each item in the source {@link Iterable} + * sequence + * @see from() + */ + public static Observable from(Iterable iterable) { + return create(OperationToObservableIterable.toObservableIterable(iterable)); + } + + /** + * Converts an {@link Iterable} sequence into an Observable with the specified scheduler. + *

+ * + * + * @param iterable the source {@link Iterable} sequence + * @param scheduler the scheduler to emit the items of the iterable + * @param the type of items in the {@link Iterable} sequence and the + * type of items to be emitted by the resulting Observable + * @return an Observable that emits each item in the source {@link Iterable} + * sequence with the specified scheduler + * @see from() + * @see MSDN: Observable.ToObservable + */ + public static Observable from(Iterable iterable, Scheduler scheduler) { + return from(iterable).observeOn(scheduler); + } + + /** + * Converts an Array into an Observable. + *

+ * + *

+ * Note: the entire array is immediately emitted each time an + * {@link Observer} subscribes. Since this occurs before the + * {@link Subscription} is returned, it is not possible to unsubscribe from + * the sequence before it completes. + * + * @param items the source sequence + * @param the type of items in the Array and the type of items to be + * emitted by the resulting Observable + * @return an Observable that emits each item in the source Array + * @see from() + */ + public static Observable from(T[] items) { + return create(OperationToObservableIterable.toObservableIterable(Arrays.asList(items))); + } + + /** + * Converts an item into an Observable that emits that item. + *

+ * + *

+ * Note: the item is immediately emitted each time an {@link Observer} + * subscribes. Since this occurs before the {@link Subscription} is + * returned, it is not possible to unsubscribe from the sequence before it + * completes. + * + * @param t1 the item + * @param the type of the item, and the type of the item to be + * emitted by the resulting Observable + * @return an Observable that emits the item + * @see from() + */ + @SuppressWarnings("unchecked") + // suppress unchecked because we are using varargs inside the method + public static Observable from(T t1) { + return from(Arrays.asList(t1)); + } + + /** + * Converts a series of items into an Observable. + *

+ * + *

+ * Note: the items will be immediately emitted each time an {@link Observer} + * subscribes. Since this occurs before the {@link Subscription} is + * returned, it is not possible to unsubscribe from the sequence before it + * completes. + * + * @param t1 first item + * @param t2 second item + * @param the type of items, and the type of items to be emitted by the + * resulting Observable + * @return an Observable that emits each item + * @see from() + */ + @SuppressWarnings("unchecked") + // suppress unchecked because we are using varargs inside the method + public static Observable from(T t1, T t2) { + return from(Arrays.asList(t1, t2)); + } + + /** + * Converts a series of items into an Observable. + *

+ * + *

+ * Note: the items will be immediately emitted each time an {@link Observer} + * subscribes. Since this occurs before the {@link Subscription} is + * returned, it is not possible to unsubscribe from the sequence before it + * completes. + * + * @param t1 first item + * @param t2 second item + * @param t3 third item + * @param the type of items, and the type of items to be emitted by the + * resulting Observable + * @return an Observable that emits each item + * @see from() + */ + @SuppressWarnings("unchecked") + // suppress unchecked because we are using varargs inside the method + public static Observable from(T t1, T t2, T t3) { + return from(Arrays.asList(t1, t2, t3)); + } + + /** + * Converts a series of items into an Observable. + *

+ * + *

+ * Note: the items will be immediately emitted each time an {@link Observer} + * subscribes. Since this occurs before the {@link Subscription} is + * returned, it is not possible to unsubscribe from the sequence before it + * completes. + * + * @param t1 first item + * @param t2 second item + * @param t3 third item + * @param t4 fourth item + * @param the type of items, and the type of items to be emitted by the + * resulting Observable + * @return an Observable that emits each item + * @see from() + */ + @SuppressWarnings("unchecked") + // suppress unchecked because we are using varargs inside the method + public static Observable from(T t1, T t2, T t3, T t4) { + return from(Arrays.asList(t1, t2, t3, t4)); + } + + /** + * Converts a series of items into an Observable. + *

+ * + *

+ * Note: the items will be immediately emitted each time an {@link Observer} + * subscribes. Since this occurs before the {@link Subscription} is + * returned, it is not possible to unsubscribe from the sequence before it + * completes. + * + * @param t1 first item + * @param t2 second item + * @param t3 third item + * @param t4 fourth item + * @param t5 fifth item + * @param the type of items, and the type of items to be emitted by the + * resulting Observable + * @return an Observable that emits each item + * @see from() + */ + @SuppressWarnings("unchecked") + // suppress unchecked because we are using varargs inside the method + public static Observable from(T t1, T t2, T t3, T t4, T t5) { + return from(Arrays.asList(t1, t2, t3, t4, t5)); + } + + /** + * Converts a series of items into an Observable. + *

+ * + *

+ * Note: the items will be immediately emitted each time an {@link Observer} + * subscribes. Since this occurs before the {@link Subscription} is + * returned, it is not possible to unsubscribe from the sequence before it + * completes. + * + * @param t1 first item + * @param t2 second item + * @param t3 third item + * @param t4 fourth item + * @param t5 fifth item + * @param t6 sixth item + * @param the type of items, and the type of items to be emitted by the + * resulting Observable + * @return an Observable that emits each item + * @see from() + */ + @SuppressWarnings("unchecked") + // suppress unchecked because we are using varargs inside the method + public static Observable from(T t1, T t2, T t3, T t4, T t5, T t6) { + return from(Arrays.asList(t1, t2, t3, t4, t5, t6)); + } + + /** + * Converts a series of items into an Observable. + *

+ * + *

+ * Note: the items will be immediately emitted each time an {@link Observer} + * subscribes. Since this occurs before the {@link Subscription} is + * returned, it is not possible to unsubscribe from the sequence before it + * completes. + * + * @param t1 first item + * @param t2 second item + * @param t3 third item + * @param t4 fourth item + * @param t5 fifth item + * @param t6 sixth item + * @param t7 seventh item + * @param the type of items, and the type of items to be emitted by the + * resulting Observable + * @return an Observable that emits each item + * @see from() + */ + @SuppressWarnings("unchecked") + // suppress unchecked because we are using varargs inside the method + public static Observable from(T t1, T t2, T t3, T t4, T t5, T t6, T t7) { + return from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7)); + } + + /** + * Converts a series of items into an Observable. + *

+ * + *

+ * Note: the items will be immediately emitted each time an {@link Observer} + * subscribes. Since this occurs before the {@link Subscription} is + * returned, it is not possible to unsubscribe from the sequence before it + * completes. + * + * @param t1 first item + * @param t2 second item + * @param t3 third item + * @param t4 fourth item + * @param t5 fifth item + * @param t6 sixth item + * @param t7 seventh item + * @param t8 eighth item + * @param the type of items, and the type of items to be emitted by the + * resulting Observable + * @return an Observable that emits each item + * @see from() + */ + @SuppressWarnings("unchecked") + // suppress unchecked because we are using varargs inside the method + public static Observable from(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8) { + return from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7, t8)); + } + + /** + * Converts a series of items into an Observable. + *

+ * + *

+ * Note: the items will be immediately emitted each time an {@link Observer} + * subscribes. Since this occurs before the {@link Subscription} is + * returned, it is not possible to unsubscribe from the sequence before it + * completes. + * + * @param t1 first item + * @param t2 second item + * @param t3 third item + * @param t4 fourth item + * @param t5 fifth item + * @param t6 sixth item + * @param t7 seventh item + * @param t8 eighth item + * @param t9 ninth item + * @param the type of items, and the type of items to be emitted by the + * resulting Observable + * @return an Observable that emits each item + * @see from() + */ + @SuppressWarnings("unchecked") + // suppress unchecked because we are using varargs inside the method + public static Observable from(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8, T t9) { + return from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7, t8, t9)); + } + + /** + * Converts a series of items into an Observable. + *

+ * + *

+ * Note: the items will be immediately emitted each time an {@link Observer} + * subscribes. Since this occurs before the {@link Subscription} is + * returned, it is not possible to unsubscribe from the sequence before it + * completes. + * + * @param t1 first item + * @param t2 second item + * @param t3 third item + * @param t4 fourth item + * @param t5 fifth item + * @param t6 sixth item + * @param t7 seventh item + * @param t8 eighth item + * @param t9 ninth item + * @param t10 tenth item + * @param the type of items, and the type of items to be emitted by the + * resulting Observable + * @return an Observable that emits each item + * @see from() + */ + @SuppressWarnings("unchecked") + // suppress unchecked because we are using varargs inside the method + public static Observable from(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8, T t9, T t10) { + return from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10)); + } + + /** + * Generates an Observable that emits a sequence of integers within a + * specified range. + *

+ * + *

+ * Note: the entire range is immediately emitted each time an + * {@link Observer} subscribes. Since this occurs before the + * {@link Subscription} is returned, it is not possible to unsubscribe from + * the sequence before it completes. + * + * @param start the value of the first integer in the sequence + * @param count the number of sequential integers to generate + * @return an Observable that emits a range of sequential integers + * @see range() + * @see Observable.Range Method (Int32, Int32) + */ + public static Observable range(int start, int count) { + return from(Range.createWithCount(start, count)); + } + + /** + * Generates an Observable that emits a sequence of integers within a + * specified range with the specified scheduler. + *

+ * + * @param start the value of the first integer in the sequence + * @param count the number of sequential integers to generate + * @param scheduler the scheduler to run the generator loop on + * @return an Observable that emits a range of sequential integers + * @see range() + * @see Observable.Range Method (Int32, Int32, IScheduler) + */ + public static Observable range(int start, int count, Scheduler scheduler) { + return range(start, count).observeOn(scheduler); + } + + /** + * Returns an Observable that calls an Observable factory to create its + * Observable for each new Observer that subscribes. That is, for each + * subscriber, the actuall Observable is determined by the factory function. + *

+ * + *

+ * The defer operator allows you to defer or delay emitting items from an + * Observable until such time as an Observer subscribes to the Observable. + * This allows an {@link Observer} to easily obtain updates or a refreshed + * version of the sequence. + * + * @param observableFactory the Observable factory function to invoke for + * each {@link Observer} that subscribes to the + * resulting Observable + * @param the type of the items emitted by the Observable + * @return an Observable whose {@link Observer}s trigger an invocation of + * the given Observable factory function + * @see defer() + */ + public static Observable defer(Func0> observableFactory) { + return create(OperationDefer.defer(observableFactory)); + } + + /** + * Returns an Observable that emits a single item and then completes. + *

+ * + *

+ * To convert any object into an Observable that emits that object, pass + * that object into the just method. + *

+ * This is similar to the {@link #from(java.lang.Object[])} method, except + * that from() will convert an {@link Iterable} object into an + * Observable that emits each of the items in the Iterable, one at a time, + * while the just() method converts an Iterable into an + * Observable that emits the entire Iterable as a single item. + * + * @param value the item to pass to the {@link Observer}'s + * {@link Observer#onNext onNext} method + * @param the type of that item + * @return an Observable that emits a single item and then completes + * @see just() + */ + public static Observable just(T value) { + List list = new ArrayList(); + list.add(value); + + return from(list); + } + + /** + * Returns an Observable that emits a single item and then completes on a + * specified scheduler. + *

+ * This is a scheduler version of {@link Observable#just(Object)}. + * + * @param value the item to pass to the {@link Observer}'s + * {@link Observer#onNext onNext} method + * @param the type of that item + * @param scheduler the scheduler to send the single element on + * @return an Observable that emits a single item and then completes on a + * specified scheduler + * @see just() + */ + public static Observable just(T value, Scheduler scheduler) { + return just(value).observeOn(scheduler); + } + + /** + * Flattens a sequence of Observables emitted by an Observable into one + * Observable, without any transformation. + *

+ * + *

+ * You can combine the items emitted by multiple Observables so that they + * act like a single Observable, by using the {@code merge} method. + * + * @param source an Observable that emits Observables + * @return an Observable that emits items that are the result of flattening + * the items emitted by the Observables emitted by the + * {@code source} Observable + * @see merge() + * @see MSDN: Observable.Merge Method + */ + public static Observable merge(Observable> source) { + return create(OperationMerge.merge(source)); + } + + /** + * Flattens a series of Observables into one Observable, without any + * transformation. + *

+ * + *

+ * You can combine items emitted by multiple Observables so that they act + * like a single Observable, by using the {@code merge} method. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see merge() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable merge(Observable t1, Observable t2) { + return create(OperationMerge.merge(t1, t2)); + } + + /** + * Flattens a series of Observables into one Observable, without any + * transformation. + *

+ * + *

+ * You can combine items emitted by multiple Observables so that they act + * like a single Observable, by using the {@code merge} method. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see merge() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable merge(Observable t1, Observable t2, Observable t3) { + return create(OperationMerge.merge(t1, t2, t3)); + } + + /** + * Flattens a series of Observables into one Observable, without any + * transformation. + *

+ * + *

+ * You can combine items emitted by multiple Observables so that they act + * like a single Observable, by using the {@code merge} method. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @param t4 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see merge() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable merge(Observable t1, Observable t2, Observable t3, Observable t4) { + return create(OperationMerge.merge(t1, t2, t3, t4)); + } + + /** + * Flattens a series of Observables into one Observable, without any + * transformation. + *

+ * + *

+ * You can combine items emitted by multiple Observables so that they act + * like a single Observable, by using the {@code merge} method. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @param t4 an Observable to be merged + * @param t5 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see merge() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable merge(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5) { + return create(OperationMerge.merge(t1, t2, t3, t4, t5)); + } + + /** + * Flattens a series of Observables into one Observable, without any + * transformation. + *

+ * + *

+ * You can combine items emitted by multiple Observables so that they act + * like a single Observable, by using the {@code merge} method. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @param t4 an Observable to be merged + * @param t5 an Observable to be merged + * @param t6 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see merge() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable merge(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6) { + return create(OperationMerge.merge(t1, t2, t3, t4, t5, t6)); + } + + /** + * Flattens a series of Observables into one Observable, without any + * transformation. + *

+ * + *

+ * You can combine items emitted by multiple Observables so that they act + * like a single Observable, by using the {@code merge} method. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @param t4 an Observable to be merged + * @param t5 an Observable to be merged + * @param t6 an Observable to be merged + * @param t7 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see merge() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable merge(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7) { + return create(OperationMerge.merge(t1, t2, t3, t4, t5, t6, t7)); + } + + /** + * Flattens a series of Observables into one Observable, without any + * transformation. + *

+ * + *

+ * You can combine items emitted by multiple Observables so that they act + * like a single Observable, by using the {@code merge} method. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @param t4 an Observable to be merged + * @param t5 an Observable to be merged + * @param t6 an Observable to be merged + * @param t7 an Observable to be merged + * @param t8 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see merge() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable merge(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7, Observable t8) { + return create(OperationMerge.merge(t1, t2, t3, t4, t5, t6, t7, t8)); + } + + /** + * Flattens a series of Observables into one Observable, without any + * transformation. + *

+ * + *

+ * You can combine items emitted by multiple Observables so that they act + * like a single Observable, by using the {@code merge} method. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @param t4 an Observable to be merged + * @param t5 an Observable to be merged + * @param t6 an Observable to be merged + * @param t7 an Observable to be merged + * @param t8 an Observable to be merged + * @param t9 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see merge() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable merge(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7, Observable t8, Observable t9) { + return create(OperationMerge.merge(t1, t2, t3, t4, t5, t6, t7, t8, t9)); + } + + /** + * Returns an Observable that emits the items emitted by two or more + * Observables, one after the other. + *

+ * + * + * @param observables an Observable that emits Observables + * @return an Observable that emits items that are the result of combining + * the items emitted by the {@code source} Observables, one after + * the other + * @see concat() + * @see MSDN: Observable.Concat Method + */ + public static Observable concat(Observable> observables) { + return create(OperationConcat.concat(observables)); + } + + /** + * Returns an Observable that emits the items emitted by two Observables, + * one after the other. + *

+ * + * + * @param t1 an Observable to be concatenated + * @param t2 an Observable to be concatenated + * @return an Observable that emits items that are the result of combining + * the items emitted by the {@code source} Observables, one after + * the other + * @see concat() + * @see MSDN: Observable.Concat Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable concat(Observable t1, Observable t2) { + return create(OperationConcat.concat(t1, t2)); + } + + /** + * Returns an Observable that emits the items emitted by three Observables, + * one after the other. + *

+ * + * + * @param t1 an Observable to be concatenated + * @param t2 an Observable to be concatenated + * @param t3 an Observable to be concatenated + * + * @return an Observable that emits items that are the result of combining + * the items emitted by the {@code source} Observables, one after + * the other + * @see concat() + * @see MSDN: Observable.Concat Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable concat(Observable t1, Observable t2, Observable t3) { + return create(OperationConcat.concat(t1, t2, t3)); + } + + /** + * Returns an Observable that emits the items emitted by four Observables, + * one after the other. + *

+ * + * + * @param t1 an Observable to be concatenated + * @param t2 an Observable to be concatenated + * @param t3 an Observable to be concatenated + * @param t4 an Observable to be concatenated + * @return an Observable that emits items that are the result of combining + * the items emitted by the {@code source} Observables, one after + * the other + * @see concat() + * @see MSDN: Observable.Concat Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable concat(Observable t1, Observable t2, Observable t3, Observable t4) { + return create(OperationConcat.concat(t1, t2, t3, t4)); + } + + /** + * Returns an Observable that emits the items emitted by five Observables, + * one after the other. + *

+ * + * + * @param t1 an Observable to be concatenated + * @param t2 an Observable to be concatenated + * @param t3 an Observable to be concatenated + * @param t4 an Observable to be concatenated + * @param t5 an Observable to be concatenated + * @return an Observable that emits items that are the result of combining + * the items emitted by the {@code source} Observables, one after + * the other + * @see concat() + * @see MSDN: Observable.Concat Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable concat(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5) { + return create(OperationConcat.concat(t1, t2, t3, t4, t5)); + } + + /** + * Returns an Observable that emits the items emitted by six Observables, + * one after the other. + *

+ * + * + * @param t1 an Observable to be concatenated + * @param t2 an Observable to be concatenated + * @param t3 an Observable to be concatenated + * @param t4 an Observable to be concatenated + * @param t5 an Observable to be concatenated + * @param t6 an Observable to be concatenated + * @return an Observable that emits items that are the result of combining + * the items emitted by the {@code source} Observables, one after + * the other + * @see concat() + * @see MSDN: Observable.Concat Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable concat(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6) { + return create(OperationConcat.concat(t1, t2, t3, t4, t5, t6)); + } + + /** + * Returns an Observable that emits the items emitted by secven Observables, + * one after the other. + *

+ * + * + * @param t1 an Observable to be concatenated + * @param t2 an Observable to be concatenated + * @param t3 an Observable to be concatenated + * @param t4 an Observable to be concatenated + * @param t5 an Observable to be concatenated + * @param t6 an Observable to be concatenated + * @param t7 an Observable to be concatenated + * @return an Observable that emits items that are the result of combining + * the items emitted by the {@code source} Observables, one after + * the other + * @see concat() + * @see MSDN: Observable.Concat Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable concat(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7) { + return create(OperationConcat.concat(t1, t2, t3, t4, t5, t6, t7)); + } + + /** + * Returns an Observable that emits the items emitted by eight Observables, + * one after the other. + *

+ * + * + * @param t1 an Observable to be concatenated + * @param t2 an Observable to be concatenated + * @param t3 an Observable to be concatenated + * @param t4 an Observable to be concatenated + * @param t5 an Observable to be concatenated + * @param t6 an Observable to be concatenated + * @param t7 an Observable to be concatenated + * @param t8 an Observable to be concatenated + * @return an Observable that emits items that are the result of combining + * the items emitted by the {@code source} Observables, one after + * the other + * @see concat() + * @see MSDN: Observable.Concat Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable concat(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7, Observable t8) { + return create(OperationConcat.concat(t1, t2, t3, t4, t5, t6, t7, t8)); + } + + /** + * Returns an Observable that emits the items emitted by nine Observables, + * one after the other. + *

+ * + * + * @param t1 an Observable to be concatenated + * @param t2 an Observable to be concatenated + * @param t3 an Observable to be concatenated + * @param t4 an Observable to be concatenated + * @param t5 an Observable to be concatenated + * @param t6 an Observable to be concatenated + * @param t7 an Observable to be concatenated + * @param t8 an Observable to be concatenated + * @param t9 an Observable to be concatenated + * @return an Observable that emits items that are the result of combining + * the items emitted by the {@code source} Observables, one after + * the other + * @see concat() + * @see MSDN: Observable.Concat Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable concat(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7, Observable t8, Observable t9) { + return create(OperationConcat.concat(t1, t2, t3, t4, t5, t6, t7, t8, t9)); + } + + /** + * This behaves like {@link #merge(Observable)} except that if any of the + * merged Observables notify of an error via + * {@link Observer#onError onError}, {@code mergeDelayError} will refrain + * from propagating that error notification until all of the merged + * Observables have finished emitting items. + *

+ * + *

+ * Even if multiple merged Observables send {@code onError} notifications, + * {@code mergeDelayError} will only invoke the {@code onError} method of + * its Observers once. + *

+ * This method allows an Observer to receive all successfully emitted items + * from all of the source Observables without being interrupted by an error + * notification from one of them. + * + * @param source an Observable that emits Observables + * @return an Observable that emits items that are the result of flattening + * the items emitted by the Observables emitted by the + * {@code source} Observable + * @see mergeDelayError() + * @see MSDN: Observable.Merge Method + */ + public static Observable mergeDelayError(Observable> source) { + return create(OperationMergeDelayError.mergeDelayError(source)); + } + + /** + * This behaves like {@link #merge(Observable, Observable)} except that if + * any of the merged Observables notify of an error via + * {@link Observer#onError onError}, {@code mergeDelayError} will refrain + * from propagating that error notification until all of the merged + * Observables have finished emitting items. + *

+ * + *

+ * Even if multiple merged Observables send {@code onError} notifications, + * {@code mergeDelayError} will only invoke the {@code onError} method of + * its Observers once. + *

+ * This method allows an Observer to receive all successfully emitted items + * from all of the source Observables without being interrupted by an error + * notification from one of them. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see mergeDelayError() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable mergeDelayError(Observable t1, Observable t2) { + return create(OperationMergeDelayError.mergeDelayError(t1, t2)); + } + + /** + * This behaves like {@link #merge(Observable, Observable, Observable)} + * except that if any of the merged Observables notify of an error via + * {@link Observer#onError onError}, {@code mergeDelayError} will refrain + * from propagating that error notification until all of the merged + * Observables have finished emitting items. + *

+ * + *

+ * Even if multiple merged Observables send {@code onError} notifications, + * {@code mergeDelayError} will only invoke the {@code onError} method of + * its Observers once. + *

+ * This method allows an Observer to receive all successfully emitted items + * from all of the source Observables without being interrupted by an error + * notification from one of them. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see mergeDelayError() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3) { + return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3)); + } + + /** + * This behaves like + * {@link #merge(Observable, Observable, Observable, Observable)} except + * that if any of the merged Observables notify of an error via + * {@link Observer#onError onError}, {@code mergeDelayError} will refrain + * from propagating that error notification until all of the merged + * Observables have finished emitting items. + *

+ * + *

+ * Even if multiple merged Observables send {@code onError} notifications, + * {@code mergeDelayError} will only invoke the {@code onError} method of + * its Observers once. + *

+ * This method allows an Observer to receive all successfully emitted items + * from all of the source Observables without being interrupted by an error + * notification from one of them. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @param t4 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see mergeDelayError() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3, Observable t4) { + return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3, t4)); + } + + /** + * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable)} + * except that if any of the merged Observables notify of an error via + * {@link Observer#onError onError}, {@code mergeDelayError} will refrain + * from propagating that error notification until all of the merged + * Observables have finished emitting items. + *

+ * + *

+ * Even if multiple merged Observables send {@code onError} notifications, + * {@code mergeDelayError} will only invoke the {@code onError} method of + * its Observers once. + *

+ * This method allows an Observer to receive all successfully emitted items + * from all of the source Observables without being interrupted by an error + * notification from one of them. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @param t4 an Observable to be merged + * @param t5 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see mergeDelayError() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5) { + return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3, t4, t5)); + } + + /** + * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable, Observable)} + * except that if any of the merged Observables notify of an error via + * {@link Observer#onError onError}, {@code mergeDelayError} will refrain + * from propagating that error notification until all of the merged + * Observables have finished emitting items. + *

+ * + *

+ * Even if multiple merged Observables send {@code onError} notifications, + * {@code mergeDelayError} will only invoke the {@code onError} method of + * its Observers once. + *

+ * This method allows an Observer to receive all successfully emitted items + * from all of the source Observables without being interrupted by an error + * notification from one of them. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @param t4 an Observable to be merged + * @param t5 an Observable to be merged + * @param t6 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see mergeDelayError() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6) { + return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3, t4, t5, t6)); + } + + /** + * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable, Observable, Observable)} + * except that if any of the merged Observables notify of an error via + * {@link Observer#onError onError}, {@code mergeDelayError} will refrain + * from propagating that error notification until all of the merged + * Observables have finished emitting items. + *

+ * + *

+ * Even if multiple merged Observables send {@code onError} notifications, + * {@code mergeDelayError} will only invoke the {@code onError} method of + * its Observers once. + *

+ * This method allows an Observer to receive all successfully emitted items + * from all of the source Observables without being interrupted by an error + * notification from one of them. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @param t4 an Observable to be merged + * @param t5 an Observable to be merged + * @param t6 an Observable to be merged + * @param t7 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see mergeDelayError() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7) { + return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3, t4, t5, t6, t7)); + } + + /** + * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable, Observable, Observable, Observable)} + * except that if any of the merged Observables notify of an error via + * {@link Observer#onError onError}, {@code mergeDelayError} will refrain + * from propagating that error notification until all of the merged + * Observables have finished emitting items. + *

+ * + *

+ * Even if multiple merged Observables send {@code onError} notifications, + * {@code mergeDelayError} will only invoke the {@code onError} method of + * its Observers once. + *

+ * This method allows an Observer to receive all successfully emitted items + * from all of the source Observables without being interrupted by an error + * notification from one of them. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @param t4 an Observable to be merged + * @param t5 an Observable to be merged + * @param t6 an Observable to be merged + * @param t7 an Observable to be merged + * @param t8 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see mergeDelayError() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7, Observable t8) { + return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3, t4, t5, t6, t7, t8)); + } + + /** + * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable, Observable, Observable, Observable, Observable)} + * except that if any of the merged Observables notify of an error via + * {@link Observer#onError onError}, {@code mergeDelayError} will refrain + * from propagating that error notification until all of the merged + * Observables have finished emitting items. + *

+ * + *

+ * Even if multiple merged Observables send {@code onError} notifications, + * {@code mergeDelayError} will only invoke the {@code onError} method of + * its Observers once. + *

+ * This method allows an Observer to receive all successfully emitted items + * from all of the source Observables without being interrupted by an error + * notification from one of them. + * + * @param t1 an Observable to be merged + * @param t2 an Observable to be merged + * @param t3 an Observable to be merged + * @param t4 an Observable to be merged + * @param t5 an Observable to be merged + * @param t6 an Observable to be merged + * @param t7 an Observable to be merged + * @param t8 an Observable to be merged + * @param t9 an Observable to be merged + * @return an Observable that emits items that are the result of flattening + * the items emitted by the {@code source} Observables + * @see mergeDelayError() + * @see MSDN: Observable.Merge Method + */ + @SuppressWarnings("unchecked") + // suppress because the types are checked by the method signature before using a vararg + public static Observable mergeDelayError(Observable t1, Observable t2, Observable t3, Observable t4, Observable t5, Observable t6, Observable t7, Observable t8, Observable t9) { + return create(OperationMergeDelayError.mergeDelayError(t1, t2, t3, t4, t5, t6, t7, t8, t9)); + } + + /** + * Returns an Observable that never sends any items or notifications to an + * {@link Observer}. + *

+ * + *

+ * This Observable is useful primarily for testing purposes. + * + * @param the type of items (not) emitted by the Observable + * @return an Observable that never sends any items or notifications to an + * {@link Observer} + * @see never() + */ + public static Observable never() { + return new NeverObservable(); + } + + /** + * Given an Observable that emits Observables, creates a single Observable + * that emits the items emitted by the most recently published of those + * Observables. + *

+ * + * + * @param sequenceOfSequences the source Observable that emits Observables + * @return an Observable that emits only the items emitted by the most + * recently published Observable + * @see switchOnNext() + * @deprecated use {@link #switchOnNext} + */ + @Deprecated + public static Observable switchDo(Observable> sequenceOfSequences) { + return create(OperationSwitch.switchDo(sequenceOfSequences)); + } + + /** + * Given an Observable that emits Observables, creates a single Observable + * that emits the items emitted by the most recently published of those + * Observables. + *

+ * + * + * @param sequenceOfSequences the source Observable that emits Observables + * @return an Observable that emits only the items emitted by the most + * recently published Observable + * @see switchOnNext() + */ + public static Observable switchOnNext(Observable> sequenceOfSequences) { + return create(OperationSwitch.switchDo(sequenceOfSequences)); + } + + /** + * Accepts an Observable and wraps it in another Observable that ensures + * that the resulting Observable is chronologically well-behaved. + *

+ * + *

+ * A well-behaved Observable does not interleave its invocations of the + * {@link Observer#onNext onNext}, {@link Observer#onCompleted onCompleted}, + * and {@link Observer#onError onError} methods of its {@link Observer}s; it + * invokes {@code onCompleted} or {@code onError} only once; and it never + * invokes {@code onNext} after invoking either {@code onCompleted} or + * {@code onError}. {@code synchronize} enforces this, and the Observable it + * returns invokes {@code onNext} and {@code onCompleted} or {@code onError} + * synchronously. + * + * @return an Observable that is a chronologically well-behaved version of + * the source Observable, and that synchronously notifies its + * {@link Observer}s + * @see synchronize() + */ + public Observable synchronize() { + return create(OperationSynchronize.synchronize(this)); + } + + /** + * Accepts an Observable and wraps it in another Observable that ensures + * that the resulting Observable is chronologically well-behaved. This is + * accomplished by acquiring a mutual-exclusion lock for the object + * provided as the lock parameter. + *

+ * + *

+ * A well-behaved Observable does not interleave its invocations of the + * {@link Observer#onNext onNext}, {@link Observer#onCompleted onCompleted}, + * and {@link Observer#onError onError} methods of its {@link Observer}s; it + * invokes {@code onCompleted} or {@code onError} only once; and it never + * invokes {@code onNext} after invoking either {@code onCompleted} or + * {@code onError}. {@code synchronize} enforces this, and the Observable it + * returns invokes {@code onNext} and {@code onCompleted} or {@code onError} + * synchronously. + * + * @param lock the lock object to synchronize each observer call on + * @return an Observable that is a chronologically well-behaved version of + * the source Observable, and that synchronously notifies its + * {@link Observer}s + * @see synchronize() + */ + public Observable synchronize(Object lock) { + return create(OperationSynchronize.synchronize(this, lock)); + } + + /** + * @deprecated use {@link #synchronize()} or {@link #synchronize(Object)} + */ + @Deprecated + public static Observable synchronize(Observable source) { + return create(OperationSynchronize.synchronize(source)); + } + + /** + * Emits an item each time interval (containing a sequential number). + *

+ * + * + * @param interval interval size in time units (see below) + * @param unit time units to use for the interval size + * @return an Observable that emits an item each time interval + * @see interval() + * @see MSDN: Observable.Interval + */ + public static Observable interval(long interval, TimeUnit unit) { + return create(OperationInterval.interval(interval, unit)); + } + + /** + * Emits an item each time interval (containing a sequential number). + *

+ * + * + * @param interval interval size in time units (see below) + * @param unit time units to use for the interval size + * @param scheduler the scheduler to use for scheduling the items + * @return an Observable that emits an item each time interval + * @see interval() + * @see MSDN: Observable.Interval + */ + public static Observable interval(long interval, TimeUnit unit, Scheduler scheduler) { + return create(OperationInterval.interval(interval, unit, scheduler)); + } + + /** + * Drops items emitted by an Observable that are followed by newer items + * before a timeout value expires. The timer resets on each emission. + *

+ * Note: If events keep firing faster than the timeout then no data will be + * emitted. + *

+ * + *

+ * Information on debounce vs throttle: + *

+ *

+ * + * @param timeout the time each value has to be "the most recent" of the + * {@link Observable} to ensure that it's not dropped + * @param unit the {@link TimeUnit} for the timeout + * @return an {@link Observable} that filters out items that are too + * quickly followed by newer items + * @see debounce() + * @see #throttleWithTimeout(long, TimeUnit) + */ + public Observable debounce(long timeout, TimeUnit unit) { + return create(OperationDebounce.debounce(this, timeout, unit)); + } + + /** + * Drops items emitted by an Observable that are followed by newer items + * before a timeout value expires. The timer resets on each emission. + *

+ * Note: If events keep firing faster than the timeout then no data will be + * emitted. + *

+ * + *

+ * Information on debounce vs throttle: + *

+ *

+ * + * @param timeout the time each value has to be "the most recent" of the + * {@link Observable} to ensure that it's not dropped + * @param unit the unit of time for the specified timeout + * @param scheduler the {@link Scheduler} to use internally to manage the + * timers that handle the timeout for each event + * @return an {@link Observable} that filters out items that are too + * quickly followed by newer items + * @see debounce() + * @see #throttleWithTimeout(long, TimeUnit, Scheduler) + */ + public Observable debounce(long timeout, TimeUnit unit, Scheduler scheduler) { + return create(OperationDebounce.debounce(this, timeout, unit, scheduler)); + } + + /** + * Drops items emitted by an Observable that are followed by newer items + * before a timeout value expires. The timer resets on each emission. + *

+ * Note: If events keep firing faster than the timeout then no data will be + * emitted. + *

+ * + *

+ * Information on debounce vs throttle: + *

+ *

+ * + * @param timeout the time each value has to be "the most recent" of the + * {@link Observable} to ensure that it's not dropped + * @param unit the {@link TimeUnit} for the timeout + * @return an {@link Observable} that filters out items that are too + * quickly followed by newer items + * @see throttleWithTimeout() + * @see #debounce(long, TimeUnit) + */ + public Observable throttleWithTimeout(long timeout, TimeUnit unit) { + return create(OperationDebounce.debounce(this, timeout, unit)); + } + + /** + * Drops items emitted by an Observable that are followed by newer items + * before a timeout value expires. The timer resets on each emission. + *

+ * Note: If events keep firing faster than the timeout then no data will be + * emitted. + *

+ * + *

+ * Information on debounce vs throttle: + *

+ *

+ * + * @param timeout the time each value has to be "the most recent" of the + * {@link Observable} to ensure that it's not dropped + * @param unit the {@link TimeUnit} for the timeout + * @param scheduler the {@link Scheduler} to use internally to manage the + * timers that handle the timeout for each event + * @return an {@link Observable} that filters out items that are too + * quickly followed by newer items + * @see throttleWithTimeout() + * @see #debounce(long, TimeUnit, Scheduler) + */ + public Observable throttleWithTimeout(long timeout, TimeUnit unit, Scheduler scheduler) { + return create(OperationDebounce.debounce(this, timeout, unit, scheduler)); + } + + /** + * Throttles by skipping items until "skipDuration" passes and then emits + * the next received item. + *

+ * This differs from {@link #throttleLast} in that this only tracks passage + * of time whereas {@link #throttleLast} ticks at scheduled intervals. + *

+ * + * + * @param windowDuration time to wait before sending another item after + * emitting the last item + * @param unit the unit of time for the specified timeout + * @return an Observable that performs the throttle operation + * @see throttleFirst() + */ + public Observable throttleFirst(long windowDuration, TimeUnit unit) { + return create(OperationThrottleFirst.throttleFirst(this, windowDuration, unit)); + } + + /** + * Throttles by skipping items until "skipDuration" passes and then emits + * the next received item. + *

+ * This differs from {@link #throttleLast} in that this only tracks passage + * of time whereas {@link #throttleLast} ticks at scheduled intervals. + *

+ * + * + * @param skipDuration time to wait before sending another item after + * emitting the last item + * @param unit the unit of time for the specified timeout + * @param scheduler the {@link Scheduler} to use internally to manage the + * timers that handle timeout for each event + * @return an Observable that performs the throttle operation + * @see throttleFirst() + */ + public Observable throttleFirst(long skipDuration, TimeUnit unit, Scheduler scheduler) { + return create(OperationThrottleFirst.throttleFirst(this, skipDuration, unit, scheduler)); + } + + /** + * Throttles by emitting the last item in each interval defined by + * intervalDuration. + *

+ * This differs from {@link #throttleFirst} in that this ticks along at a + * scheduled interval whereas {@link #throttleFirst} does not tick, it just + * tracks passage of time. + *

+ * + * + * @param intervalDuration duration of windows within which the last item + * will be emitted + * @param unit the unit of time for the specified interval + * @return an Observable that performs the throttle operation + * @see throttleLast() + * @see #sample(long, TimeUnit) + */ + public Observable throttleLast(long intervalDuration, TimeUnit unit) { + return sample(intervalDuration, unit); + } + + /** + * Throttles by emitting the last item in each interval defined by + * intervalDuration. + *

+ * This differs from {@link #throttleFirst} in that this ticks along at a + * scheduled interval whereas {@link #throttleFirst} does not tick, it just + * tracks passage of time. + *

+ * + * + * @param intervalDuration duration of windows within which the last item + * will be emitted + * @param unit the unit of time for the specified interval + * @return an Observable that performs the throttle operation + * @see throttleLast() + * @see #sample(long, TimeUnit, Scheduler) + */ + public Observable throttleLast(long intervalDuration, TimeUnit unit, Scheduler scheduler) { + return sample(intervalDuration, unit, scheduler); + } + + /** + * Wraps each item emitted by a source Observable in a {@link Timestamped} + * object. + *

+ * + * + * @return an Observable that emits timestamped items from the source + * Observable + * @see timestamp() + */ + public Observable> timestamp() { + return create(OperationTimestamp.timestamp(this)); + } + + /** + * Converts a {@link Future} into an Observable. + *

+ * + *

+ * You can convert any object that supports the {@link Future} interface + * into an Observable that emits the return value of the {@link Future#get} + * method of that object, by passing the object into the {@code from} + * method. + *

+ * Important note: This Observable is blocking; you cannot + * unsubscribe from it. + * + * @param future the source {@link Future} + * @param the type of object that the {@link Future} returns, and also + * the type of item to be emitted by the resulting Observable + * @return an Observable that emits the item from the source Future + * @see from() + */ + public static Observable from(Future future) { + return create(OperationToObservableFuture.toObservableFuture(future)); + } + + /** + * Converts a {@link Future} into an Observable. + *

+ * + *

+ * You can convert any object that supports the {@link Future} interface + * into an Observable that emits the return value of the {@link Future#get} + * method of that object, by passing the object into the {@code from} + * method. + *

+ * + * @param future the source {@link Future} + * @param scheduler the {@link Scheduler} to wait for the Future on. Use a + * Scheduler such as {@link Schedulers#threadPoolForIO()} + * that can block and wait on the future. + * @param the type of object that the {@link Future} returns, and also + * the type of item to be emitted by the resulting Observable + * @return an Observable that emits the item from the source Future + * @see from() + */ + public static Observable from(Future future, Scheduler scheduler) { + return create(OperationToObservableFuture.toObservableFuture(future)).subscribeOn(scheduler); + } + + /** + * Converts a {@link Future} into an Observable with timeout. + *

+ * + *

+ * You can convert any object that supports the {@link Future} interface + * into an Observable that emits the return value of the {link Future#get} + * method of that object, by passing the object into the {@code from} + * method. + *

+ * Important note: This Observable is blocking; you cannot + * unsubscribe from it. + * + * @param future the source {@link Future} + * @param timeout the maximum time to wait before calling get() + * @param unit the {@link TimeUnit} of the timeout argument + * @param the type of object that the {@link Future} returns, and also + * the type of item to be emitted by the resulting Observable + * @return an Observable that emits the item from the source {@link Future} + * @see from() + */ + public static Observable from(Future future, long timeout, TimeUnit unit) { + return create(OperationToObservableFuture.toObservableFuture(future, timeout, unit)); + } + + /** + * Returns an Observable that emits Boolean values that indicate whether the + * pairs of items emitted by two source Observables are equal. + *

+ * + * + * @param first the first Observable to compare + * @param second the second Observable to compare + * @param the type of items emitted by each Observable + * @return an Observable that emits Booleans that indicate whether the + * corresponding items emitted by the source Observables are equal + * @see sequenceEqual() + */ + public static Observable sequenceEqual(Observable first, Observable second) { + return sequenceEqual(first, second, new Func2() { + @Override + public Boolean call(T first, T second) { + return first.equals(second); + } + }); + } + + /** + * Returns an Observable that emits Boolean values that indicate whether the + * pairs of items emitted by two source Observables are equal based on the + * results of a specified equality function. + *

+ * + * + * @param first the first Observable to compare + * @param second the second Observable to compare + * @param equality a function used to compare items emitted by both + * Observables + * @param the type of items emitted by each Observable + * @return an Observable that emits Booleans that indicate whether the + * corresponding items emitted by the source Observables are equal + * @see sequenceEqual() + */ + public static Observable sequenceEqual(Observable first, Observable second, Func2 equality) { + return zip(first, second, equality); + } + + /** + * Returns an Observable that emits the results of a function of your + * choosing applied to combinations of two items emitted, in sequence, by + * two other Observables. + *

+ * + *

+ * {@code zip} applies this function in strict sequence, so the first item + * emitted by the new Observable will be the result of the function applied + * to the first item emitted by {@code o1} and the first item emitted by + * {@code o2}; the second item emitted by the new Observable will be the + * result of the function applied to the second item emitted by {@code o1} + * and the second item emitted by {@code o2}; and so forth. + *

+ * The resulting {@code Observable} returned from {@code zip} will + * invoke {@link Observer#onNext onNext} as many times as the number of + * {@code onNext} invocations of the source Observable that emits the fewest + * items. + * + * @param o1 the first source Observable + * @param o2 another source Observable + * @param zipFunction a function that, when applied to an item emitted by + * each of the source Observables, results in an item that will + * be emitted by the resulting Observable + * @return an Observable that emits the zipped results + * @see zip() + */ + public static Observable zip(Observable o1, Observable o2, Func2 zipFunction) { + return create(OperationZip.zip(o1, o2, zipFunction)); + } + + /** + * Returns an Observable that emits the results of a function of your + * choosing applied to combinations of three items emitted, in sequence, by + * three other Observables. + *

+ * + *

+ * {@code zip} applies this function in strict sequence, so the first item + * emitted by the new Observable will be the result of the function applied + * to the first item emitted by {@code o1}, the first item emitted by + * {@code o2}, and the first item emitted by {@code o3}; the second item + * emitted by the new Observable will be the result of the function applied + * to the second item emitted by {@code o1}, the second item emitted by + * {@code o2}, and the second item emitted by {@code o3}; and so forth. + *

+ * The resulting {@code Observable} returned from {@code zip} will + * invoke {@link Observer#onNext onNext} as many times as the number of + * {@code onNext} invocations of the source Observable that emits the fewest + * items. + * + * @param o1 the first source Observable + * @param o2 a second source Observable + * @param o3 a third source Observable + * @param zipFunction a function that, when applied to an item emitted by + * each of the source Observables, results in an item + * that will be emitted by the resulting Observable + * @return an Observable that emits the zipped results + * @see zip() + */ + public static Observable zip(Observable o1, Observable o2, Observable o3, Func3 zipFunction) { + return create(OperationZip.zip(o1, o2, o3, zipFunction)); + } + + /** + * Returns an Observable that emits the results of a function of your + * choosing applied to combinations of four items emitted, in sequence, by + * four other Observables. + *

+ * + *

+ * {@code zip} applies this function in strict sequence, so the first item + * emitted by the new Observable will be the result of the function applied + * to the first item emitted by {@code o1}, the first item emitted by + * {@code o2}, the first item emitted by {@code o3}, and the first item + * emitted by {@code 04}; the second item emitted by the new Observable will + * be the result of the function applied to the second item emitted by each + * of those Observables; and so forth. + *

+ * The resulting {@code Observable} returned from {@code zip} will + * invoke {@link Observer#onNext onNext} as many times as the number of + * {@code onNext} invocations of the source Observable that emits the fewest + * items. + * + * @param o1 one source Observable + * @param o2 a second source Observable + * @param o3 a third source Observable + * @param o4 a fourth source Observable + * @param zipFunction a function that, when applied to an item emitted by + * each of the source Observables, results in an item that will + * be emitted by the resulting Observable + * @return an Observable that emits the zipped results + * @see zip() + */ + public static Observable zip(Observable o1, Observable o2, Observable o3, Observable o4, Func4 zipFunction) { + return create(OperationZip.zip(o1, o2, o3, o4, zipFunction)); + } + + /** + * Returns an Observable that emits the results of a function of your + * choosing applied to combinations of five items emitted, in sequence, by + * five other Observables. + *

+ * + *

+ * {@code zip} applies this function in strict sequence, so the first item + * emitted by the new Observable will be the result of the function applied + * to the first item emitted by {@code o1}, the first item emitted by + * {@code o2}, the first item emitted by {@code o3}, the first item emitted + * by {@code o4}, and the first item emitted by {@code o5}; the second item + * emitted by the new Observable will be the result of the function applied + * to the second item emitted by each of those Observables; and so forth. + *

+ * The resulting {@code Observable} returned from {@code zip} will + * invoke {@link Observer#onNext onNext} as many times as the number of + * {@code onNext} invocations of the source Observable that emits the fewest + * items. + * + * @param o1 the first source Observable + * @param o2 a second source Observable + * @param o3 a third source Observable + * @param o4 a fourth source Observable + * @param o5 a fifth source Observable + * @param zipFunction a function that, when applied to an item emitted by + * each of the source Observables, results in an item + * that will be emitted by the resulting Observable + * @return an Observable that emits the zipped results + * @see zip() + */ + public static Observable zip(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Func5 zipFunction) { + return create(OperationZip.zip(o1, o2, o3, o4, o5, zipFunction)); + } + + /** + * Returns an Observable that emits the results of a function of your + * choosing applied to combinations of six items emitted, in sequence, by + * six other Observables. + *

+ * + *

+ * {@code zip} applies this function in strict sequence, so the first item + * emitted by the new Observable will be the result of the function applied + * to the first item emitted each source Observable, the second item emitted + * by the new Observable will be the result of the function applied to the + * second item emitted by each of those Observables, and so forth. + *

+ * The resulting {@code Observable} returned from {@code zip} will + * invoke {@link Observer#onNext onNext} as many times as the number of + * {@code onNext} invocations of the source Observable that emits the fewest + * items. + * + * @param o1 the first source Observable + * @param o2 a second source Observable + * @param o3 a third source Observable + * @param o4 a fourth source Observable + * @param o5 a fifth source Observable + * @param o6 a sixth source Observable + * @param zipFunction a function that, when applied to an item emitted by + * each of the source Observables, results in an item + * that will be emitted by the resulting Observable + * @return an Observable that emits the zipped results + * @see zip() + */ + public static Observable zip(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, + Func6 zipFunction) { + return create(OperationZip.zip(o1, o2, o3, o4, o5, o6, zipFunction)); + } + + /** + * Returns an Observable that emits the results of a function of your + * choosing applied to combinations of seven items emitted, in sequence, by + * seven other Observables. + *

+ * + *

+ * {@code zip} applies this function in strict sequence, so the first item + * emitted by the new Observable will be the result of the function applied + * to the first item emitted each source Observable, the second item emitted + * by the new Observable will be the result of the function applied to the + * second item emitted by each of those Observables, and so forth. + *

+ * The resulting {@code Observable} returned from {@code zip} will + * invoke {@link Observer#onNext onNext} as many times as the number of + * {@code onNext} invocations of the source Observable that emits the fewest + * items. + * + * @param o1 the first source Observable + * @param o2 a second source Observable + * @param o3 a third source Observable + * @param o4 a fourth source Observable + * @param o5 a fifth source Observable + * @param o6 a sixth source Observable + * @param o7 a seventh source Observable + * @param zipFunction a function that, when applied to an item emitted by + * each of the source Observables, results in an item + * that will be emitted by the resulting Observable + * @return an Observable that emits the zipped results + * @see zip() + */ + public static Observable zip(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, + Func7 zipFunction) { + return create(OperationZip.zip(o1, o2, o3, o4, o5, o6, o7, zipFunction)); + } + + /** + * Returns an Observable that emits the results of a function of your + * choosing applied to combinations of eight items emitted, in sequence, by + * eight other Observables. + *

+ * + *

+ * {@code zip} applies this function in strict sequence, so the first item + * emitted by the new Observable will be the result of the function applied + * to the first item emitted each source Observable, the second item emitted + * by the new Observable will be the result of the function applied to the + * second item emitted by each of those Observables, and so forth. + *

+ * The resulting {@code Observable} returned from {@code zip} will + * invoke {@link Observer#onNext onNext} as many times as the number of + * {@code onNext} invocations of the source Observable that emits the fewest + * items. + * + * @param o1 the first source Observable + * @param o2 a second source Observable + * @param o3 a third source Observable + * @param o4 a fourth source Observable + * @param o5 a fifth source Observable + * @param o6 a sixth source Observable + * @param o7 a seventh source Observable + * @param o8 an eighth source Observable + * @param zipFunction a function that, when applied to an item emitted by + * each of the source Observables, results in an item + * that will be emitted by the resulting Observable + * @return an Observable that emits the zipped results + * @see zip() + */ + public static Observable zip(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, Observable o8, + Func8 zipFunction) { + return create(OperationZip.zip(o1, o2, o3, o4, o5, o6, o7, o8, zipFunction)); + } + + /** + * Returns an Observable that emits the results of a function of your + * choosing applied to combinations of nine items emitted, in sequence, by + * nine other Observables. + *

+ * + *

+ * {@code zip} applies this function in strict sequence, so the first item + * emitted by the new Observable will be the result of the function applied + * to the first item emitted each source Observable, the second item emitted + * by the new Observable will be the result of the function applied to the + * second item emitted by each of those Observables, and so forth. + *

+ * The resulting {@code Observable} returned from {@code zip} will + * invoke {@link Observer#onNext onNext} as many times as the number of + * {@code onNext} invocations of the source Observable that emits the fewest + * items. + * + * @param o1 the first source Observable + * @param o2 a second source Observable + * @param o3 a third source Observable + * @param o4 a fourth source Observable + * @param o5 a fifth source Observable + * @param o6 a sixth source Observable + * @param o7 a seventh source Observable + * @param o8 an eighth source Observable + * @param o9 a ninth source Observable + * @param zipFunction a function that, when applied to an item emitted by + * each of the source Observables, results in an item + * that will be emitted by the resulting Observable + * @return an Observable that emits the zipped results + * @see zip() + */ + public static Observable zip(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, Observable o8, + Observable o9, Func9 zipFunction) { + return create(OperationZip.zip(o1, o2, o3, o4, o5, o6, o7, o8, o9, zipFunction)); + } + + /** + * Combines the given Observables, emitting an event containing an + * aggregation of the latest values of each of the source observables each + * time an event is received from one of the source observables, where the + * aggregation is defined by the given function. + *

+ * + * + * @param o1 the first source Observable + * @param o2 the second source Observable + * @param combineFunction the aggregation function used to combine the + * source observable values + * @return an Observable that combines the source Observables with the + * given combine function + * @see combineLatest() + */ + public static Observable combineLatest(Observable o1, Observable o2, Func2 combineFunction) { + return create(OperationCombineLatest.combineLatest(o1, o2, combineFunction)); + } + + /** + * Combines the given Observables, emitting an event containing an + * aggregation of the latest values of each of the source observables each + * time an event is received from one of the source observables, where the + * aggregation is defined by the given function. + *

+ * + * + * @param o1 the first source Observable + * @param o2 the second source Observable + * @param o3 the third source Observable + * @param combineFunction the aggregation function used to combine the + * source observable values + * @return an Observable that combines the source Observables with the + * given combine function + * @see combineLatest() + */ + public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Func3 combineFunction) { + return create(OperationCombineLatest.combineLatest(o1, o2, o3, combineFunction)); + } + + /** + * Combines the given Observables, emitting an event containing an + * aggregation of the latest values of each of the source observables each + * time an event is received from one of the source observables, where the + * aggregation is defined by the given function. + *

+ * + * + * @param o1 the first source Observable + * @param o2 the second source Observable + * @param o3 the third source Observable + * @param o4 the fourth source Observable + * @param combineFunction the aggregation function used to combine the + * source observable values + * @return an Observable that combines the source Observables with the + * given combine function + * @see combineLatest() + */ + public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Observable o4, + Func4 combineFunction) { + return create(OperationCombineLatest.combineLatest(o1, o2, o3, o4, combineFunction)); + } + + /** + * Combines the given Observables, emitting an event containing an + * aggregation of the latest values of each of the source observables each + * time an event is received from one of the source observables, where the + * aggregation is defined by the given function. + *

+ * + * + * @param o1 the first source Observable + * @param o2 the second source Observable + * @param o3 the third source Observable + * @param o4 the fourth source Observable + * @param o5 the fifth source Observable + * @param combineFunction the aggregation function used to combine the + * source observable values + * @return an Observable that combines the source Observables with the + * given combine function + * @see combineLatest() + */ + public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, + Func5 combineFunction) { + return create(OperationCombineLatest.combineLatest(o1, o2, o3, o4, o5, combineFunction)); + } + + /** + * Combines the given Observables, emitting an event containing an + * aggregation of the latest values of each of the source observables each + * time an event is received from one of the source observables, where the + * aggregation is defined by the given function. + *

+ * + * + * @param o1 the first source Observable + * @param o2 the second source Observable + * @param o3 the third source Observable + * @param o4 the fourth source Observable + * @param o5 the fifth source Observable + * @param o6 the sixth source Observable + * @param combineFunction the aggregation function used to combine the + * source observable values + * @return an Observable that combines the source Observables with the + * given combine function + * @see combineLatest() + */ + public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, + Func6 combineFunction) { + return create(OperationCombineLatest.combineLatest(o1, o2, o3, o4, o5, o6, combineFunction)); + } + + /** + * Combines the given Observables, emitting an event containing an + * aggregation of the latest values of each of the source observables each + * time an event is received from one of the source observables, where the + * aggregation is defined by the given function. + *

+ * + * + * @param o1 the first source Observable + * @param o2 the second source Observable + * @param o3 the third source Observable + * @param o4 the fourth source Observable + * @param o5 the fifth source Observable + * @param o6 the sixth source Observable + * @param o7 the seventh source Observable + * @param combineFunction the aggregation function used to combine the + * source observable values + * @return an Observable that combines the source Observables with the + * given combine function + * @see combineLatest() + */ + public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, + Func7 combineFunction) { + return create(OperationCombineLatest.combineLatest(o1, o2, o3, o4, o5, o6, o7, combineFunction)); + } + + /** + * Combines the given Observables, emitting an event containing an + * aggregation of the latest values of each of the source observables each + * time an event is received from one of the source observables, where the + * aggregation is defined by the given function. + *

+ * + * + * @param o1 the first source Observable + * @param o2 the second source Observable + * @param o3 the third source Observable + * @param o4 the fourth source Observable + * @param o5 the fifth source Observable + * @param o6 the sixth source Observable + * @param o7 the seventh source Observable + * @param o8 the eighth source Observable + * @param combineFunction the aggregation function used to combine the + * source observable values + * @return an Observable that combines the source Observables with the + * given combine function + * @see combineLatest() + */ + public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, Observable o8, + Func8 combineFunction) { + return create(OperationCombineLatest.combineLatest(o1, o2, o3, o4, o5, o6, o7, o8, combineFunction)); + } + + /** + * Combines the given Observables, emitting an event containing an + * aggregation of the latest values of each of the source observables each + * time an event is received from one of the source observables, where the + * aggregation is defined by the given function. + *

+ * + * + * @param o1 the first source Observable + * @param o2 the second source Observable + * @param o3 the third source Observable + * @param o4 the fourth source Observable + * @param o5 the fifth source Observable + * @param o6 the sixth source Observable + * @param o7 the seventh source Observable + * @param o8 the eighth source Observable + * @param o9 the ninth source Observable + * @param combineFunction the aggregation function used to combine the + * source observable values + * @return an Observable that combines the source Observables with the + * given combine function + * @see combineLatest() + */ + public static Observable combineLatest(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, Observable o8, Observable o9, + Func9 combineFunction) { + return create(OperationCombineLatest.combineLatest(o1, o2, o3, o4, o5, o6, o7, o8, o9, combineFunction)); + } + + /** + * Creates an Observable that produces buffers of collected items. + *

+ * + *

+ * This Observable produces connected, non-overlapping buffers. The current + * buffer is emitted and replaced with a new buffer when the Observable + * produced by the specified bufferClosingSelector produces a + * {@link rx.util.Closing} object. The bufferClosingSelector + * will then be used to create a new Observable to listen for the end of + * the next buffer. + * + * @param bufferClosingSelector the {@link Func0} which is used to produce + * an {@link Observable} for every buffer + * created. When this {@link Observable} + * produces a {@link rx.util.Closing} object, + * the associated buffer is emitted and + * replaced with a new one. + * @return an {@link Observable} which produces connected, non-overlapping + * buffers, which are emitted when the current {@link Observable} + * created with the {@link Func0} argument produces a + * {@link rx.util.Closing} object + * @see buffer() + */ + public Observable> buffer(Func0> bufferClosingSelector) { + return create(OperationBuffer.buffer(this, bufferClosingSelector)); + } + + /** + * Creates an Observable which produces buffers of collected values. + *

+ * + *

+ * This Observable produces buffers. Buffers are created when the specified + * bufferOpenings Observable produces a {@link rx.util.Opening} + * object. Additionally the bufferClosingSelector argument is + * used to create an Observable which produces {@link rx.util.Closing} + * objects. When this Observable produces such an object, the associated + * buffer is emitted. + * + * @param bufferOpenings the {@link Observable} that, when it produces a + * {@link rx.util.Opening} object, will cause another + * buffer to be created + * @param bufferClosingSelector the {@link Func1} that is used to produce + * an {@link Observable} for every buffer + * created. When this {@link Observable} + * produces a {@link rx.util.Closing} object, + * the associated buffer is emitted. + * @return an {@link Observable} that produces buffers that are created and + * emitted when the specified {@link Observable}s publish certain + * objects + * @see buffer() + */ + public Observable> buffer(Observable bufferOpenings, Func1> bufferClosingSelector) { + return create(OperationBuffer.buffer(this, bufferOpenings, bufferClosingSelector)); + } + + /** + * Creates an Observable that produces buffers of collected items. + *

+ * + *

+ * This Observable produces connected, non-overlapping buffers, each + * containing count items. When the source Observable completes + * or encounters an error, the current buffer is emitted, and the event is + * propagated. + * + * @param count the maximum size of each buffer before it should be emitted + * @return an {@link Observable} that produces connected, non-overlapping + * buffers containing at most "count" items + * @see buffer() + */ + public Observable> buffer(int count) { + return create(OperationBuffer.buffer(this, count)); + } + + /** + * Creates an Observable which produces buffers of collected items. + *

+ * + *

+ * This Observable produces buffers every skip items, each + * containing count items. When the source Observable + * completes or encounters an error, the current buffer is emitted, and the + * event is propagated. + * + * @param count the maximum size of each buffer before it should be emitted + * @param skip how many produced items need to be skipped before starting a + * new buffer. Note that when skip and + * count are equal, this is the same operation as + * {@link Observable#buffer(int)}. + * @return an {@link Observable} that produces buffers every + * skip item containing at most count + * items + * @see buffer() + */ + public Observable> buffer(int count, int skip) { + return create(OperationBuffer.buffer(this, count, skip)); + } + + /** + * Creates an Observable that produces buffers of collected values. + *

+ * + *

+ * This Observable produces connected, non-overlapping buffers, each of a + * fixed duration specified by the timespan argument. When the + * source Observable completes or encounters an error, the current buffer is + * emitted and the event is propagated. + * + * @param timespan the period of time each buffer collects values before it + * should be emitted and replaced with a new buffer + * @param unit the unit of time which applies to the timespan + * argument + * @return an {@link Observable} that produces connected, non-overlapping + * buffers with a fixed duration + * @see buffer() + */ + public Observable> buffer(long timespan, TimeUnit unit) { + return create(OperationBuffer.buffer(this, timespan, unit)); + } + + /** + * Creates an Observable that produces buffers of collected values. + *

+ * + *

+ * This Observable produces connected, non-overlapping buffers, each of a + * fixed duration specified by the timespan argument. When the + * source Observable completes or encounters an error, the current buffer is + * emitted and the event is propagated. + * + * @param timespan the period of time each buffer collects values before it + * should be emitted and replaced with a new buffer + * @param unit the unit of time which applies to the timespan + * argument + * @param scheduler the {@link Scheduler} to use when determining the end + * and start of a buffer + * @return an {@link Observable} that produces connected, non-overlapping + * buffers with a fixed duration + * @see buffer() + */ + public Observable> buffer(long timespan, TimeUnit unit, Scheduler scheduler) { + return create(OperationBuffer.buffer(this, timespan, unit, scheduler)); + } + + /** + * Creates an Observable that produces buffers of collected items. This + * Observable produces connected, non-overlapping buffers, each of a fixed + * duration specified by the timespan argument or a maximum + * size specified by the count argument (whichever is reached + * first). When the source Observable completes or encounters an error, the + * current buffer is emitted and the event is propagated. + *

+ * + * + * @param timespan the period of time each buffer collects values before it + * should be emitted and replaced with a new buffer + * @param unit the unit of time which applies to the timespan + * argument + * @param count the maximum size of each buffer before it should be emitted + * @return an {@link Observable} that produces connected, non-overlapping + * buffers that are emitted after a fixed duration or when the + * buffer reaches maximum capacity (whichever occurs first) + * @see buffer() + */ + public Observable> buffer(long timespan, TimeUnit unit, int count) { + return create(OperationBuffer.buffer(this, timespan, unit, count)); + } + + /** + * Creates an Observable that produces buffers of collected items. This + * Observable produces connected, non-overlapping buffers, each of a fixed + * duration specified by the timespan argument or a maximum + * size specified by the count argument (whichever is reached + * first). When the source Observable completes or encounters an error, the + * current buffer is emitted and the event is propagated. + *

+ * + * + * @param timespan the period of time each buffer collects values before it + * should be emitted and replaced with a new buffer + * @param unit the unit of time which applies to the timespan + * argument + * @param count the maximum size of each buffer before it should be emitted + * @param scheduler the {@link Scheduler} to use when determining the end + and start of a buffer + * @return an {@link Observable} that produces connected, non-overlapping + * buffers that are emitted after a fixed duration or when the + * buffer has reached maximum capacity (whichever occurs first) + * @see buffer() + */ + public Observable> buffer(long timespan, TimeUnit unit, int count, Scheduler scheduler) { + return create(OperationBuffer.buffer(this, timespan, unit, count, scheduler)); + } + + /** + * Creates an Observable that produces buffers of collected items. This + * Observable starts a new buffer periodically, as determined by the + * timeshift argument. Each buffer is emitted after a fixed + * timespan, specified by the timespan argument. When the + * source Observable completes or encounters an error, the current buffer is + * emitted and the event is propagated. + *

+ * + * + * @param timespan the period of time each buffer collects values before it + * should be emitted + * @param timeshift the period of time after which a new buffer will be + * created + * @param unit the unit of time that applies to the timespan + * and timeshift arguments + * @return an {@link Observable} that produces new buffers periodically and + * emits these after a fixed timespan has elapsed. + * @see buffer() + */ + public Observable> buffer(long timespan, long timeshift, TimeUnit unit) { + return create(OperationBuffer.buffer(this, timespan, timeshift, unit)); + } + + /** + * Creates an Observable that produces buffers of collected items. This + * Observable starts a new buffer periodically, as determined by the + * timeshift argument. Each buffer is emitted after a fixed + * timespan, specified by the timespan argument. When the + * source Observable completes or encounters an error, the current buffer is + * emitted and the event is propagated. + *

+ * + * + * @param timespan the period of time each buffer collects values before it + * should be emitted + * @param timeshift the period of time after which a new buffer will be + * created + * @param unit the unit of time that applies to the timespan + * and timeshift arguments + * @param scheduler the {@link Scheduler} to use when determining the end + * and start of a buffer + * @return an {@link Observable} that produces new buffers periodically and + * emits these after a fixed timespan has elapsed + * @see buffer() + */ + public Observable> buffer(long timespan, long timeshift, TimeUnit unit, Scheduler scheduler) { + return create(OperationBuffer.buffer(this, timespan, timeshift, unit, scheduler)); + } + + /** + * Creates an Observable that produces windows of collected items. This + * Observable produces connected, non-overlapping windows. The current + * window is emitted and replaced with a new window when the Observable + * produced by the specified closingSelector produces a + * {@link rx.util.Closing} object. The closingSelector will + * then be used to create a new Observable to listen for the end of the next + * window. + *

+ * + * + * @param closingSelector the {@link Func0} used to produce an + * {@link Observable} for every window created. When this + * {@link Observable} emits a {@link rx.util.Closing} object, the + * associated window is emitted and replaced with a new one. + * @return an {@link Observable} that produces connected, non-overlapping + * windows, which are emitted when the current {@link Observable} + * created with the closingSelector argument emits a + * {@link rx.util.Closing} object. + * @see window() + */ + public Observable> window(Func0> closingSelector) { + return create(OperationWindow.window(this, closingSelector)); + } + + /** + * Creates an Observable that produces windows of collected items. This + * Observable produces windows. Chunks are created when the + * windowOpenings Observable produces a {@link rx.util.Opening} + * object. Additionally the closingSelector argument creates an + * Observable that produces {@link rx.util.Closing} objects. When this + * Observable produces such an object, the associated window is emitted. + *

+ * + * + * @param windowOpenings the {@link Observable} that, when it produces a + * {@link rx.util.Opening} object, causes another + * window to be created + * @param closingSelector the {@link Func1} that produces an + * {@link Observable} for every window created. When + * this {@link Observable} produces a + * {@link rx.util.Closing} object, the associated + * window is emitted. + * @return an {@link Observable} that produces windows that are created and + * emitted when the specified {@link Observable}s publish certain + * objects + * @see window() + */ + public Observable> window(Observable windowOpenings, Func1> closingSelector) { + return create(OperationWindow.window(this, windowOpenings, closingSelector)); + } + + /** + * Creates an Observable that produces windows of collected items. This + * Observable produces connected, non-overlapping windows, each containing + * count elements. When the source Observable completes or + * encounters an error, the current window is emitted, and the event is + * propagated. + *

+ * + * + * @param count the maximum size of each window before it should be emitted + * @return an {@link Observable} that produces connected, non-overlapping + * windows containing at most count items + * @see window() + */ + public Observable> window(int count) { + return create(OperationWindow.window(this, count)); + } + + /** + * Creates an Observable that produces windows of collected items. This + * Observable produces windows every skip items, each + * containing count elements. When the source Observable + * completes or encounters an error, the current window is emitted and the + * event is propagated. + *

+ * + * + * @param count the maximum size of each window before it should be emitted + * @param skip how many items need to be skipped before starting a new + * window. Note that if skip and count + * are equal this is the same operation as {@link #window(int)}. + * @return an {@link Observable} that produces windows every "skipped" + * items containing at most count items + * @see window() + */ + public Observable> window(int count, int skip) { + return create(OperationWindow.window(this, count, skip)); + } + + /** + * Creates an Observable that produces windows of collected items. This + * Observable produces connected, non-overlapping windows, each of a fixed + * duration specified by the timespan argument. When the source + * Observable completes or encounters an error, the current window is + * emitted and the event is propagated. + *

+ * + * + * @param timespan the period of time each window collects items before it + * should be emitted and replaced with a new window + * @param unit the unit of time that applies to the timespan + * argument + * @return an {@link Observable} that produces connected, non-overlapping + * windows with a fixed duration + * @see window() + */ + public Observable> window(long timespan, TimeUnit unit) { + return create(OperationWindow.window(this, timespan, unit)); + } + + /** + * Creates an Observable that produces windows of collected items. This + * Observable produces connected, non-overlapping windows, each of a fixed + * duration as specified by the timespan argument. When the + * source Observable completes or encounters an error, the current window is + * emitted and the event is propagated. + *

+ * + * + * @param timespan the period of time each window collects items before it + * should be emitted and replaced with a new window + * @param unit the unit of time which applies to the timespan + * argument + * @param scheduler the {@link Scheduler} to use when determining the end + * and start of a window + * @return an {@link Observable} that produces connected, non-overlapping + * windows with a fixed duration + * @see window() + */ + public Observable> window(long timespan, TimeUnit unit, Scheduler scheduler) { + return create(OperationWindow.window(this, timespan, unit, scheduler)); + } + + /** + * Creates an Observable that produces windows of collected items. This + * Observable produces connected non-overlapping windows, each of a fixed + * duration as specified by the timespan argument or a maximum + * size as specified by the count argument (whichever is + * reached first). When the source Observable completes or encounters an + * error, the current window is emitted and the event is propagated. + *

+ * + * + * @param timespan the period of time each window collects values before it + * should be emitted and replaced with a new window + * @param unit the unit of time that applies to the timespan + * argument + * @param count the maximum size of each window before it should be emitted + * @return an {@link Observable} that produces connected, non-overlapping + * windows that are emitted after a fixed duration or when the + * window has reached maximum capacity (whichever occurs first) + * @see window() + */ + public Observable> window(long timespan, TimeUnit unit, int count) { + return create(OperationWindow.window(this, timespan, unit, count)); + } + + /** + * Creates an Observable that produces windows of collected items. This + * Observable produces connected, non-overlapping windows, each of a fixed + * duration specified by the timespan argument or a maximum + * size specified by the count argument (whichever is reached + * first). When the source Observable completes or encounters an error, the + * current window is emitted and the event is propagated. + *

+ * + * + * @param timespan the period of time each window collects values before it + * should be emitted and replaced with a new window + * @param unit the unit of time which applies to the timespan + * argument + * @param count the maximum size of each window before it should be emitted + * @param scheduler the {@link Scheduler} to use when determining the end + * and start of a window. + * @return an {@link Observable} that produces connected non-overlapping + * windows that are emitted after a fixed duration or when the + * window has reached maximum capacity (whichever occurs first). + * @see window() + */ + public Observable> window(long timespan, TimeUnit unit, int count, Scheduler scheduler) { + return create(OperationWindow.window(this, timespan, unit, count, scheduler)); + } + + /** + * Creates an Observable that produces windows of collected items. This + * Observable starts a new window periodically, as determined by the + * timeshift argument. Each window is emitted after a fixed + * timespan, specified by the timespan argument. When the + * source Observable completes or encounters an error, the current window is + * emitted and the event is propagated. + *

+ * + * + * @param timespan the period of time each window collects values before it + * should be emitted + * @param timeshift the period of time after which a new window will be + * created + * @param unit the unit of time that applies to the timespan + * and timeshift arguments + * @return an {@link Observable} that produces new windows periodically and + * emits these after a fixed timespan has elapsed + * @see window() + */ + public Observable> window(long timespan, long timeshift, TimeUnit unit) { + return create(OperationWindow.window(this, timespan, timeshift, unit)); + } + + /** + * Creates an Observable that produces windows of collected items. This + * Observable starts a new window periodically, as determined by the + * timeshift argument. Each window is emitted after a fixed + * timespan, specified by the timespan argument. When the + * source Observable completes or encounters an error, the current window is + * emitted and the event is propagated. + *

+ * + * + * @param timespan the period of time each window collects values before it + * should be emitted + * @param timeshift the period of time after which a new window will be + * created + * @param unit the unit of time that applies to the timespan + * and timeshift arguments + * @param scheduler the {@link Scheduler} to use when determining the end + * and start of a window + * @return an {@link Observable} that produces new windows periodically and + * emits these after a fixed timespan has elapsed + * @see window() + */ + public Observable> window(long timespan, long timeshift, TimeUnit unit, Scheduler scheduler) { + return create(OperationWindow.window(this, timespan, timeshift, unit, scheduler)); + } + + /** + * Returns an Observable that emits the results of a function of your + * choosing applied to combinations of n items emitted, in sequence, + * by n other Observables as provided by an Iterable. + *

+ * {@code zip} applies this function in strict sequence, so the first item + * emitted by the new Observable will be the result of the function applied + * to the first item emitted by all of the source Observables; the second + * item emitted by the new Observable will be the result of the function + * applied to the second item emitted by each of those Observables; and so + * forth. + *

+ * The resulting {@code Observable} returned from {@code zip} will + * invoke {@code onNext} as many times as the number of {@code onNext} + * invokations of the source Observable that emits the fewest items. + *

+ * + * + * @param ws an Observable of source Observables + * @param zipFunction a function that, when applied to an item emitted by + * each of the source Observables, results in an item + * that will be emitted by the resulting Observable + * @return an Observable that emits the zipped results + * @see zip() + */ + public static Observable zip(Observable> ws, final FuncN zipFunction) { + return ws.toList().mapMany(new Func1>, Observable>() { + @Override + public Observable call(List> wsList) { + return create(OperationZip.zip(wsList, zipFunction)); + } + }); + } + + /** + * Returns an Observable that emits the results of a function of your + * choosing applied to combinations items emitted, in sequence, by a + * collection of other Observables. + *

+ * {@code zip} applies this function in strict sequence, so the first item + * emitted by the new Observable will be the result of the function applied + * to the first item emitted by all of the source Observables; the second + * item emitted by the new Observable will be the result of the function + * applied to the second item emitted by each of those Observables; and so + * forth. + *

+ * The resulting {@code Observable} returned from {@code zip} will invoke + * {@code onNext} as many times as the number of {@code onNext} invokations + * of the source Observable that emits the fewest items. + *

+ * + * + * @param ws a collection of source Observables + * @param zipFunction a function that, when applied to an item emitted by + * each of the source Observables, results in an item + * that will be emitted by the resulting Observable + * @return an Observable that emits the zipped results + * @see zip() + */ + public static Observable zip(Iterable> ws, FuncN zipFunction) { + return create(OperationZip.zip(ws, zipFunction)); + } + + /** + * Filter items emitted by an Observable. + *

+ * + * + * @param predicate a function that evaluates the items emitted by the + * source Observable, returning {@code true} if they pass + * the filter + * @return an Observable that emits only those items in the original + * Observable that the filter evaluates as {@code true} + * @see filter() + */ + public Observable filter(Func1 predicate) { + return create(OperationFilter.filter(this, predicate)); + } + + /** + * Returns an Observable that forwards all sequentially distinct items + * emitted from the source Observable. + *

+ * + * + * @return an Observable of sequentially distinct items + * @see distinctUntilChanged() + * @see MSDN: Observable.distinctUntilChanged + */ + public Observable distinctUntilChanged() { + return create(OperationDistinctUntilChanged.distinctUntilChanged(this)); + } + + /** + * Returns an Observable that forwards all items emitted from the source + * Observable that are sequentially distinct according to a key selector + * function. + *

+ * + * + * @param keySelector a function that projects an emitted item to a key + * value that is used for deciding whether an item is + * sequentially distinct from another one or not + * @return an Observable of sequentially distinct items + * @see distinctUntilChanged() + * @see MSDN: Observable.distinctUntilChanged + */ + public Observable distinctUntilChanged(Func1 keySelector) { + return create(OperationDistinctUntilChanged.distinctUntilChanged(this, keySelector)); + } + + /** + * Returns an Observable that emits all distinct items emitted from the + * source Observable. + *

+ * + * + * @return an Observable of distinct items + * @see distinct() + * @see MSDN: Observable.distinct + */ + public Observable distinct() { + return create(OperationDistinct.distinct(this)); + } + + /** + * Returns an Observable that emits all items emitted from the source + * Observable that are distinct according to a key selector function. + *

+ * + * + * @param keySelector a function that projects an emitted item to a key + * value that is used to decide whether an item is + * distinct from another one or not + * @return an Observable that emits distinct items + * @see distinct() + * @see MSDN: Observable.distinct + */ + public Observable distinct(Func1 keySelector) { + return create(OperationDistinct.distinct(this, keySelector)); + } + + /** + * Returns the item at a specified index in a sequence. + *

+ * + * + * @param index the zero-based index of the item to retrieve + * @return an Observable that emits the item at the specified position in + * the source sequence + * @throws IndexOutOfBoundsException if index is greater than + * or equal to the number of elements in + * the source sequence + * @throws IndexOutOfBoundsException if index is less than 0 + * @see elementAt() + */ + public Observable elementAt(int index) { + return create(OperationElementAt.elementAt(this, index)); + } + + /** + * Returns the item at a specified index in a sequence or the default item + * if the index is out of range. + *

+ * + * + * @param index the zero-based index of the item to retrieve + * @param defaultValue the default item + * @return an Observable that emits the item at the specified position in + * the source sequence, or the default item if the index is outside + * the bounds of the source sequence + * @throws IndexOutOfBoundsException if index is less than 0 + * @see elementAtOrDefault() + */ + public Observable elementAtOrDefault(int index, T defaultValue) { + return create(OperationElementAt.elementAtOrDefault(this, index, defaultValue)); + } + + /** + * Returns an {@link Observable} that emits true if any element + * of the source {@link Observable} satisfies the given condition, otherwise + * false. Note: always emits false if the source + * {@link Observable} is empty. + *

+ * In Rx.Net this is the any operator but renamed in RxJava to + * better match Java naming idioms. + *

+ * + * + * @param predicate the condition to test every element + * @return a subscription function for creating the target Observable + * @see exists() + * @see MSDN: Observable.Any Note: the description in this page is wrong. + */ + public Observable exists(Func1 predicate) { + return create(OperationAny.exists(this, predicate)); + } + + /** + * Determines whether an Observable sequence contains a specified item. + *

+ * + * + * @param element the item to search in the sequence + * @return an Observable that emits true if the item is in the + * source sequence + * @see contains() + * @see MSDN: Observable.Contains + */ + public Observable contains(final T element) { + return exists(new Func1() { + public Boolean call(T t1) { + return element == null ? t1 == null : element.equals(t1); + } + }); + } + + /** + * Registers an {@link Action0} to be called when this Observable invokes + * {@link Observer#onCompleted onCompleted} or + * {@link Observer#onError onError}. + *

+ * + * + * @param action an {@link Action0} to be invoked when the source + * Observable finishes + * @return an Observable that emits the same items as the source Observable, + * then invokes the {@link Action0} + * @see finallyDo() + * @see MSDN: Observable.Finally Method + */ + public Observable finallyDo(Action0 action) { + return create(OperationFinally.finallyDo(this, action)); + } + + /** + * Creates a new Observable by applying a function that you supply to each + * item emitted by the source Observable, where that function returns an + * Observable, and then merging those resulting Observables and emitting the + * results of this merger. + *

+ * + *

+ * Note: {@code mapMany} and {@code flatMap} are equivalent. + * + * @param func a function that, when applied to an item emitted by the + * source Observable, returns an Observable + * @return an Observable that emits the result of applying the + * transformation function to each item emitted by the source + * Observable and merging the results of the Observables obtained + * from this transformation. + * @see flatMap() + * @see #mapMany(Func1) + */ + public Observable flatMap(Func1> func) { + return mapMany(func); + } + + /** + * Filter items emitted by an Observable. + *

+ * + * + * @param predicate a function that evaluates an item emitted by the source + * Observable, returning {@code true} if it passes the + * filter + * @return an Observable that emits only those items emitted by the original + * Observable that the filter evaluates as {@code true} + * @see where() + * @see #filter(Func1) + */ + public Observable where(Func1 predicate) { + return filter(predicate); + } + + /** + * Returns an Observable that applies the given function to each item + * emitted by an Observable and emits the result. + *

+ * + * + * @param func a function to apply to each item emitted by the Observable + * @return an Observable that emits the items from the source Observable, + * transformed by the given function + * @see map() + * @see MSDN: Observable.Select + */ + public Observable map(Func1 func) { + return create(OperationMap.map(this, func)); + } + + /** + * Returns an Observable that applies the given function to each item + * emitted by an Observable and emits the result. + *

+ * + * + * @param func a function to apply to each item emitted by the Observable. + * The function takes the index of the emitted item as + * additional parameter. + * @return an Observable that emits the items from the source Observable, + * transformed by the given function + * @see mapWithIndex() + * @see MSDN: Observable.Select + */ + public Observable mapWithIndex(Func2 func) { + return create(OperationMap.mapWithIndex(this, func)); + } + + /** + * Creates a new Observable by applying a function that you supply to each + * item emitted by the source Observable, where that function returns an + * Observable, and then merging those resulting Observables and emitting + * the results of this merger. + *

+ * + *

+ * Note: mapMany and flatMap are equivalent. + * + * @param func a function that, when applied to an item emitted by the + * source Observable, returns an Observable + * @return an Observable that emits the result of applying the + * transformation function to each item emitted by the source + * Observable and merging the results of the Observables obtained + * from this transformation. + * @see mapMany() + * @see #flatMap(Func1) + */ + public Observable mapMany(Func1> func) { + return create(OperationMap.mapMany(this, func)); + } + + /** + * Turns all of the notifications from a source Observable into + * {@link Observer#onNext onNext} emissions, and marks them with their + * original notification types within {@link Notification} objects. + *

+ * + * + * @return an Observable whose items are the result of materializing the + * items and notifications of the source Observable + * @see materialize() + * @see MSDN: Observable.materialize + */ + public Observable> materialize() { + return create(OperationMaterialize.materialize(this)); + } + + /** + * Asynchronously subscribes and unsubscribes Observers on the specified + * {@link Scheduler}. + *

+ * + * + * @param scheduler the {@link Scheduler} to perform subscription and + * unsubscription actions on + * @return the source Observable modified so that its subscriptions and + * unsubscriptions happen on the specified {@link Scheduler} + * @see subscribeOn() + */ + public Observable subscribeOn(Scheduler scheduler) { + return create(OperationSubscribeOn.subscribeOn(this, scheduler)); + } + + /** + * Asynchronously notify {@link Observer}s on the specified + * {@link Scheduler}. + *

+ * + * + * @param scheduler the {@link Scheduler} to notify {@link Observer}s on + * @return the source Observable modified so that its {@link Observer}s are + * notified on the specified {@link Scheduler} + * @see observeOn() + */ + public Observable observeOn(Scheduler scheduler) { + return create(OperationObserveOn.observeOn(this, scheduler)); + } + + /** + * Returns an Observable that reverses the effect of + * {@link #materialize materialize} by transforming the {@link Notification} + * objects emitted by the source Observable into the items or notifications + * they represent. + *

+ * + * + * @return an Observable that emits the items and notifications embedded in + * the {@link Notification} objects emitted by the source Observable + * @throws Throwable if the source Observable is not of type + * {@code Observable>} + * @see dematerialize() + * @see MSDN: Observable.dematerialize + */ + @SuppressWarnings("unchecked") + public Observable dematerialize() { + return create(OperationDematerialize.dematerialize((Observable>) this)); + } + + /** + * Instruct an Observable to pass control to another Observable rather than + * invoking {@link Observer#onError onError} if it encounters an error. + *

+ * + *

+ * By default, when an Observable encounters an error that prevents it from + * emitting the expected item to its {@link Observer}, the Observable + * invokes its Observer's onError method, and then quits + * without invoking any more of its Observer's methods. The + * onErrorResumeNext method changes this behavior. If you pass + * a function that returns an Observable (resumeFunction) to + * onErrorResumeNext, if the original Observable encounters an + * error, instead of invoking its Observer's onError method, it + * will instead relinquish control to the Observable returned from + * resumeFunction, which will invoke the Observer's + * {@link Observer#onNext onNext} method if it is able to do so. In such a + * case, because no Observable necessarily invokes onError, the + * Observer may never know that an error happened. + *

+ * You can use this to prevent errors from propagating or to supply fallback + * data should errors be encountered. + * + * @param resumeFunction a function that returns an Observable that will + * take over if the source Observable encounters an + * error + * @return the original Observable, with appropriately modified behavior + * @see onErrorResumeNext() + */ + public Observable onErrorResumeNext(final Func1> resumeFunction) { + return create(OperationOnErrorResumeNextViaFunction.onErrorResumeNextViaFunction(this, resumeFunction)); + } + + /** + * Instruct an Observable to pass control to another Observable rather than + * invoking {@link Observer#onError onError} if it encounters an error. + *

+ * + *

+ * By default, when an Observable encounters an error that prevents it from + * emitting the expected item to its {@link Observer}, the Observable + * invokes its Observer's onError method, and then quits + * without invoking any more of its Observer's methods. The + * onErrorResumeNext method changes this behavior. If you pass + * another Observable (resumeSequence) to an Observable's + * onErrorResumeNext method, if the original Observable + * encounters an error, instead of invoking its Observer's + * onError method, it will instead relinquish control to + * resumeSequence which will invoke the Observer's + * {@link Observer#onNext onNext} method if it is able to do so. In such a + * case, because no Observable necessarily invokes onError, the + * Observer may never know that an error happened. + *

+ * You can use this to prevent errors from propagating or to supply fallback + * data should errors be encountered. + * + * @param resumeSequence a function that returns an Observable that will + * take over if the source Observable encounters an + * error + * @return the original Observable, with appropriately modified behavior + * @see onErrorResumeNext() + */ + public Observable onErrorResumeNext(final Observable resumeSequence) { + return create(OperationOnErrorResumeNextViaObservable.onErrorResumeNextViaObservable(this, resumeSequence)); + } + + /** + * Instruct an Observable to pass control to another Observable rather than + * invoking {@link Observer#onError onError} if it encounters an error of + * type {@link java.lang.Exception}. + *

+ * This differs from {@link #onErrorResumeNext} in that this one does not + * handle {@link java.lang.Throwable} or {@link java.lang.Error} but lets + * those continue through. + *

+ * + *

+ * By default, when an Observable encounters an error that prevents it from + * emitting the expected item to its {@link Observer}, the Observable + * invokes its Observer's onError method, and then quits + * without invoking any more of its Observer's methods. The + * onErrorResumeNext method changes this behavior. If you pass + * another Observable (resumeSequence) to an Observable's + * onErrorResumeNext method, if the original Observable + * encounters an error, instead of invoking its Observer's + * onError method, it will instead relinquish control to + * resumeSequence which will invoke the Observer's + * {@link Observer#onNext onNext} method if it is able to do so. In such a + * case, because no Observable necessarily invokes onError, + * the Observer may never know that an error happened. + *

+ * You can use this to prevent errors from propagating or to supply fallback + * data should errors be encountered. + * + * @param resumeSequence a function that returns an Observable that will + * take over if the source Observable encounters an + * error + * @return the original Observable, with appropriately modified behavior + * @see onExceptionResumeNextViaObservable() + */ + public Observable onExceptionResumeNext(final Observable resumeSequence) { + return create(OperationOnExceptionResumeNextViaObservable.onExceptionResumeNextViaObservable(this, resumeSequence)); + } + + /** + * Instruct an Observable to emit an item (returned by a specified function) + * rather than invoking {@link Observer#onError onError} if it encounters an + * error. + *

+ * + *

+ * By default, when an Observable encounters an error that prevents it from + * emitting the expected item to its {@link Observer}, the Observable + * invokes its Observer's onError method, and then quits + * without invoking any more of its Observer's methods. The + * onErrorReturn method changes this behavior. If you pass a + * function (resumeFunction) to an Observable's + * onErrorReturn method, if the original Observable encounters + * an error, instead of invoking its Observer's onError method, + * it will instead pass the return value of resumeFunction to + * the Observer's {@link Observer#onNext onNext} method. + *

+ * You can use this to prevent errors from propagating or to supply fallback + * data should errors be encountered. + * + * @param resumeFunction a function that returns an item that the new + * Observable will emit if the source Observable + * encounters an error + * @return the original Observable with appropriately modified behavior + * @see onErrorReturn() + */ + public Observable onErrorReturn(Func1 resumeFunction) { + return create(OperationOnErrorReturn.onErrorReturn(this, resumeFunction)); + } + + /** + * Returns an Observable that applies a function of your choosing to the + * first item emitted by a source Observable, then feeds the result of that + * function along with the second item emitted by the source Observable into + * the same function, and so on until all items have been emitted by the + * source Observable, and emits the final result from the final call to your + * function as its sole item. + *

+ * + *

+ * This technique, which is called "reduce" or "aggregate" here, is + * sometimes called "fold," "accumulate," "compress," or "inject" in other + * programming contexts. Groovy, for instance, has an inject + * method that does a similar operation on lists. + * + * @param accumulator an accumulator function to be invoked on each item + * emitted by the source Observable, whose result will + * be used in the next accumulator call + * @return an Observable that emits a single item that is the result of + * accumulating the output from the source Observable + * @throws IllegalArgumentException if the Observable sequence is empty + * @see reduce() + * @see MSDN: Observable.Aggregate + * @see Wikipedia: Fold (higher-order function) + */ + public Observable reduce(Func2 accumulator) { + /* + * Discussion and confirmation of implementation at https://github.com/Netflix/RxJava/issues/423#issuecomment-27642532 + * + * It should use last() not takeLast(1) since it needs to emit an error if the sequence is empty. + */ + return create(OperationScan.scan(this, accumulator)).last(); + } + + /** + * Returns an Observable that counts the total number of items in the + * source Observable. + *

+ * + * + * @return an Observable that emits the number of counted elements of the + * source Observable as its single item + * @see count() + * @see MSDN: Observable.Count + */ + public Observable count() { + return reduce(0, new Func2() { + @Override + public Integer call(Integer t1, T t2) { + return t1 + 1; + } + }); + } + + /** + * Returns an Observable that sums up the integers emitted by the source + * Observable. + *

+ * + * + * @param source source Observable to compute the sum of + * @return an Observable that emits the sum of all the items of the + * source Observable as its single item + * @see sum() + * @see MSDN: Observable.Sum + */ + public static Observable sum(Observable source) { + return OperationSum.sum(source); + } + + /** + * Returns an Observable that sums up the longs emitted by the source + * Observable. + *

+ * + * + * @param source source Observable to compute the sum of + * @return an Observable that emits the sum of all the items of the + * source Observable as its single item + * @see sumLongs() + * @see MSDN: Observable.Sum + */ + public static Observable sumLongs(Observable source) { + return OperationSum.sumLongs(source); + } + + /** + * Returns an Observable that sums up the floats emitted by the source + * Observable. + *

+ * + * + * @param source source Observable to compute the sum of + * @return an Observable that emits the sum of all the items of the + * source Observable as its single item + * @see sumFloats() + * @see MSDN: Observable.Sum + */ + public static Observable sumFloats(Observable source) { + return OperationSum.sumFloats(source); + } + + /** + * Returns an Observable that sums up the doubles emitted by the source + * Observable. + *

+ * + * + * @param source source Observable to compute the sum of + * @return an Observable that emits the sum of all the items of the + * source Observable as its single item + * @see sumDoubles() + * @see MSDN: Observable.Sum + */ + public static Observable sumDoubles(Observable source) { + return OperationSum.sumDoubles(source); + } + + /** + * Returns an Observable that computes the average of the integers emitted + * by the source Observable. + *

+ * + * + * @param source source observable to compute the average of + * @return an Observable that emits the average of all the items emitted by + * the source Observable as its single item + * @throws IllegalArgumentException if the Observable sequence is empty + * @see average() + * @see MSDN: Observable.Average + */ + public static Observable average(Observable source) { + return OperationAverage.average(source); + } + + /** + * Returns an Observable that computes the average of the longs emitted by + * the source Observable. + *

+ * + * + * @param source source observable to compute the average of + * @return an Observable that emits the average of all the items emitted by + * the source Observable as its single item + * @see averageLongs() + * @see MSDN: Observable.Average + */ + public static Observable averageLongs(Observable source) { + return OperationAverage.averageLongs(source); + } + + /** + * Returns an Observable that computes the average of the floats emitted by + * the source Observable. + *

+ * + * + * @param source source observable to compute the average of + * @return an Observable that emits the average of all the items emitted by + * the source Observable as its single item + * @see averageFloats() + * @see MSDN: Observable.Average + */ + public static Observable averageFloats(Observable source) { + return OperationAverage.averageFloats(source); + } + + /** + * Returns an Observable that computes the average of the doubles emitted + * by the source Observable. + *

+ * + * + * @param source source observable to compute the average of + * @return an Observable that emits the average of all the items emitted by + * the source Observable as its single item + * @see averageDoubles() + * @see MSDN: Observable.Average + */ + public static Observable averageDoubles(Observable source) { + return OperationAverage.averageDoubles(source); + } + + /** + * Returns the minimum item emitted by an Observable. If there are more than + * one minimum items, its returns the last one. + *

+ * + * + * @param source an Observable sequence to determine the minimum item of + * @return an Observable that emits the minimum item + * @throws IllegalArgumentException if the source is empty + * @see MSDN: Observable.Min + */ + public static > Observable min(Observable source) { + return OperationMinMax.min(source); + } + + /** + * Returns the minimum item emitted by an Observable according to a + * specified comparator. If there are more than one minimum items, it + * returns the last one. + *

+ * + * + * @param comparator the comparer used to compare elements + * @return an Observable that emits the minimum value according to the + * specified comparator + * @throws IllegalArgumentException if the source is empty + * @see min() + * @see MSDN: Observable.Min + */ + public Observable min(Comparator comparator) { + return OperationMinMax.min(this, comparator); + } + + /** + * Returns the items emitted by an Observable sequence with the minimum key + * value. For an empty source, returns an Observable that emits an empty + * List. + *

+ * + * + * @param selector the key selector function + * @return an Observable that emits a List of the items with the minimum key + * value + * @see minBy() + * @see MSDN: Observable.MinBy + */ + public > Observable> minBy(Func1 selector) { + return OperationMinMax.minBy(this, selector); + } + + /** + * Returns the elements emitted by an Observable with the minimum key value + * according to the specified comparator. For an empty source, it returns an + * Observable that emits an empty List. + *

+ * + * + * @param selector the key selector function + * @param comparator the comparator used to compare key values + * @return an Observable that emits a List of the elements with the minimum + * key value according to the specified comparator + * @see minBy() + * @see MSDN: Observable.MinBy + */ + public Observable> minBy(Func1 selector, Comparator comparator) { + return OperationMinMax.minBy(this, selector, comparator); + } + + /** + * Returns the maximum item emitted by an Observable. If there is more + * than one maximum item, it returns the last one. + *

+ * + * + * @param source an Observable to determine the maximum item of + * @return an Observable that emits the maximum element + * @throws IllegalArgumentException if the source is empty + * @see max() + * @see MSDN: Observable.Max + */ + public static > Observable max(Observable source) { + return OperationMinMax.max(source); + } + + /** + * Returns the maximum item emitted by an Observable according to the + * specified comparator. If there is more than one maximum item, it returns + * the last one. + *

+ * + * + * @param comparator the comparer used to compare items + * @return an Observable that emits the maximum item according to the + * specified comparator + * @throws IllegalArgumentException if the source is empty + * @see max() + * @see MSDN: Observable.Max + */ + public Observable max(Comparator comparator) { + return OperationMinMax.max(this, comparator); + } + + /** + * Returns the items emitted by an Observable with the maximum key value. + * For an empty source, it returns an Observable that emits an empty List. + *

+ * + * + * @param selector the key selector function + * @return an Observable that emits a List of the items with the maximum key + * value + * @see maxBy() + * @see MSDN: Observable.MaxBy + */ + public > Observable> maxBy(Func1 selector) { + return OperationMinMax.maxBy(this, selector); + } + + /** + * Returns the items emitted by an Observable with the maximum key value + * according to the specified comparator. For an empty source, it returns an + * Observable that emits an empty List. + *

+ * + * + * @param selector the key selector function + * @param comparator the comparator used to compare key values + * @return an Observable that emits a List of the elements with the maximum + * key value according to the specified comparator + * @see maxBy() + * @see MSDN: Observable.MaxBy + */ + public Observable> maxBy(Func1 selector, Comparator comparator) { + return OperationMinMax.maxBy(this, selector, comparator); + } + + /** + * Returns a {@link ConnectableObservable} that shares a single subscription + * to the underlying Observable that will replay all of its items and + * notifications to any future {@link Observer}. + *

+ * + * + * @return a {@link ConnectableObservable} that upon connection causes the + * source Observable to emit items to its {@link Observer}s + * @see replay() + */ + public ConnectableObservable replay() { + return OperationMulticast.multicast(this, ReplaySubject. create()); + } + + /** + * Retry subscription to origin Observable upto given retry count. + *

+ * + *

+ * If {@link Observer#onError} is invoked the source Observable will be + * re-subscribed to as many times as defined by retryCount. + *

+ * Any {@link Observer#onNext} calls received on each attempt will be + * emitted and concatenated together. + *

+ * For example, if an Observable fails on first time but emits [1, 2] then + * succeeds the second time and emits [1, 2, 3, 4, 5] then the complete + * output would be [1, 2, 1, 2, 3, 4, 5, onCompleted]. + * + * @param retryCount number of retry attempts before failing + * @return an Observable with retry logic + * @see retry() + */ + public Observable retry(int retryCount) { + return create(OperationRetry.retry(this, retryCount)); + } + + /** + * Retry subscription to origin Observable whenever onError is + * called (infinite retry count). + *

+ * + *

+ * If {@link Observer#onError} is invoked the source Observable will be + * re-subscribed to. + *

+ * Any {@link Observer#onNext} calls received on each attempt will be + * emitted and concatenated together. + *

+ * For example, if an Observable fails on first time but emits [1, 2] then + * succeeds the second time and emits [1, 2, 3, 4, 5] then the complete + * output would be [1, 2, 1, 2, 3, 4, 5, onCompleted]. + * + * @return an Observable with retry logic + * @see retry() + */ + public Observable retry() { + return create(OperationRetry.retry(this)); + } + + /** + * This method has similar behavior to {@link #replay} except that this + * auto-subscribes to the source Observable rather than returning a + * {@link ConnectableObservable}. + *

+ * + *

+ * This is useful when you want an Observable to cache responses and you + * can't control the subscribe/unsubscribe behavior of all the + * {@link Observer}s. + *

+ * Note: You sacrifice the ability to unsubscribe from the origin when you + * use the cache() operator so be careful not to use this + * operator on Observables that emit an infinite or very large number of + * items that will use up memory. + * + * @return an Observable that, when first subscribed to, caches all of its + * notifications for the benefit of subsequent subscribers. + * @see cache() + */ + public Observable cache() { + return create(OperationCache.cache(this)); + } + + /** + * Perform work in parallel by sharding an {@code Observable} on a + * {@link Schedulers#threadPoolForComputation()} {@link Scheduler} and + * return an {@code Observable} with the output. + *

+ * + * + * @param f a {@link Func1} that applies Observable operators to + * {@code Observable} in parallel and returns an + * {@code Observable} + * @return an Observable with the output of the {@link Func1} executed on a + * {@link Scheduler} + * @see parallel() + */ + public Observable parallel(Func1, Observable> f) { + return OperationParallel.parallel(this, f); + } + + /** + * Perform work in parallel by sharding an {@code Observable} on a + * {@link Scheduler} and return an {@code Observable} with the output. + *

+ * + * + * @param f a {@link Func1} that applies Observable operators to + * {@code Observable} in parallel and returns an + * {@code Observable} + * @param s a {@link Scheduler} to perform the work on + * @return an Observable with the output of the {@link Func1} executed on a + * {@link Scheduler} + * @see parallel() + */ + + public Observable parallel(final Func1, Observable> f, final Scheduler s) { + return OperationParallel.parallel(this, f, s); + } + + + /** + * Merges an Observable<Observable<T>> to + * Observable<Observable<T>> with the number of + * inner Observables defined by parallelObservables. + *

+ * For example, if the original + * Observable<Observable<T>> has 100 Observables to + * be emitted and parallelObservables is 8, the 100 will be + * grouped onto 8 output Observables. + *

+ * This is a mechanism for efficiently processing n number of + * Observables on a smaller m number of resources (typically CPU + * cores). + *

+ * + * + * @param parallelObservables the number of Observables to merge into + * @return an Observable of Observables constrained to number defined by + * parallelObservables + * @see parallelMerge() + */ + public static Observable> parallelMerge(Observable> source, int parallelObservables) { + return OperationParallelMerge.parallelMerge(source, parallelObservables); + } + + /** + * Merges an Observable<Observable<T>> to + * Observable<Observable<T>> with the number of + * inner Observables defined by parallelObservables and runs + * each Observable on the defined Scheduler. + *

+ * For example, if the original + * Observable<Observable<T>> has 100 Observables to + * be emitted and parallelObservables is 8, the 100 will be + * grouped onto 8 output Observables. + *

+ * This is a mechanism for efficiently processing n number of + * Observables on a smaller m number of resources (typically CPU + * cores). + *

+ * + * + * @param parallelObservables the number of Observables to merge into + * @return an Observable of Observables constrained to number defined by + * parallelObservables. + * @see parallelMerge() + */ + public static Observable> parallelMerge(Observable> source, int parallelObservables, Scheduler scheduler) { + return OperationParallelMerge.parallelMerge(source, parallelObservables, scheduler); + } + + /** + * Returns a {@link ConnectableObservable}, which waits until its + * {@link ConnectableObservable#connect connect} method is called before it + * begins emitting items to those {@link Observer}s that have subscribed to + * it. + *

+ * + * + * @return a {@link ConnectableObservable} that upon connection causes the + * source Observable to emit items to its {@link Observer}s + * @see publish() + */ + public ConnectableObservable publish() { + return OperationMulticast.multicast(this, PublishSubject. create()); + } + + /** + * Returns a {@link ConnectableObservable} that shares a single subscription + * that contains the last notification only. + *

+ * + * + * @return a {@link ConnectableObservable} + * @see publishLast() + */ + public ConnectableObservable publishLast() { + return OperationMulticast.multicast(this, AsyncSubject. create()); + } + + /** + * Synonymous with reduce(). + *

+ * + * + * @see aggregate() + * @see #reduce(Func2) + */ + public Observable aggregate(Func2 accumulator) { + return reduce(accumulator); + } + + /** + * Returns an Observable that applies a function of your choosing to the + * first item emitted by a source Observable, then feeds the result of that + * function along with the second item emitted by an Observable into the + * same function, and so on until all items have been emitted by the source + * Observable, emitting the final result from the final call to your + * function as its sole item. + *

+ * + *

+ * This technique, which is called "reduce" or "aggregate" here, is + * sometimes called "fold," "accumulate," "compress," or "inject" in other + * programming contexts. Groovy, for instance, has an inject + * method that does a similar operation on lists. + * + * @param initialValue the initial (seed) accumulator value + * @param accumulator an accumulator function to be invoked on each item + * emitted by the source Observable, the result of which + * will be used in the next accumulator call + * @return an Observable that emits a single item that is the result of + * accumulating the output from the items emitted by the source + * Observable + * @see reduce() + * @see MSDN: Observable.Aggregate + * @see Wikipedia: Fold (higher-order function) + */ + public Observable reduce(R initialValue, Func2 accumulator) { + return create(OperationScan.scan(this, initialValue, accumulator)).takeLast(1); + } + + /** + * Synonymous with reduce(). + *

+ * + * + * @see aggregate() + * @see #reduce(Object, Func2) + */ + public Observable aggregate(R initialValue, Func2 accumulator) { + return reduce(initialValue, accumulator); + } + + /** + * Returns an Observable that applies a function of your choosing to the + * first item emitted by a source Observable, then feeds the result of that + * function along with the second item emitted by an Observable into the + * same function, and so on until all items have been emitted by the source + * Observable, emitting the result of each of these iterations. + *

+ * + *

+ * This sort of function is sometimes called an accumulator. + *

+ * Note that when you pass a seed to scan() the resulting + * Observable will emit that seed as its first emitted item. + * + * @param accumulator an accumulator function to be invoked on each item + * emitted by the source Observable, whose result will be + * emitted to {@link Observer}s via + * {@link Observer#onNext onNext} and used in the next + * accumulator call + * @return an Observable that emits the results of each call to the + * accumulator function + * @see scan() + * @see MSDN: Observable.Scan + */ + public Observable scan(Func2 accumulator) { + return create(OperationScan.scan(this, accumulator)); + } + + /** + * Returns an Observable that emits the results of sampling the items + * emitted by the source Observable at a specified time interval. + *

+ * + * + * @param period the sampling rate + * @param unit the {@link TimeUnit} in which period is defined + * @return an Observable that emits the results of sampling the items + * emitted by the source Observable at the specified time interval + * @see sample() + */ + public Observable sample(long period, TimeUnit unit) { + return create(OperationSample.sample(this, period, unit)); + } + + /** + * Returns an Observable that emits the results of sampling the items + * emitted by the source Observable at a specified time interval. + *

+ * + * + * @param period the sampling rate + * @param unit the {@link TimeUnit} in which period is defined + * @param scheduler the {@link Scheduler} to use when sampling + * @return an Observable that emits the results of sampling the items + * emitted by the source Observable at the specified time interval + * @see sample() + */ + public Observable sample(long period, TimeUnit unit, Scheduler scheduler) { + return create(OperationSample.sample(this, period, unit, scheduler)); + } + + /** + * Returns an Observable that applies a function of your choosing to the + * first item emitted by a source Observable, then feeds the result of that + * function along with the second item emitted by an Observable into the + * same function, and so on until all items have been emitted by the source + * Observable, emitting the result of each of these iterations. + *

+ * + *

+ * This sort of function is sometimes called an accumulator. + *

+ * Note that when you pass a seed to scan() the resulting + * Observable will emit that seed as its first emitted item. + * + * @param initialValue the initial (seed) accumulator value + * @param accumulator an accumulator function to be invoked on each item + * emitted by the source Observable, whose result will be + * emitted to {@link Observer}s via + * {@link Observer#onNext onNext} and used in the next + * accumulator call + * @return an Observable that emits the results of each call to the + * accumulator function + * @see scan() + * @see MSDN: Observable.Scan + */ + public Observable scan(R initialValue, Func2 accumulator) { + return create(OperationScan.scan(this, initialValue, accumulator)); + } + + /** + * Returns an Observable that emits a Boolean that indicates whether all of + * the items emitted by the source Observable satisfy a condition. + *

+ * + * + * @param predicate a function that evaluates an item and returns a Boolean + * @return an Observable that emits true if all items emitted + * by the source Observable satisfy the predicate; otherwise, + * false + * @see all() + */ + public Observable all(Func1 predicate) { + return create(OperationAll.all(this, predicate)); + } + + /** + * Returns an Observable that skips the first num items emitted + * by the source Observable and emits the remainder. + *

+ * + *

+ * You can ignore the first num items emitted by an Observable + * and attend only to those items that come after, by modifying the + * Observable with the skip method. + * + * @param num the number of items to skip + * @return an Observable that is identical to the source Observable except + * that it does not emit the first num items that the + * source emits + * @see skip() + */ + public Observable skip(int num) { + return create(OperationSkip.skip(this, num)); + } + + /** + * Returns an Observable that emits only the very first item emitted by the + * source Observable. + *

+ * + * + * @return an Observable that emits only the very first item from the + * source, or none if the source Observable completes without + * emitting a single item + * @see first() + * @see MSDN: Observable.First + */ + public Observable first() { + return take(1); + } + + /** + * Returns an Observable that emits only the very first item emitted by the + * source Observable that satisfies a given condition. + *

+ * + * + * @param predicate the condition any source emitted item has to satisfy + * @return an Observable that emits only the very first item satisfying the + * given condition from the source, or none if the source Observable + * completes without emitting a single matching item + * @see first() + * @see MSDN: Observable.First + */ + public Observable first(Func1 predicate) { + return skipWhile(not(predicate)).take(1); + } + + /** + * Returns an Observable that emits only the very first item emitted by the + * source Observable, or a default value. + *

+ * + * + * @param defaultValue the default value to emit if the source Observable + * doesn't emit anything + * @return an Observable that emits only the very first item from the + * source, or a default value if the source Observable completes + * without emitting a single item + * @see firstOrDefault() + * @see MSDN: Observable.FirstOrDefault + */ + public Observable firstOrDefault(T defaultValue) { + return create(OperationFirstOrDefault.firstOrDefault(this, defaultValue)); + } + + /** + * Returns an Observable that emits only the very first item emitted by the + * source Observable that satisfies a given condition, or a default value + * otherwise. + *

+ * + * + * @param predicate the condition any source emitted item has to satisfy + * @param defaultValue the default value to emit if the source Observable + * doesn't emit anything that satisfies the given condition + * @return an Observable that emits only the very first item from the source + * that satisfies the given condition, or a default value otherwise + * @see firstOrDefault() + * @see MSDN: Observable.FirstOrDefault + */ + public Observable firstOrDefault(Func1 predicate, T defaultValue) { + return create(OperationFirstOrDefault.firstOrDefault(this, predicate, defaultValue)); + } + + /** + * Returns the elements of the specified sequence or the specified default + * value in a singleton sequence if the sequence is empty. + *

+ * + * + * @param defaultValue the value to return if the sequence is empty + * @return an Observable that emits the specified default value if the + * source is empty; otherwise, the items emitted by the source + * @see defaultIfEmpty() + * @see MSDN: Observable.DefaultIfEmpty + */ + public Observable defaultIfEmpty(T defaultValue) { + return create(OperationDefaultIfEmpty.defaultIfEmpty(this, defaultValue)); + } + + /** + * Returns an Observable that emits only the first num items + * emitted by the source Observable. + *

+ * + *

+ * This method returns an Observable that will invoke a subscribing + * {@link Observer}'s {@link Observer#onNext onNext} function a maximum of + * num times before invoking + * {@link Observer#onCompleted onCompleted}. + * + * @param num the number of items to emit + * @return an Observable that emits only the first num items + * from the source Observable, or all of the items from the source + * Observable if that Observable emits fewer than num + * items + * @see take() + */ + public Observable take(final int num) { + return create(OperationTake.take(this, num)); + } + + /** + * Returns an Observable that emits items emitted by the source Observable + * so long as a specified condition is true. + *

+ * + * + * @param predicate a function that evaluates an item emitted by the source + * Observable and returns a Boolean + * @return an Observable that emits the items from the source Observable so + * long as each item satisfies the condition defined by + * predicate + * @see takeWhile() + */ + public Observable takeWhile(final Func1 predicate) { + return create(OperationTakeWhile.takeWhile(this, predicate)); + } + + /** + * Returns an Observable that emits the items emitted by a source Observable + * so long as a given predicate remains true, where the predicate can + * operate on both the item and its index relative to the complete sequence. + *

+ * + * + * @param predicate a function to test each item emitted by the source + * Observable for a condition; the second parameter of the + * function represents the index of the source item + * @return an Observable that emits items from the source Observable so long + * as the predicate continues to return true for each + * item, then completes + * @see takeWhileWithIndex() + */ + public Observable takeWhileWithIndex(final Func2 predicate) { + return create(OperationTakeWhile.takeWhileWithIndex(this, predicate)); + } + + /** + * Returns an Observable that emits only the very first item emitted by the + * source Observable. + *

+ * + * + * @return an Observable that emits only the very first item from the + * source, or none if the source Observable completes without + * emitting a single item + * @see first() + * @see MSDN: Observable.First + * @see #first() + */ + public Observable takeFirst() { + return first(); + } + + /** + * Returns an Observable that emits only the very first item emitted by the + * source Observable that satisfies a given condition. + *

+ * + * + * @param predicate the condition any source emitted item has to satisfy + * @return an Observable that emits only the very first item satisfying the + * given condition from the source, or none if the source Observable + * completes without emitting a single matching item + * @see first() + * @see MSDN: Observable.First + * @see #first(Func1) + */ + public Observable takeFirst(Func1 predicate) { + return first(predicate); + } + + /** + * Returns an Observable that emits only the last count items + * emitted by the source Observable. + *

+ * + * + * @param count the number of items to emit from the end of the sequence + * emitted by the source Observable + * @return an Observable that emits only the last count items + * emitted by the source Observable + * @see takeLast() + */ + public Observable takeLast(final int count) { + return create(OperationTakeLast.takeLast(this, count)); + } + + /** + * Returns an Observable that emits the items from the source Observable + * only until the other Observable emits an item. + *

+ * + * + * @param other the Observable whose first emitted item will cause + * takeUntil to stop emitting items from the + * source Observable + * @param the type of items emitted by other + * @return an Observable that emits the items of the source Observable until + * such time as other emits its first item + * @see takeUntil() + */ + public Observable takeUntil(Observable other) { + return OperationTakeUntil.takeUntil(this, other); + } + + /** + * Returns an Observable that bypasses all items from the source Observable + * as long as the specified condition holds true, but emits all further + * source items as soon as the condition becomes false. + *

+ * + * + * @param predicate a function to test each item emitted from the source + * Observable for a condition. It receives the emitted item + * as the first parameter and the index of the emitted item + * as a second parameter. + * @return an Observable that emits all items from the source Observable as + * soon as the condition becomes false + * @see skipWhileWithIndex() + * @see MSDN: Observable.SkipWhile + */ + public Observable skipWhileWithIndex(Func2 predicate) { + return create(OperationSkipWhile.skipWhileWithIndex(this, predicate)); + } + + /** + * Returns an Observable that bypasses all items from the source Observable + * as long as the specified condition holds true, but emits all further + * source items as soon as the condition becomes false. + *

+ * + * + * @param predicate a function to test each item emitted from the source + * Observable for a condition + * @return an Observable that emits all items from the source Observable as + * soon as the condition becomes false + * @see skipWhile() + * @see MSDN: Observable.SkipWhile + */ + public Observable skipWhile(Func1 predicate) { + return create(OperationSkipWhile.skipWhile(this, predicate)); + } + + /** + * Bypasses a specified number of items at the end of an Observable + * sequence. + *

+ * This operator accumulates a queue with a length enough to store the first + * count items. As more items are received, items are taken + * from the front of the queue and produced on the result sequence. This + * causes elements to be delayed. + *

+ * + * + * @param count number of elements to bypass at the end of the source + * sequence + * @return an Observable sequence emitting the source sequence items + * except for the bypassed ones at the end + * @throws IndexOutOfBoundsException if count is less than zero + * @see skipLast() + * @see MSDN: Observable.SkipLast + */ + public Observable skipLast(int count) { + return create(OperationSkipLast.skipLast(this, count)); + } + + /** + * Returns an Observable that emits a single item, a list composed of all + * the items emitted by the source Observable. + *

+ * + *

+ * Normally, an Observable that returns multiple items will do so by + * invoking its {@link Observer}'s {@link Observer#onNext onNext} method for + * each such item. You can change this behavior, instructing the Observable + * to compose a list of all of these items and then to invoke the Observer's + * onNext function once, passing it the entire list, by calling + * the Observable's toList method prior to calling its + * {@link #subscribe} method. + *

+ * Be careful not to use this operator on Observables that emit infinite or + * very large numbers of items, as you do not have the option to + * unsubscribe. + * + * @return an Observable that emits a single item: a List containing all of + * the items emitted by the source Observable. + * @see toList() + */ + public Observable> toList() { + return create(OperationToObservableList.toObservableList(this)); + } + + /** + * Return an Observable that emits the items emitted by the source + * Observable, in a sorted order (each item emitted by the Observable must + * implement {@link Comparable} with respect to all other items in the + * sequence). + *

+ * + * + * @throws ClassCastException if any item emitted by the Observable does not + * implement {@link Comparable} with respect to + * all other items emitted by the Observable + * @return an Observable that emits the items from the source Observable in + * sorted order + * @see toSortedList() + */ + public Observable> toSortedList() { + return create(OperationToObservableSortedList.toSortedList(this)); + } + + /** + * Return an Observable that emits the items emitted by the source + * Observable, in a sorted order based on a specified comparison function + *

+ * + * + * @param sortFunction a function that compares two items emitted by the + * source Observable and returns an Integer that + * indicates their sort order + * @return an Observable that emits the items from the source Observable in + * sorted order + * @see toSortedList() + */ + public Observable> toSortedList(Func2 sortFunction) { + return create(OperationToObservableSortedList.toSortedList(this, sortFunction)); + } + + /** + * Emit a specified set of items before beginning to emit items from the + * source Observable. + *

+ * + * + * @param values Iterable of the items you want the modified Observable to + * emit first + * @return an Observable that exhibits the modified behavior + * @see startWith() + */ + public Observable startWith(Iterable values) { + return concat(Observable. from(values), this); + } + + /** + * Emit a specified set of items with the specified scheduler before + * beginning to emit items from the source Observable. + *

+ * + * + * @param values iterable of the items you want the modified Observable to + * emit first + * @param scheduler the scheduler to emit the prepended values on + * @return an Observable that exhibits the modified behavior + * @see startWith() + * @see MSDN: Observable.StartWith + */ + public Observable startWith(Iterable values, Scheduler scheduler) { + return concat(from(values, scheduler), this); + } + + /** + * Emit a specified array of items with the specified scheduler before + * beginning to emit items from the source Observable. + *

+ * + * + * @param values the items you want the modified Observable to emit first + * @param scheduler the scheduler to emit the prepended values on + * @return an Observable that exhibits the modified behavior + * @see startWith() + * @see MSDN: Observable.StartWith + */ + public Observable startWith(T[] values, Scheduler scheduler) { + return startWith(Arrays.asList(values), scheduler); + } + + /** + * Emit a specified item before beginning to emit items from the source + * Observable. + *

+ * + * + * @param t1 item to emit + * @return an Observable that exhibits the modified behavior + * @see startWith() + */ + public Observable startWith(T t1) { + return concat(Observable. from(t1), this); + } + + /** + * Emit a specified set of items before beginning to emit items from the + * source Observable. + *

+ * + * + * @param t1 first item to emit + * @param t2 second item to emit + * @return an Observable that exhibits the modified behavior + * @see startWith() + */ + public Observable startWith(T t1, T t2) { + return concat(Observable. from(t1, t2), this); + } + + /** + * Emit a specified set of items before beginning to emit items from the + * source Observable. + *

+ * + * + * @param t1 first item to emit + * @param t2 second item to emit + * @param t3 third item to emit + * @return an Observable that exhibits the modified behavior + * @see startWith() + */ + public Observable startWith(T t1, T t2, T t3) { + return concat(Observable. from(t1, t2, t3), this); + } + + /** + * Emit a specified set of items before beginning to emit items from the + * source Observable. + *

+ * + * + * @param t1 first item to emit + * @param t2 second item to emit + * @param t3 third item to emit + * @param t4 fourth item to emit + * @return an Observable that exhibits the modified behavior + * @see startWith() + */ + public Observable startWith(T t1, T t2, T t3, T t4) { + return concat(Observable. from(t1, t2, t3, t4), this); + } + + /** + * Emit a specified set of items before beginning to emit items from the + * source Observable. + *

+ * + * + * @param t1 first item to emit + * @param t2 second item to emit + * @param t3 third item to emit + * @param t4 fourth item to emit + * @param t5 fifth item to emit + * @return an Observable that exhibits the modified behavior + * @see startWith() + */ + public Observable startWith(T t1, T t2, T t3, T t4, T t5) { + return concat(Observable. from(t1, t2, t3, t4, t5), this); + } + + /** + * Emit a specified set of items before beginning to emit items from the + * source Observable. + *

+ * + * + * @param t1 first item to emit + * @param t2 second item to emit + * @param t3 third item to emit + * @param t4 fourth item to emit + * @param t5 fifth item to emit + * @param t6 sixth item to emit + * @return an Observable that exhibits the modified behavior + * @see startWith() + */ + public Observable startWith(T t1, T t2, T t3, T t4, T t5, T t6) { + return concat(Observable. from(t1, t2, t3, t4, t5, t6), this); + } + + /** + * Emit a specified set of items before beginning to emit items from the + * source Observable. + *

+ * + * + * @param t1 first item to emit + * @param t2 second item to emit + * @param t3 third item to emit + * @param t4 fourth item to emit + * @param t5 fifth item to emit + * @param t6 sixth item to emit + * @param t7 seventh item to emit + * @return an Observable that exhibits the modified behavior + * @see startWith() + */ + public Observable startWith(T t1, T t2, T t3, T t4, T t5, T t6, T t7) { + return concat(Observable. from(t1, t2, t3, t4, t5, t6, t7), this); + } + + /** + * Emit a specified set of items before beginning to emit items from the + * source Observable. + *

+ * + * + * @param t1 first item to emit + * @param t2 second item to emit + * @param t3 third item to emit + * @param t4 fourth item to emit + * @param t5 fifth item to emit + * @param t6 sixth item to emit + * @param t7 seventh item to emit + * @param t8 eighth item to emit + * @return an Observable that exhibits the modified behavior + * @see startWith() + */ + public Observable startWith(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8) { + return concat(Observable. from(t1, t2, t3, t4, t5, t6, t7, t8), this); + } + + /** + * Emit a specified set of items before beginning to emit items from the + * source Observable. + *

+ * + * + * @param t1 first item to emit + * @param t2 second item to emit + * @param t3 third item to emit + * @param t4 fourth item to emit + * @param t5 fifth item to emit + * @param t6 sixth item to emit + * @param t7 seventh item to emit + * @param t8 eighth item to emit + * @param t9 ninth item to emit + * @return an Observable that exhibits the modified behavior + * @see startWith() + */ + public Observable startWith(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8, T t9) { + return concat(Observable. from(t1, t2, t3, t4, t5, t6, t7, t8, t9), this); + } + + /** + * Groups the items emitted by an Observable according to a specified + * criterion, and emits these grouped items as {@link GroupedObservable}s, + * one GroupedObservable per group. + *

+ * + * + * @param keySelector a function that extracts the key from an item + * @param elementSelector a function to map a source item to an item in a + * {@link GroupedObservable} + * @param the key type + * @param the type of items emitted by the resulting + * {@link GroupedObservable}s + * @return an Observable that emits {@link GroupedObservable}s, each of + * which corresponds to a unique key value and emits items + * representing items from the source Observable that share that key + * value + * @see groupBy + */ + public Observable> groupBy(final Func1 keySelector, final Func1 elementSelector) { + return create(OperationGroupBy.groupBy(this, keySelector, elementSelector)); + } + + /** + * Groups the items emitted by an Observable according to a specified + * criterion, and emits these grouped items as {@link GroupedObservable}s, + * one GroupedObservable per group. + *

+ * + * + * @param keySelector a function that extracts the key for each item + * @param the key type + * @return an Observable that emits {@link GroupedObservable}s, each of + * which corresponds to a unique key value and emits items + * representing items from the source Observable that share that key + * value + * @see groupBy + */ + public Observable> groupBy(final Func1 keySelector) { + return create(OperationGroupBy.groupBy(this, keySelector)); + } + + /** + * Returns an {@link Observable} that emits true if the source + * {@link Observable} is empty, otherwise false. + *

+ * In Rx.Net this is negated as the any operator but renamed in + * RxJava to better match Java naming idioms. + *

+ * + * + * @return an Observable that emits a Boolean + * @see isEmpty() + * @see MSDN: Observable.Any + */ + public Observable isEmpty() { + return create(OperationAny.isEmpty(this)); + } + + /** + * Returns an {@link Observable} that emits the last item emitted by the + * source or an IllegalArgumentException if the source + * {@link Observable} is empty. + *

+ * + * + * @return + * @see last() + */ + public Observable last() { + return create(OperationLast.last(this)); + } + + /** + * Converts an Observable into a {@link BlockingObservable} (an Observable + * with blocking operators). + * + * @return + * @see Blocking Observable Operators + */ + public BlockingObservable toBlockingObservable() { + return BlockingObservable.from(this); + } + + /** + * Converts the items emitted by an Observable to the specified type. + *

+ * + * + * @param klass the target class type which the items will be converted to + * @return an Observable that emits each item from the source Observable + * converted to the specified type + * @see cast() + * @see MSDN: Observable.Cast + */ + public Observable cast(final Class klass) { + return create(OperationCast.cast(this, klass)); + } + + /** + * Filters the items emitted by an Observable based on the specified type. + *

+ * + * + * @param klass the class type to filter the items emitted by the source + * Observable + * @return an Observable that emits items from the source Observable of + * type klass. + * @see ofClass() + * @see MSDN: Observable.OfType + */ + public Observable ofType(final Class klass) { + return filter(new Func1() { + public Boolean call(T t) { + return klass.isInstance(t); + } + }).cast(klass); + } + + /** + * Ignores all items emitted by an Observable and only calls + * onCompleted or onError. + *

+ * + * + * @return an empty Observable that only calls onCompleted or + * onError + * @see ignoreElements() + * @see MSDN: Observable.IgnoreElements + */ + public Observable ignoreElements() { + return filter(alwaysFalse()); + } + + /** + * Applies a timeout policy for each element in the observable sequence, + * using the specified scheduler to run timeout timers. If the next element + * isn't received within the specified timeout duration starting from its + * predecessor, a TimeoutException is propagated to the observer. + *

+ * + * + * @param timeout maximum duration between values before a timeout occurs + * @param timeUnit the unit of time which applies to the + * timeout argument. + * @return the source Observable with a TimeoutException in + * case of a timeout + * @see timeout() + * @see MSDN: Observable.Timeout + */ + public Observable timeout(long timeout, TimeUnit timeUnit) { + return create(OperationTimeout.timeout(this, timeout, timeUnit)); + } + + /** + * Applies a timeout policy for each element in the observable sequence, + * using the specified scheduler to run timeout timers. If the next element + * isn't received within the specified timeout duration starting from its + * predecessor, the other observable sequence is used to produce future + * messages from that point on. + *

+ * + * + * @param timeout maximum duration between values before a timeout occurs + * @param timeUnit the unit of time which applies to the + * timeout argument + * @param other sequence to return in case of a timeout + * @return the source sequence switching to the other sequence in case of a + * timeout + * @see timeout() + * @see MSDN: Observable.Timeout + */ + public Observable timeout(long timeout, TimeUnit timeUnit, Observable other) { + return create(OperationTimeout.timeout(this, timeout, timeUnit, other)); + } + + /** + * Applies a timeout policy for each element in the observable sequence, + * using the specified scheduler to run timeout timers. If the next element + * isn't received within the specified timeout duration starting from its + * predecessor, a TimeoutException is propagated to the observer. + *

+ * + * + * @param timeout maximum duration between values before a timeout occurs + * @param timeUnit the unit of time which applies to the + * timeout argument + * @param scheduler Scheduler to run the timeout timers on + * @return the source sequence with a TimeoutException in case + * of a timeout + * @see timeout() + * @see MSDN: Observable.Timeout + */ + public Observable timeout(long timeout, TimeUnit timeUnit, Scheduler scheduler) { + return create(OperationTimeout.timeout(this, timeout, timeUnit, scheduler)); + } + + /** + * Applies a timeout policy for each element in the observable sequence, + * using the specified scheduler to run timeout timers. If the next element + * isn't received within the specified timeout duration starting from its + * predecessor, the other observable sequence is used to produce future + * messages from that point on. + *

+ * + * + * @param timeout maximum duration between values before a timeout occurs + * @param timeUnit the unit of time which applies to the + * timeout argument + * @param other sequence to return in case of a timeout + * @param scheduler Scheduler to run the timeout timers on + * @return the source sequence switching to the other sequence in case of a + * timeout + * @see timeout() + * @see MSDN: Observable.Timeout + */ + public Observable timeout(long timeout, TimeUnit timeUnit, Observable other, Scheduler scheduler) { + return create(OperationTimeout.timeout(this, timeout, timeUnit, other, scheduler)); + } + + /** + * Records the time interval between consecutive items emitted by an + * Observable. + *

+ * + * + * @return an Observable that emits time interval information items + * @see timeInterval() + * @see MSDN: Observable.TimeInterval + */ + public Observable> timeInterval() { + return create(OperationTimeInterval.timeInterval(this)); + } + + /** + * Records the time interval between consecutive items emitted by an + * Observable, using the specified Scheduler to compute time intervals. + *

+ * + * + * @param scheduler Scheduler used to compute time intervals + * @return an Observable that emits time interval information items + * @see timeInterval() + * @see MSDN: Observable.TimeInterval + */ + public Observable> timeInterval(Scheduler scheduler) { + return create(OperationTimeInterval.timeInterval(this, scheduler)); + } + + /** + * Constructs an Observable that depends on a resource object. + *

+ * + * + * @param resourceFactory the factory function to obtain a resource object + * that depends on the Observable + * @param observableFactory the factory function to obtain an Observable + * @return the Observable whose lifetime controls the lifetime of the + * dependent resource object + * @see using() + * @see MSDN: Observable.Using + */ + public static Observable using(Func0 resourceFactory, Func1> observableFactory) { + return create(OperationUsing.using(resourceFactory, observableFactory)); + } + + /** + * Propagates the Observable sequence that reacts first. + *

+ * + * + * @param o1 an Observable competing to react first + * @param o2 an Observable competing to react first + * @return an Observable that reflects whichever of the given Observables + * reacted first + * @see amb() + * @see MSDN: Observable.Amb + */ + public static Observable amb(Observable o1, Observable o2) { + return create(OperationAmb.amb(o1, o2)); + } + + /** + * Propagates the Observable sequence that reacts first. + *

+ * + * + * @param o1 an Observable competing to react first + * @param o2 an Observable competing to react first + * @param o3 an Observable competing to react first + * @return an Observable that reflects whichever of the given Observables + * reacted first + * @see amb() + * @see MSDN: Observable.Amb + */ + public static Observable amb(Observable o1, Observable o2, Observable o3) { + return create(OperationAmb.amb(o1, o2, o3)); + } + + /** + * Propagates the observable sequence that reacts first. + *

+ * + * + * @param o1 an Observable competing to react first + * @param o2 an Observable competing to react first + * @param o3 an Observable competing to react first + * @param o4 an Observable competing to react first + * @return an Observable that reflects whichever of the given Observables + * reacted first + * @see amb() + * @see MSDN: Observable.Amb + */ + public static Observable amb(Observable o1, Observable o2, Observable o3, Observable o4) { + return create(OperationAmb.amb(o1, o2, o3, o4)); + } + + /** + * Propagates the Observable sequence that reacts first. + *

+ * + * + * @param o1 an Observable competing to react first + * @param o2 an Observable competing to react first + * @param o3 an Observable competing to react first + * @param o4 an Observable competing to react first + * @param o5 an Observable competing to react first + * @return an Observable that reflects whichever of the given Observables + * reacted first + * @see amb() + * @see MSDN: Observable.Amb + */ + public static Observable amb(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5) { + return create(OperationAmb.amb(o1, o2, o3, o4, o5)); + } + + /** + * Propagates the observable sequence that reacts first. + *

+ * + * + * @param o1 an Observable competing to react first + * @param o2 an Observable competing to react first + * @param o3 an Observable competing to react first + * @param o4 an Observable competing to react first + * @param o5 an Observable competing to react first + * @param o6 an Observable competing to react first + * @return an Observable that reflects whichever of the given Observables + * reacted first + * @see amb() + * @see MSDN: Observable.Amb + */ + public static Observable amb(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6) { + return create(OperationAmb.amb(o1, o2, o3, o4, o5, o6)); + } + + /** + * Propagates the observable sequence that reacts first. + *

+ * + * + * @param o1 an Observable competing to react first + * @param o2 an Observable competing to react first + * @param o3 an Observable competing to react first + * @param o4 an Observable competing to react first + * @param o5 an Observable competing to react first + * @param o6 an Observable competing to react first + * @param o7 an Observable competing to react first + * @return an Observable that reflects whichever of the given Observables + * reacted first + * @see amb() + * @see MSDN: Observable.Amb + */ + public static Observable amb(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7) { + return create(OperationAmb.amb(o1, o2, o3, o4, o5, o6, o7)); + } + + /** + * Propagates the observable sequence that reacts first. + *

+ * + * + * @param o1 an Observable competing to react first + * @param o2 an Observable competing to react first + * @param o3 an Observable competing to react first + * @param o4 an Observable competing to react first + * @param o5 an Observable competing to react first + * @param o6 an Observable competing to react first + * @param o7 an Observable competing to react first + * @param o8 an observable competing to react first + * @return an Observable that reflects whichever of the given Observables + * reacted first + * @see amb() + * @see MSDN: Observable.Amb + */ + public static Observable amb(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, Observable o8) { + return create(OperationAmb.amb(o1, o2, o3, o4, o5, o6, o7, o8)); + } + + /** + * Propagates the observable sequence that reacts first. + *

+ * + * + * @param o1 an Observable competing to react first + * @param o2 an Observable competing to react first + * @param o3 an Observable competing to react first + * @param o4 an Observable competing to react first + * @param o5 an Observable competing to react first + * @param o6 an Observable competing to react first + * @param o7 an Observable competing to react first + * @param o8 an Observable competing to react first + * @param o9 an Observable competing to react first + * @return an Observable that reflects whichever of the given Observables + * reacted first + * @see amb() + * @see MSDN: Observable.Amb + */ + public static Observable amb(Observable o1, Observable o2, Observable o3, Observable o4, Observable o5, Observable o6, Observable o7, Observable o8, Observable o9) { + return create(OperationAmb.amb(o1, o2, o3, o4, o5, o6, o7, o8, o9)); + } + + /** + * Propagates the observable sequence that reacts first. + *

+ * + * + * @param sources Observable sources competing to react first + * @return an Observable that reflects whichever of the given Observables + * reacted first + * @see amb() + * @see MSDN: Observable.Amb + */ + public static Observable amb(Iterable> sources) { + return create(OperationAmb.amb(sources)); + } + + /** + * Invokes an action for each item emitted by the Observable. + *

+ * + * + * @param observer the action to invoke for each item emitted in the source + * sequence + * @return the source sequence with the side-effecting behavior applied + * @see doOnEach() + * @see MSDN: Observable.Do + */ + public Observable doOnEach(Observer observer) { + return create(OperationDoOnEach.doOnEach(this, observer)); + } + + /** + * Invokes an action for each item emitted by an Observable. + *

+ * + * + * @param onNext the action to invoke for each item in the source + * sequence + * @return the source sequence with the side-effecting behavior applied + * @see doOnEach() + * @see MSDN: Observable.Do + */ + public Observable doOnEach(final Action1 onNext) { + Observer observer = new Observer() { + @Override + public void onCompleted() {} + + @Override + public void onError(Throwable e) {} + + @Override + public void onNext(T args) { + onNext.call(args); + } + + }; + + + return create(OperationDoOnEach.doOnEach(this, observer)); + } + + /** + * Invokes an action if onError is called from the Observable. + *

+ * + * + * @param onError the action to invoke if onError is invoked + * @return the source sequence with the side-effecting behavior applied + * @see doOnError() + * @see MSDN: Observable.Do + */ + public Observable doOnError(final Action1 onError) { + Observer observer = new Observer() { + @Override + public void onCompleted() {} + + @Override + public void onError(Throwable e) { + onError.call(e); + } + + @Override + public void onNext(T args) { } + + }; + + + return create(OperationDoOnEach.doOnEach(this, observer)); + } + + /** + * Invokes an action when onCompleted is called by the + * Observable. + *

+ * + * + * @param onCompleted the action to invoke when onCompleted is + * called + * @return the source sequence with the side-effecting behavior applied + * @see doOnCompleted() + * @see MSDN: Observable.Do + */ + public Observable doOnCompleted(final Action0 onCompleted) { + Observer observer = new Observer() { + @Override + public void onCompleted() { + onCompleted.call(); + } + + @Override + public void onError(Throwable e) { } + + @Override + public void onNext(T args) { } + + }; + + + return create(OperationDoOnEach.doOnEach(this, observer)); + } + + /** + * Invokes an action for each item emitted by an Observable. + * + * @param onNext the action to invoke for each item in the source sequence + * @param onError the action to invoke when the source Observable calls + * onError + * @return the source sequence with the side-effecting behavior applied + * @see doOnEach() + * @see MSDN: Observable.Do + */ + public Observable doOnEach(final Action1 onNext, final Action1 onError) { + Observer observer = new Observer() { + @Override + public void onCompleted() {} + + @Override + public void onError(Throwable e) { + onError.call(e); + } + + @Override + public void onNext(T args) { + onNext.call(args); + } + + }; + + + return create(OperationDoOnEach.doOnEach(this, observer)); + } + + /** + * Invokes an action for each item emitted by an Observable. + * + * @param onNext the action to invoke for each item in the source sequence + * @param onError the action to invoke when the source Observable calls + * onError + * @param onCompleted the action to invoke when the source Observable calls + * onCompleted + * @return the source sequence with the side-effecting behavior applied + * @see doOnEach() + * @see MSDN: Observable.Do + */ + public Observable doOnEach(final Action1 onNext, final Action1 onError, final Action0 onCompleted) { + Observer observer = new Observer() { + @Override + public void onCompleted() { + onCompleted.call(); + } + + @Override + public void onError(Throwable e) { + onError.call(e); + } + + @Override + public void onNext(T args) { + onNext.call(args); + } + + }; + + + return create(OperationDoOnEach.doOnEach(this, observer)); + } + + /** + * Whether a given {@link Function} is an internal implementation inside + * rx.* packages or not. + *

+ * For why this is being used see + * https://github.com/Netflix/RxJava/issues/216 for discussion on + * "Guideline 6.4: Protect calls to user code from within an operator" + * + * Note: If strong reasons for not depending on package names comes up then + * the implementation of this method can change to looking for a marker + * interface. + * + * @param o + * @return {@code true} if the given function is an internal implementation, + * and {@code false} otherwise. + */ + private boolean isInternalImplementation(Object o) { + if (o == null) { + return true; + } + // prevent double-wrapping (yeah it happens) + if (o instanceof SafeObserver) { + return true; + } + + Class clazz = o.getClass(); + if (internalClassMap.containsKey(clazz)) { + //don't need to do reflection + return internalClassMap.get(clazz); + } else { + // we treat the following package as "internal" and don't wrap it + Package p = o.getClass().getPackage(); // it can be null + Boolean isInternal = (p != null && p.getName().startsWith("rx.operators")); + internalClassMap.put(clazz, isInternal); + return isInternal; + } + } + + /** + * Creates a pattern that matches when both Observable sequences have an + * available item. + *

+ * + * + * @param right Observable sequence to match with the left sequence + * @return Pattern object that matches when both Observable sequences have + * an available item + * @throws NullPointerException if right is null + * @see and() + * @see MSDN: Observable.And + */ + public Pattern2 and(Observable right) { + return OperationJoinPatterns.and(this, right); + } + + /** + * Matches when the Observable sequence has an available item and + * projects the item by invoking the selector function. + *

+ * + * + * @param selector Selector that will be invoked for elements in the source + * sequence + * @return Plan that produces the projected results, to be fed (with other + * plans) to the When operator + * @throws NullPointerException if selector is null + * @see then() + * @see MSDN: Observable.Then + */ + public Plan0 then(Func1 selector) { + return OperationJoinPatterns.then(this, selector); + } + + /** + * Joins together the results from several patterns. + *

+ * + * + * @param plans a series of plans created by use of the Then operator on + * patterns + * @return an Observable sequence with the results from matching several + * patterns + * @throws NullPointerException if plans is null + * @see when() + * @see MSDN: Observable.When + */ + public static Observable when(Plan0... plans) { + return create(OperationJoinPatterns.when(plans)); + } + + /** + * Joins together the results from several patterns. + *

+ * + * + * @param plans a series of plans created by use of the Then operator on + * patterns + * @return an Observable sequence with the results from matching several + * patterns + * @throws NullPointerException if plans is null + * @see when() + * @see MSDN: Observable.When + */ + public static Observable when(Iterable> plans) { + if (plans == null) { + throw new NullPointerException("plans"); + } + return create(OperationJoinPatterns.when(plans)); + } + + /** + * Joins the results from a pattern. + *

+ * + * + * @param p1 the plan to join + * @return an Observable sequence with the results from matching a pattern + * @see when() + * @see MSDN: Observable.When + */ + @SuppressWarnings("unchecked") + public static Observable when(Plan0 p1) { + return create(OperationJoinPatterns.when(p1)); + } + + /** + * Joins together the results from several patterns. + *

+ * + * + * @param p1 a plan + * @param p2 a plan + * @return an Observable sequence with the results from matching several + * patterns + * @see when() + * @see MSDN: Observable.When + */ + @SuppressWarnings("unchecked") + public static Observable when(Plan0 p1, Plan0 p2) { + return create(OperationJoinPatterns.when(p1, p2)); + } + + /** + * Joins together the results from several patterns. + *

+ * + * + * @param p1 a plan + * @param p2 a plan + * @param p3 a plan + * @return an Observable sequence with the results from matching several + * patterns + * @see when() + * @see MSDN: Observable.When + */ + @SuppressWarnings("unchecked") + public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3) { + return create(OperationJoinPatterns.when(p1, p2, p3)); + } + + /** + * Joins together the results from several patterns. + *

+ * + * + * @param p1 a plan + * @param p2 a plan + * @param p3 a plan + * @param p4 a plan + * @return an Observable sequence with the results from matching several + * patterns + * @see when() + * @see MSDN: Observable.When + */ + @SuppressWarnings("unchecked") + public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3, Plan0 p4) { + return create(OperationJoinPatterns.when(p1, p2, p3, p4)); + } + + /** + * Joins together the results from several patterns. + *

+ * + * + * @param p1 a plan + * @param p2 a plan + * @param p3 a plan + * @param p4 a plan + * @param p5 a plan + * @return an Observable sequence with the results from matching several + * patterns + * @see when() + * @see MSDN: Observable.When + */ + @SuppressWarnings("unchecked") + public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3, Plan0 p4, Plan0 p5) { + return create(OperationJoinPatterns.when(p1, p2, p3, p4, p5)); + } + + /** + * Joins together the results from several patterns. + *

+ * + * + * @param p1 a plan + * @param p2 a plan + * @param p3 a plan + * @param p4 a plan + * @param p5 a plan + * @param p6 a plan + * @return an Observable sequence with the results from matching several + * patterns + * @see when() + * @see MSDN: Observable.When + */ + @SuppressWarnings("unchecked") + public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3, Plan0 p4, Plan0 p5, Plan0 p6) { + return create(OperationJoinPatterns.when(p1, p2, p3, p4, p5, p6)); + } + + /** + * Joins together the results from several patterns. + *

+ * + * + * @param p1 a plan + * @param p2 a plan + * @param p3 a plan + * @param p4 a plan + * @param p5 a plan + * @param p6 a plan + * @param p7 a plan + * @return an Observable sequence with the results from matching several + * patterns + * @see when() + * @see MSDN: Observable.When + */ + @SuppressWarnings("unchecked") + public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3, Plan0 p4, Plan0 p5, Plan0 p6, Plan0 p7) { + return create(OperationJoinPatterns.when(p1, p2, p3, p4, p5, p6, p7)); + } + + /** + * Joins together the results from several patterns. + *

+ * + * + * @param p1 a plan + * @param p2 a plan + * @param p3 a plan + * @param p4 a plan + * @param p5 a plan + * @param p6 a plan + * @param p7 a plan + * @param p8 a plan + * @return an Observable sequence with the results from matching several + * patterns + * @see when() + * @see MSDN: Observable.When + */ + @SuppressWarnings("unchecked") + public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3, Plan0 p4, Plan0 p5, Plan0 p6, Plan0 p7, Plan0 p8) { + return create(OperationJoinPatterns.when(p1, p2, p3, p4, p5, p6, p7, p8)); + } + + /** + * Joins together the results from several patterns. + *

+ * + * + * @param p1 a plan + * @param p2 a plan + * @param p3 a plan + * @param p4 a plan + * @param p5 a plan + * @param p6 a plan + * @param p7 a plan + * @param p8 a plan + * @param p9 a plan + * @return an Observable sequence with the results from matching several + * patterns + * @see when() + * @see MSDN: Observable.When + */ + @SuppressWarnings("unchecked") + public static Observable when(Plan0 p1, Plan0 p2, Plan0 p3, Plan0 p4, Plan0 p5, Plan0 p6, Plan0 p7, Plan0 p8, Plan0 p9) { + return create(OperationJoinPatterns.when(p1, p2, p3, p4, p5, p6, p7, p8, p9)); + } + /** + * Correlates the elements of two sequences based on overlapping durations. + * @param right The right observable sequence to join elements for. + * @param leftDurationSelector A function to select the duration of each + * element of this observable sequence, used to + * determine overlap. + * @param rightDurationSelector A function to select the duration of each + * element of the right observable sequence, + * used to determine overlap. + * @param resultSelector A function invoked to compute a result element + * for any two overlapping elements of the left and + * right observable sequences. + * @return An observable sequence that contains result elements computed + * from source elements that have an overlapping duration. + * @see MSDN: Observable.Join + */ + public Observable join(Observable right, Func1> leftDurationSelector, + Func1> rightDurationSelector, + Func2 resultSelector) { + return create(new OperationJoin(this, right, leftDurationSelector, rightDurationSelector, resultSelector)); + } +} +