RxJava: Reactive Extensions for the JVM



rx.observables
Class BlockingObservable<T>

java.lang.Object
  extended by rx.observables.BlockingObservable<T>
Type Parameters:
T - the type of item emitted by the BlockingObservable

public class BlockingObservable<T>
extends java.lang.Object

An extension of Observable that provides blocking operators.

You construct a BlockingObservable from an Observable with BlockingObservable.from(Observable) or Observable.toBlocking().

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

For more information see the Blocking Observable Operators page at the RxJava Wiki.


Method Summary
 T first()
          Returns the first item emitted by this BlockingObservable, or throws NoSuchElementException if it emits no items.
 T first(Func1<? super T,java.lang.Boolean> predicate)
          Returns the first item emitted by this BlockingObservable that matches a predicate, or throws NoSuchElementException if it emits no such item.
 T firstOrDefault(T defaultValue)
          Returns the first item emitted by this BlockingObservable, or a default value if it emits no items.
 T firstOrDefault(T defaultValue, Func1<? super T,java.lang.Boolean> predicate)
          Returns the first item emitted by this BlockingObservable that matches a predicate, or a default value if it emits no such items.
 void forEach(Action1<? super T> onNext)
          Invokes a method on each item emitted by this BlockingObservable and blocks until the Observable completes.
static
<T> BlockingObservable<T>
from(Observable<? extends T> o)
          Converts an Observable into a BlockingObservable.
 java.util.Iterator<T> getIterator()
          Returns an Iterator that iterates over all items emitted by this BlockingObservable.
 T last()
          Returns the last item emitted by this BlockingObservable, or throws NoSuchElementException if this BlockingObservable emits no items.
 T last(Func1<? super T,java.lang.Boolean> predicate)
          Returns the last item emitted by this BlockingObservable that matches a predicate, or throws NoSuchElementException if it emits no such items.
 T lastOrDefault(T defaultValue)
          Returns the last item emitted by this BlockingObservable, or a default value if it emits no items.
 T lastOrDefault(T defaultValue, Func1<? super T,java.lang.Boolean> predicate)
          Returns the last item emitted by this BlockingObservable that matches a predicate, or a default value if it emits no such items.
 java.lang.Iterable<T> latest()
          Returns an Iterable that returns the latest item emitted by this BlockingObservable, waiting if necessary for one to become available.
 java.lang.Iterable<T> mostRecent(T initialValue)
          Returns an Iterable that always returns the item most recently emitted by this BlockingObservable.
 java.lang.Iterable<T> next()
          Returns an Iterable that blocks until this BlockingObservable emits another item, then returns that item.
 T single()
          If this BlockingObservable completes after emitting a single item, return that item, otherwise throw a NoSuchElementException.
 T single(Func1<? super T,java.lang.Boolean> predicate)
          If this BlockingObservable completes after emitting a single item that matches a given predicate, return that item, otherwise throw a NoSuchElementException.
 T singleOrDefault(T defaultValue)
          If this BlockingObservable completes after emitting a single item, return that item; if it emits more than one item, throw an IllegalArgumentException; if it emits no items, return a default value.
 T singleOrDefault(T defaultValue, Func1<? super T,java.lang.Boolean> predicate)
          If this BlockingObservable completes after emitting a single item that matches a predicate, return that item; if it emits more than one such item, throw an IllegalArgumentException; if it emits no items, return a default value.
 java.util.concurrent.Future<T> toFuture()
          Returns a Future representing the single value emitted by this BlockingObservable.
 java.lang.Iterable<T> toIterable()
          Converts this BlockingObservable into an Iterable.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

from

public static <T> BlockingObservable<T> from(Observable<? extends T> o)
Converts an Observable into a BlockingObservable.

Parameters:
o - the Observable you want to convert
Returns:
a BlockingObservable version of o

forEach

public void forEach(Action1<? super T> onNext)
Invokes a method on each item emitted by this BlockingObservable and blocks until the Observable completes.

Note: This will block even if the underlying Observable is asynchronous.

