/**

* Copyright 2015 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 java.util.Collection;

import java.util.concurrent.Callable;

import java.util.concurrent.Future;

import java.util.concurrent.TimeUnit;

import java.util.concurrent.TimeoutException;

import rx.Observable.Operator;

import rx.annotations.Experimental;

import rx.exceptions.Exceptions;

import rx.exceptions.OnErrorNotImplementedException;

import rx.functions.Action0;

import rx.functions.Action1;

import rx.functions.Func1;

import rx.functions.Func2;

import rx.functions.Func3;

import rx.functions.Func4;

import rx.functions.Func5;

import rx.functions.Func6;

import rx.functions.Func7;

import rx.functions.Func8;

import rx.functions.Func9;

import rx.functions.FuncN;

import rx.annotations.Beta;

import rx.internal.operators.*;

import rx.internal.producers.SingleDelayedProducer;

import rx.singles.BlockingSingle;

import rx.observers.SafeSubscriber;

import rx.plugins.*;

import rx.schedulers.Schedulers;

import rx.subscriptions.Subscriptions;

/**

* The Single class implements the Reactive Pattern for a single value response. See {@link Observable} for the

* implementation of the Reactive Pattern for a stream or vector of values.

* <p>

* {@code Single} behaves the same as {@link Observable} except that it can only emit either a single successful

* value, or an error (there is no "onComplete" notification as there is for {@link Observable})

* <p>

* Like an {@link Observable}, a {@code Single} is lazy, can be either "hot" or "cold", synchronous or

* asynchronous.

* <p>

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

* <p>

* <img width="605" height="285" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.legend.png" alt="">

* <p>

* For more information see the <a href="http://reactivex.io/documentation/observable.html">ReactiveX

* documentation</a>.

*

* @param <T>

* the type of the item emitted by the Single

* @since (If this class graduates from "Experimental" replace this parenthetical with the release number)

*/

@Beta

public class Single<T> {

final Observable.OnSubscribe<T> onSubscribe;

/**

* Creates a Single with a Function to execute when it is subscribed to (executed).

* <p>

* <em>Note:</em> Use {@link #create(OnSubscribe)} to create a Single, instead of this constructor,

* unless you specifically have a need for inheritance.

*

* @param f

* {@code OnExecute} to be executed when {@code execute(SingleSubscriber)} or

* {@code subscribe(Subscriber)} is called

*/

protected Single(final OnSubscribe<T> f) {

// bridge between OnSubscribe (which all Operators and Observables use) and OnExecute (for Single)

this.onSubscribe = new Observable.OnSubscribe<T>() {

@Override

public void call(final Subscriber<? super T> child) {

final SingleDelayedProducer<T> producer = new SingleDelayedProducer<T>(child);

child.setProducer(producer);

SingleSubscriber<T> ss = new SingleSubscriber<T>() {

@Override

public void onSuccess(T value) {

producer.setValue(value);

}

@Override

public void onError(Throwable error) {

child.onError(error);

}

};

child.add(ss);

f.call(ss);

}

};

}

private Single(final Observable.OnSubscribe<T> f) {

this.onSubscribe = f;

}

static final RxJavaObservableExecutionHook hook = RxJavaPlugins.getInstance().getObservableExecutionHook();

/**

* Returns a Single that will execute the specified function when a {@link SingleSubscriber} executes it or

* a {@link Subscriber} subscribes to it.

* <p>

* <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.create.png" alt="">

* <p>

* Write the function you pass to {@code create} so that it behaves as a Single: It should invoke the

* SingleSubscriber {@link SingleSubscriber#onSuccess onSuccess} and/or

* {@link SingleSubscriber#onError onError} methods appropriately.

* <p>

* A well-formed Single must invoke either the SingleSubscriber's {@code onSuccess} method exactly once or

* its {@code onError} method exactly once.

* <p>

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code create} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param <T>

* the type of the item that this Single emits

* @param f

* a function that accepts an {@code SingleSubscriber<T>}, and invokes its {@code onSuccess} or

* {@code onError} methods as appropriate

* @return a Single that, when a {@link Subscriber} subscribes to it, will execute the specified function

* @see <a href="http://reactivex.io/documentation/operators/create.html">ReactiveX operators documentation: Create</a>

*/

public final static <T> Single<T> create(OnSubscribe<T> f) {

return new Single<T>(f); // TODO need hook

}

/**

* Invoked when Single.execute is called.

*/

public interface OnSubscribe<T> extends Action1<SingleSubscriber<? super T>> {

// cover for generics insanity

}

/**

* Lifts a function to the current Single and returns a new Single that when subscribed to will pass the

* values of the current Single through the Operator function.

* <p>

* In other words, this allows chaining TaskExecutors together on a Single for acting on the values within

* the Single.

* <p>

* {@code task.map(...).filter(...).lift(new OperatorA()).lift(new OperatorB(...)).subscribe() }

* <p>

* If the operator you are creating is designed to act on the item emitted by a source Single, use

* {@code lift}. If your operator is designed to transform the source Single as a whole (for instance, by

* applying a particular set of existing RxJava operators to it) use {@link #compose}.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code lift} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param lift

* the Operator that implements the Single-operating function to be applied to the source Single

* @return a Single that is the result of applying the lifted Operator to the source Single

* @see <a href="https://github.com/ReactiveX/RxJava/wiki/Implementing-Your-Own-Operators">RxJava wiki: Implementing Your Own Operators</a>

*/

private final <R> Single<R> lift(final Operator<? extends R, ? super T> lift) {

// This method is private because not sure if we want to expose the Observable.Operator in this public API rather than a Single.Operator

return new Single<R>(new Observable.OnSubscribe<R>() {

@Override

public void call(Subscriber<? super R> o) {

try {

final Subscriber<? super T> st = hook.onLift(lift).call(o);

try {

// new Subscriber created and being subscribed with so 'onStart' it

st.onStart();

onSubscribe.call(st);

} catch (Throwable e) {

// localized capture of errors rather than it skipping all operators

// and ending up in the try/catch of the subscribe method which then

// prevents onErrorResumeNext and other similar approaches to error handling

Exceptions.throwOrReport(e, st);

}

} catch (Throwable e) {

// if the lift function failed all we can do is pass the error to the final Subscriber

// as we don't have the operator available to us

Exceptions.throwOrReport(e, o);

}

}

});

}

/**

* Transform a Single by applying a particular Transformer function to it.

* <p>

* This method operates on the Single itself whereas {@link #lift} operates on the Single's Subscribers or

* Observers.

* <p>

* If the operator you are creating is designed to act on the individual item emitted by a Single, use

* {@link #lift}. If your operator is designed to transform the source Single as a whole (for instance, by

* applying a particular set of existing RxJava operators to it) use {@code compose}.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code compose} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param transformer

* implements the function that transforms the source Single

* @return the source Single, transformed by the transformer function

* @see <a href="https://github.com/ReactiveX/RxJava/wiki/Implementing-Your-Own-Operators">RxJava wiki: Implementing Your Own Operators</a>

*/

@SuppressWarnings("unchecked")

public <R> Single<R> compose(Transformer<? super T, ? extends R> transformer) {

return ((Transformer<T, R>) transformer).call(this);

}

/**

* Transformer function used by {@link #compose}.

*

* @warn more complete description needed

*/

public interface Transformer<T, R> extends Func1<Single<T>, Single<R>> {

// cover for generics insanity

}

/**

* <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.toObservable.png" alt="">

*

* @warn more complete description needed

*/

private static <T> Observable<T> asObservable(Single<T> t) {

// is this sufficient, or do I need to keep the outer Single and subscribe to it?

return Observable.create(t.onSubscribe);

}

/**

* INTERNAL: Used with lift and operators.

*

* Converts the source {@code Single<T>} into an {@code Single<Observable<T>>} that emits an Observable

* that emits the same emission as the source Single.

* <p>

* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.nest.png" alt="">

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code nest} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @return a Single that emits an Observable that emits the same item as the source Single

* @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>

*/

private final Single<Observable<T>> nest() {

return Single.just(asObservable(this));

}

/* *********************************************************************************************************

* Operators Below Here

* *********************************************************************************************************

*/

/**

* Returns an Observable that emits the items emitted by two Singles, one after the other.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.png" alt="">

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* an Single to be concatenated

* @param t2

* an Single to be concatenated

* @return an Observable that emits items emitted by the two source Singles, one after the other.

* @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>

*/

public final static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2) {

return Observable.concat(asObservable(t1), asObservable(t2));

}