This is similar to Observable.subscribe(Subscriber), but it blocks. Because it blocks it does not need the Observer.onCompleted() or Observer.onError(Throwable) methods.

Parameters:
onNext - the Action1 to invoke for each item emitted by the BlockingObservable
Throws:
java.lang.RuntimeException - if an error occurs
See Also:
RxJava Wiki: forEach()

getIterator

public java.util.Iterator<T> getIterator()
Returns an Iterator that iterates over all items emitted by this BlockingObservable.

Returns:
an Iterator that can iterate over the items emitted by this BlockingObservable
See Also:
RxJava Wiki: getIterator()

first

public T first()
Returns the first item emitted by this BlockingObservable, or throws NoSuchElementException if it emits no items.

Returns:
the first item emitted by this BlockingObservable
Throws:
java.util.NoSuchElementException - if this BlockingObservable emits no items
See Also:
RxJava Wiki: first(), MSDN: Observable.First

first

public T first(Func1<? super T,java.lang.Boolean> predicate)
Returns the first item emitted by this BlockingObservable that matches a predicate, or throws NoSuchElementException if it emits no such item.

Parameters:
predicate - a predicate function to evaluate items emitted by this BlockingObservable
Returns:
the first item emitted by this BlockingObservable that matches the predicate
Throws:
java.util.NoSuchElementException - if this BlockingObservable emits no such items
See Also:
RxJava Wiki: first(), MSDN: Observable.First

firstOrDefault

public T firstOrDefault(T defaultValue)
Returns the first item emitted by this BlockingObservable, or a default value if it emits no items.

Parameters:
defaultValue - a default value to return if this BlockingObservable emits no items
Returns:
the first item emitted by this BlockingObservable, or the default value if it emits no items
See Also:
RxJava Wiki: firstOrDefault(), MSDN: Observable.FirstOrDefault

firstOrDefault

public T firstOrDefault(T defaultValue,
                        Func1<? super T,java.lang.Boolean> predicate)
Returns the first item emitted by this BlockingObservable that matches a predicate, or a default value if it emits no such items.

Parameters:
defaultValue - a default value to return if this BlockingObservable emits no matching items
predicate - a predicate function to evaluate items emitted by this BlockingObservable
Returns:
the first item emitted by this BlockingObservable that matches the predicate, or the default value if this BlockingObservable emits no matching items
See Also:
RxJava Wiki: firstOrDefault(), MSDN: Observable.FirstOrDefault

last

public T last()
Returns the last item emitted by this BlockingObservable, or throws NoSuchElementException if this BlockingObservable emits no items.

Returns:
the last item emitted by this BlockingObservable
Throws:
java.util.NoSuchElementException - if this BlockingObservable emits no items
See Also:
RxJava Wiki: last(), MSDN: Observable.Last

last

public T last(Func1<? super T,java.lang.Boolean> predicate)
Returns the last item emitted by this BlockingObservable that matches a predicate, or throws NoSuchElementException if it emits no such items.

Parameters:
predicate - a predicate function to evaluate items emitted by the BlockingObservable
Returns:
the last item emitted by the BlockingObservable that matches the predicate
Throws:
java.util.NoSuchElementException - if this BlockingObservable emits no items
See Also:
RxJava Wiki: last(), MSDN: Observable.Last

lastOrDefault

public T lastOrDefault(T defaultValue)
Returns the last item emitted by this BlockingObservable, or a default value if it emits no items.

Parameters:
defaultValue - a default value to return if this BlockingObservable emits no items
Returns:
the last item emitted by the BlockingObservable, or the default value if it emits no items
See Also:
RxJava Wiki: lastOrDefault(), MSDN: Observable.LastOrDefault

lastOrDefault

public T lastOrDefault(T defaultValue,
                       Func1<? super T,java.lang.Boolean> predicate)
Returns the last item emitted by this BlockingObservable that matches a predicate, or a default value if it emits no such items.