/**

* Returns an Observable that emits the items emitted by three Singles, one after the other.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.png" alt="">

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be concatenated

* @param t2

* a Single to be concatenated

* @param t3

* a Single to be concatenated

* @return an Observable that emits items emitted by the three source Singles, one after the other.

* @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>

*/

public final static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3) {

return Observable.concat(asObservable(t1), asObservable(t2), asObservable(t3));

}

/**

* Returns an Observable that emits the items emitted by four Singles, one after the other.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.png" alt="">

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be concatenated

* @param t2

* a Single to be concatenated

* @param t3

* a Single to be concatenated

* @param t4

* a Single to be concatenated

* @return an Observable that emits items emitted by the four source Singles, one after the other.

* @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>

*/

public final static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4) {

return Observable.concat(asObservable(t1), asObservable(t2), asObservable(t3), asObservable(t4));

}

/**

* Returns an Observable that emits the items emitted by five Singles, one after the other.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.png" alt="">

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be concatenated

* @param t2

* a Single to be concatenated

* @param t3

* a Single to be concatenated

* @param t4

* a Single to be concatenated

* @param t5

* a Single to be concatenated

* @return an Observable that emits items emitted by the five source Singles, one after the other.

* @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>

*/

public final static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5) {

return Observable.concat(asObservable(t1), asObservable(t2), asObservable(t3), asObservable(t4), asObservable(t5));

}

/**

* Returns an Observable that emits the items emitted by six Singles, one after the other.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.png" alt="">

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be concatenated

* @param t2

* a Single to be concatenated

* @param t3

* a Single to be concatenated

* @param t4

* a Single to be concatenated

* @param t5

* a Single to be concatenated

* @param t6

* a Single to be concatenated

* @return an Observable that emits items emitted by the six source Singles, one after the other.

* @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>

*/

public final static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6) {

return Observable.concat(asObservable(t1), asObservable(t2), asObservable(t3), asObservable(t4), asObservable(t5), asObservable(t6));

}

/**

* Returns an Observable that emits the items emitted by seven Singles, one after the other.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.png" alt="">

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be concatenated

* @param t2

* a Single to be concatenated

* @param t3

* a Single to be concatenated

* @param t4

* a Single to be concatenated

* @param t5

* a Single to be concatenated

* @param t6

* a Single to be concatenated

* @param t7

* a Single to be concatenated

* @return an Observable that emits items emitted by the seven source Singles, one after the other.

* @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>

*/

public final static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7) {

return Observable.concat(asObservable(t1), asObservable(t2), asObservable(t3), asObservable(t4), asObservable(t5), asObservable(t6), asObservable(t7));

}

/**

* Returns an Observable that emits the items emitted by eight Singles, one after the other.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.png" alt="">

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be concatenated

* @param t2

* a Single to be concatenated

* @param t3

* a Single to be concatenated

* @param t4

* a Single to be concatenated

* @param t5

* a Single to be concatenated

* @param t6

* a Single to be concatenated

* @param t7

* a Single to be concatenated

* @param t8

* a Single to be concatenated

* @return an Observable that emits items emitted by the eight source Singles, one after the other.

* @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>

*/

public final static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7, Single<? extends T> t8) {

return Observable.concat(asObservable(t1), asObservable(t2), asObservable(t3), asObservable(t4), asObservable(t5), asObservable(t6), asObservable(t7), asObservable(t8));

}

/**

* Returns an Observable that emits the items emitted by nine Singles, one after the other.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.png" alt="">

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be concatenated

* @param t2

* a Single to be concatenated

* @param t3

* a Single to be concatenated

* @param t4

* a Single to be concatenated

* @param t5

* a Single to be concatenated

* @param t6

* a Single to be concatenated

* @param t7

* a Single to be concatenated

* @param t8

* a Single to be concatenated

* @param t9

* a Single to be concatenated

* @return an Observable that emits items emitted by the nine source Singles, one after the other.

* @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>

*/

public final static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7, Single<? extends T> t8, Single<? extends T> t9) {

return Observable.concat(asObservable(t1), asObservable(t2), asObservable(t3), asObservable(t4), asObservable(t5), asObservable(t6), asObservable(t7), asObservable(t8), asObservable(t9));

}

/**

* Returns a Single that invokes a subscriber's {@link SingleSubscriber#onError onError} method when the

* subscriber subscribes to it.

* <p>

* <img width="640" height="190" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.error.png" alt="">

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code error} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param exception

* the particular Throwable to pass to {@link SingleSubscriber#onError onError}

* @param <T>

* the type of the item (ostensibly) emitted by the Single

* @return a Single that invokes the subscriber's {@link SingleSubscriber#onError onError} method when

* the subscriber subscribes to it

* @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Throw</a>

*/

public final static <T> Single<T> error(final Throwable exception) {

return Single.create(new OnSubscribe<T>() {

@Override

public void call(SingleSubscriber<? super T> te) {

te.onError(exception);

}

});

}

/**

* Converts a {@link Future} into a {@code Single}.

* <p>

* <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.from.Future.png" alt="">

* <p>

* You can convert any object that supports the {@link Future} interface into a Single that emits the return

* value of the {@link Future#get} method of that object, by passing the object into the {@code from}

* method.

* <p>

* <em>Important note:</em> This Single is blocking; you cannot unsubscribe from it.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code from} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param future

* the source {@link Future}

* @param <T>

* the type of object that the {@link Future} returns, and also the type of item to be emitted by

* the resulting {@code Single}

* @return a {@code Single} that emits the item from the source {@link Future}

* @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>

*/

public final static <T> Single<T> from(Future<? extends T> future) {

return new Single<T>(OnSubscribeToObservableFuture.toObservableFuture(future));

}

/**

* Converts a {@link Future} into a {@code Single}, with a timeout on the Future.

* <p>

* <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.from.Future.png" alt="">

* <p>

* You can convert any object that supports the {@link Future} interface into a {@code Single} that emits

* the return value of the {@link Future#get} method of that object, by passing the object into the

* {@code from} method.

* <p>

* <em>Important note:</em> This {@code Single} is blocking; you cannot unsubscribe from it.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code from} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param future

* the source {@link Future}

* @param timeout

* the maximum time to wait before calling {@code get}

* @param unit

* the {@link TimeUnit} of the {@code timeout} argument

* @param <T>

* the type of object that the {@link Future} returns, and also the type of item to be emitted by

* the resulting {@code Single}

* @return a {@code Single} that emits the item from the source {@link Future}

* @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>

*/

public final static <T> Single<T> from(Future<? extends T> future, long timeout, TimeUnit unit) {

return new Single<T>(OnSubscribeToObservableFuture.toObservableFuture(future, timeout, unit));

}

/**

* Converts a {@link Future}, operating on a specified {@link Scheduler}, into a {@code Single}.

* <p>

* <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.from.Future.s.png" alt="">

* <p>

* You can convert any object that supports the {@link Future} interface into a {@code Single} that emits

* the return value of the {@link Future#get} method of that object, by passing the object into the

* {@code from} method.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>you specify which {@link Scheduler} this operator will use</dd>

* </dl>

*

* @param future

* the source {@link Future}

* @param scheduler

* the {@link Scheduler} to wait for the Future on. Use a Scheduler such as

* {@link Schedulers#io()} that can block and wait on the Future

* @param <T>

* the type of object that the {@link Future} returns, and also the type of item to be emitted by

* the resulting {@code Single}

* @return a {@code Single} that emits the item from the source {@link Future}

* @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>

*/

public final static <T> Single<T> from(Future<? extends T> future, Scheduler scheduler) {

return new Single<T>(OnSubscribeToObservableFuture.toObservableFuture(future)).subscribeOn(scheduler);

}

/**

* Returns a {@link Single} that invokes passed function and emits its result for each new Observer that subscribes.

* <p>

* Allows you to defer execution of passed function until Observer subscribes to the {@link Single}.

* It makes passed function "lazy".

* Result of the function invocation will be emitted by the {@link Single}.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code fromCallable} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param func

* function which execution should be deferred, it will be invoked when Observer will subscribe to the {@link Single}.

* @param <T>

* the type of the item emitted by the {@link Single}.

* @return a {@link Single} whose {@link Observer}s' subscriptions trigger an invocation of the given function.

*/

@Experimental