Parameters:
defaultValue - a default value to return if this BlockingObservable emits no matching items
predicate - a predicate function to evaluate items emitted by this BlockingObservable
Returns:
the last item emitted by this BlockingObservable that matches the predicate, or the default value if it emits no matching items
See Also:
RxJava Wiki: lastOrDefault(), MSDN: Observable.LastOrDefault

mostRecent

public java.lang.Iterable<T> mostRecent(T initialValue)
Returns an Iterable that always returns the item most recently emitted by this BlockingObservable.

Parameters:
initialValue - the initial value that the Iterable sequence will yield if this BlockingObservable has not yet emitted an item
Returns:
an Iterable that on each iteration returns the item that this BlockingObservable has most recently emitted
See Also:
RxJava wiki: mostRecent(), MSDN: Observable.MostRecent

next

public java.lang.Iterable<T> next()
Returns an Iterable that blocks until this BlockingObservable emits another item, then returns that item.

Returns:
an Iterable that blocks upon each iteration until this BlockingObservable emits a new item, whereupon the Iterable returns that item
See Also:
RxJava Wiki: next(), MSDN: Observable.Next

latest

public java.lang.Iterable<T> latest()
Returns an Iterable that returns the latest item emitted by this BlockingObservable, waiting if necessary for one to become available.

If this BlockingObservable produces items faster than Iterator.next takes them, onNext events might be skipped, but onError or onCompleted events are not.

Note also that an onNext directly followed by onCompleted might hide the onNext event.

Returns:
an Iterable that always returns the latest item emitted by this BlockingObservable
See Also:
RxJava wiki: latest(), MSDN: Observable.Latest

single

public T single()
If this BlockingObservable completes after emitting a single item, return that item, otherwise throw a NoSuchElementException.

Returns:
the single item emitted by this BlockingObservable
See Also:
RxJava Wiki: single(), MSDN: Observable.Single

single

public T single(Func1<? super T,java.lang.Boolean> predicate)
If this BlockingObservable completes after emitting a single item that matches a given predicate, return that item, otherwise throw a NoSuchElementException.

Parameters:
predicate - a predicate function to evaluate items emitted by this BlockingObservable
Returns:
the single item emitted by this BlockingObservable that matches the predicate
See Also:
RxJava Wiki: single(), MSDN: Observable.Single

singleOrDefault

public T singleOrDefault(T defaultValue)
If this BlockingObservable completes after emitting a single item, return that item; if it emits more than one item, throw an IllegalArgumentException; if it emits no items, return a default value.

Parameters:
defaultValue - a default value to return if this BlockingObservable emits no items
Returns:
the single item emitted by this BlockingObservable, or the default value if it emits no items
See Also:
RxJava Wiki: singleOrDefault(), MSDN: Observable.SingleOrDefault

singleOrDefault

public T singleOrDefault(T defaultValue,
                         Func1<? super T,java.lang.Boolean> predicate)
If this BlockingObservable completes after emitting a single item that matches a predicate, return that item; if it emits more than one such item, throw an IllegalArgumentException; if it emits no items, return a default value.

Parameters:
defaultValue - a default value to return if this BlockingObservable emits no matching items
predicate - a predicate function to evaluate items emitted by this BlockingObservable
Returns:
the single item emitted by the BlockingObservable that matches the predicate, or the default value if no such items are emitted
See Also:
RxJava Wiki: singleOrDefault(), MSDN: Observable.SingleOrDefault

toFuture

public java.util.concurrent.Future<T> toFuture()
Returns a Future representing the single value emitted by this BlockingObservable.

If BlockingObservable emits more than one item, Future will receive an IllegalArgumentException. If BlockingObservable is empty, Future will receive an NoSuchElementException.

If the BlockingObservable may emit more than one item, use Observable.toList().toBlocking().toFuture().

Returns:
a Future that expects a single item to be emitted by this BlockingObservable
See Also:
RxJava Wiki: toFuture()

toIterable

public java.lang.Iterable<T> toIterable()
Converts this BlockingObservable into an Iterable.

Returns:
an Iterable version of this BlockingObservable
See Also:
RxJava Wiki: toIterable()