public static <T> Single<T> fromCallable(final Callable<? extends T> func) {

return create(new OnSubscribe<T>() {

@Override

public void call(SingleSubscriber<? super T> singleSubscriber) {

final T value;

try {

value = func.call();

} catch (Throwable t) {

Exceptions.throwIfFatal(t);

singleSubscriber.onError(t);

return;

}

singleSubscriber.onSuccess(value);

}

});

}

/**

* Returns a {@code Single} that emits a specified item.

* <p>

* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.just.png" alt="">

* <p>

* To convert any object into a {@code Single} that emits that object, pass that object into the

* {@code just} method.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param value

* the item to emit

* @param <T>

* the type of that item

* @return a {@code Single} that emits {@code value}

* @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>

*/

public final static <T> Single<T> just(final T value) {

// TODO add similar optimization as ScalarSynchronousObservable

return Single.create(new OnSubscribe<T>() {

@Override

public void call(SingleSubscriber<? super T> te) {

te.onSuccess(value);

}

});

}

/**

* Flattens a {@code Single} that emits a {@code Single} into a single {@code Single} that emits the item

* emitted by the nested {@code Single}, without any transformation.

* <p>

* <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.oo.png" alt="">

* <p>

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param source

* a {@code Single} that emits a {@code Single}

* @return a {@code Single} that emits the item that is the result of flattening the {@code Single} emitted

* by {@code source}

* @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>

*/

public final static <T> Single<T> merge(final Single<? extends Single<? extends T>> source) {

return Single.create(new OnSubscribe<T>() {

@Override

public void call(final SingleSubscriber<? super T> child) {

source.subscribe(new SingleSubscriber<Single<? extends T>>() {

@Override

public void onSuccess(Single<? extends T> innerSingle) {

innerSingle.subscribe(child);

}

@Override

public void onError(Throwable error) {

child.onError(error);

}

});

}

});

}

/**

* Flattens two Singles into a single Observable, without any transformation.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.png" alt="">

* <p>

* You can combine items emitted by multiple Singles so that they appear as a single Observable, by

* using the {@code merge} method.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be merged

* @param t2

* a Single to be merged

* @return an Observable that emits all of the items emitted by the source Singles

* @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>

*/

public final static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2) {

return Observable.merge(asObservable(t1), asObservable(t2));

}

/**

* Flattens three Singles into a single Observable, without any transformation.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.png" alt="">

* <p>

* You can combine items emitted by multiple Singles so that they appear as a single Observable, by using

* the {@code merge} method.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be merged

* @param t2

* a Single to be merged

* @param t3

* a Single to be merged

* @return an Observable that emits all of the items emitted by the source Singles

* @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>

*/

public final static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3) {

return Observable.merge(asObservable(t1), asObservable(t2), asObservable(t3));

}

/**

* Flattens four Singles into a single Observable, without any transformation.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.png" alt="">

* <p>

* You can combine items emitted by multiple Singles so that they appear as a single Observable, by using

* the {@code merge} method.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be merged

* @param t2

* a Single to be merged

* @param t3

* a Single to be merged

* @param t4

* a Single to be merged

* @return an Observable that emits all of the items emitted by the source Singles

* @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>

*/

public final static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4) {

return Observable.merge(asObservable(t1), asObservable(t2), asObservable(t3), asObservable(t4));

}

/**

* Flattens five Singles into a single Observable, without any transformation.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.png" alt="">

* <p>

* You can combine items emitted by multiple Singles so that they appear as a single Observable, by using

* the {@code merge} method.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be merged

* @param t2

* a Single to be merged

* @param t3

* a Single to be merged

* @param t4

* a Single to be merged

* @param t5

* a Single to be merged

* @return an Observable that emits all of the items emitted by the source Singles

* @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>

*/

public final static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5) {

return Observable.merge(asObservable(t1), asObservable(t2), asObservable(t3), asObservable(t4), asObservable(t5));

}

/**

* Flattens six Singles into a single Observable, without any transformation.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.png" alt="">

* <p>

* You can combine items emitted by multiple Singles so that they appear as a single Observable, by using

* the {@code merge} method.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be merged

* @param t2

* a Single to be merged

* @param t3

* a Single to be merged

* @param t4

* a Single to be merged

* @param t5

* a Single to be merged

* @param t6

* a Single to be merged

* @return an Observable that emits all of the items emitted by the source Singles

* @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>

*/

public final static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6) {

return Observable.merge(asObservable(t1), asObservable(t2), asObservable(t3), asObservable(t4), asObservable(t5), asObservable(t6));

}

/**

* Flattens seven Singles into a single Observable, without any transformation.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.png" alt="">

* <p>

* You can combine items emitted by multiple Singles so that they appear as a single Observable, by using

* the {@code merge} method.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be merged

* @param t2

* a Single to be merged

* @param t3

* a Single to be merged

* @param t4

* a Single to be merged

* @param t5

* a Single to be merged

* @param t6

* a Single to be merged

* @param t7

* a Single to be merged

* @return an Observable that emits all of the items emitted by the source Singles

* @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>

*/

public final static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7) {

return Observable.merge(asObservable(t1), asObservable(t2), asObservable(t3), asObservable(t4), asObservable(t5), asObservable(t6), asObservable(t7));

}

/**

* Flattens eight Singles into a single Observable, without any transformation.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.png" alt="">

* <p>

* You can combine items emitted by multiple Singles so that they appear as a single Observable, by using

* the {@code merge} method.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be merged

* @param t2

* a Single to be merged

* @param t3

* a Single to be merged

* @param t4

* a Single to be merged

* @param t5

* a Single to be merged

* @param t6

* a Single to be merged

* @param t7

* a Single to be merged

* @param t8

* a Single to be merged

* @return an Observable that emits all of the items emitted by the source Singles

* @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>

*/

public final static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7, Single<? extends T> t8) {

return Observable.merge(asObservable(t1), asObservable(t2), asObservable(t3), asObservable(t4), asObservable(t5), asObservable(t6), asObservable(t7), asObservable(t8));

}

/**

* Flattens nine Singles into a single Observable, without any transformation.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.png" alt="">

* <p>

* You can combine items emitted by multiple Singles so that they appear as a single Observable, by using

* the {@code merge} method.

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param t1

* a Single to be merged

* @param t2

* a Single to be merged

* @param t3

* a Single to be merged

* @param t4

* a Single to be merged

* @param t5

* a Single to be merged

* @param t6

* a Single to be merged

* @param t7

* a Single to be merged

* @param t8

* a Single to be merged

* @param t9

* a Single to be merged

* @return an Observable that emits all of the items emitted by the source Singles

* @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>

*/

public final static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7, Single<? extends T> t8, Single<? extends T> t9) {

return Observable.merge(asObservable(t1), asObservable(t2), asObservable(t3), asObservable(t4), asObservable(t5), asObservable(t6), asObservable(t7), asObservable(t8), asObservable(t9));

}

/**

* Returns a Single that emits the results of a specified combiner function applied to two items emitted by

* two other Singles.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.zip.png" alt="">

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param s1

* the first source Single

* @param s2

* a second source Single

* @param zipFunction

* a function that, when applied to the item emitted by each of the source Singles, results in an

* item that will be emitted by the resulting Single

* @return a Single that emits the zipped results

* @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>

*/

public static final <T1, T2, R> Single<R> zip(Single<? extends T1> s1, Single<? extends T2> s2, final Func2<? super T1, ? super T2, ? extends R> zipFunction) {

return SingleOperatorZip.zip(new Single<?>[] {s1, s2}, new FuncN<R>() {

@Override

public R call(Object... args) {

return zipFunction.call((T1) args[0], (T2) args[1]);

}

});

}

/**

* Returns a Single that emits the results of a specified combiner function applied to three items emitted

* by three other Singles.

* <p>

* <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.zip.png" alt="">

* <dl>

* <dt><b>Scheduler:</b></dt>

* <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>

* </dl>

*

* @param s1

* the first source Single

* @param s2

* a second source Single

* @param s3

* a third source Single

* @param zipFunction

* a function that, when applied to the item emitted by each of the source Singles, results in an

* item that will be emitted by the resulting Single

* @return a Single that emits the zipped results

* @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>

*/

public static final <T1, T2, T3, R> Single<R> zip(Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, final Func3<? super T1, ? super T2, ? super T3, ? extends R> zipFunction) {

return SingleOperatorZip.zip(new Single<?>[] {s1, s2, s3}, new FuncN<R>() {

@Override