Class BlockingObservable<T>

  • Type Parameters:
    T - the type of item emitted by the BlockingObservable

    public final class BlockingObservable<T>
    extends java.lang.Object
    BlockingObservable is a variety of Observable that provides blocking operators. It can be useful for testing and demo purposes, but is generally inappropriate for production applications (if you think you need to use a BlockingObservable this is usually a sign that you should rethink your design).

    You construct a BlockingObservable from an Observable with 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:

    See Also:
    RxJava wiki: Blocking Observable Operators
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private Observable<? extends T> o  
      (package private) static java.lang.Object ON_START
      Constant to indicate the onStart method should be called.
      (package private) static java.lang.Object SET_PRODUCER
      Constant indicating the setProducer method should be called.
      (package private) static java.lang.Object UNSUBSCRIBE
      Indicates an unsubscription happened
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private T blockForSingle​(Observable<? extends T> observable)
      Helper method which handles the actual blocking for a single response.
      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.
      void subscribe()
      Runs the source observable to a terminal event, ignoring any values and rethrowing any exception.
      void subscribe​(Action1<? super T> onNext)
      Subscribes to the source and calls the given action on the current thread and rethrows any exception wrapped into OnErrorNotImplementedException.
      void subscribe​(Action1<? super T> onNext, Action1<? super java.lang.Throwable> onError)
      Subscribes to the source and calls the given actions on the current thread.
      void subscribe​(Action1<? super T> onNext, Action1<? super java.lang.Throwable> onError, Action0 onCompleted)
      Subscribes to the source and calls the given actions on the current thread.
      void subscribe​(Observer<? super T> observer)
      Subscribes to the source and calls back the Observer methods on the current thread.
      void subscribe​(Subscriber<? super T> subscriber)
      Subscribes to the source and calls the Subscriber methods on the current thread.
      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
    • Field Detail

      • ON_START

        static final java.lang.Object ON_START
        Constant to indicate the onStart method should be called.
      • SET_PRODUCER

        static final java.lang.Object SET_PRODUCER
        Constant indicating the setProducer method should be called.
      • UNSUBSCRIBE

        static final java.lang.Object UNSUBSCRIBE
        Indicates an unsubscription happened
    • Constructor Detail

      • BlockingObservable

        private BlockingObservable​(Observable<? extends T> o)
    • Method Detail

      • from

        public static <T> BlockingObservable<T> from​(Observable<? extends T> o)
        Converts an Observable into a BlockingObservable.
        Type Parameters:
        T - the observed value type
        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. If the underlying Observable terminates with an error, rather than calling onError, this method will throw an exception.

        The difference between this method and subscribe(Action1) is that the onNext action is executed on the emission thread instead of the current thread.

        Parameters:
        onNext - the Action1 to invoke for each item emitted by the BlockingObservable
        Throws:
        java.lang.RuntimeException - if an error occurs
        See Also:
        ReactiveX documentation: Subscribe, subscribe(Action1)
      • 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:
        ReactiveX documentation: To
      • 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:
        ReactiveX documentation: 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:
        ReactiveX documentation: 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:
        ReactiveX documentation: First
      • 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:
        ReactiveX documentation: First
      • 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:
        ReactiveX documentation: 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:
        ReactiveX documentation: 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:
        ReactiveX documentation: Last
      • 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:
        ReactiveX documentation: Last
      • 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:
        ReactiveX documentation: First
      • 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:
        ReactiveX documentation: TakeLast
      • 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:
        ReactiveX documentation: First
      • 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:
        ReactiveX documentation: First
      • 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:
        ReactiveX documentation: First
      • 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:
        ReactiveX documentation: First
      • 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:
        ReactiveX documentation: First
      • 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:
        ReactiveX documentation: To
      • toIterable

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

        Returns:
        an Iterable version of this BlockingObservable
        See Also:
        ReactiveX documentation: To
      • blockForSingle

        private T blockForSingle​(Observable<? extends T> observable)
        Helper method which handles the actual blocking for a single response.

        If the Observable errors, it will be thrown right away.

        Returns:
        the actual item
      • subscribe

        @Experimental
        public void subscribe()
        Runs the source observable to a terminal event, ignoring any values and rethrowing any exception.
      • subscribe

        @Experimental
        public void subscribe​(Observer<? super T> observer)
        Subscribes to the source and calls back the Observer methods on the current thread.
        Parameters:
        observer - the observer to call event methods on
      • subscribe

        @Experimental
        public void subscribe​(Subscriber<? super T> subscriber)
        Subscribes to the source and calls the Subscriber methods on the current thread.

        The unsubscription and backpressure is composed through.

        Parameters:
        subscriber - the subscriber to forward events and calls to in the current thread
      • subscribe

        @Experimental
        public void subscribe​(Action1<? super T> onNext)
        Subscribes to the source and calls the given action on the current thread and rethrows any exception wrapped into OnErrorNotImplementedException.

        The difference between this method and forEach(Action1) is that the action is always executed on the current thread.

        Parameters:
        onNext - the callback action for each source value
        See Also:
        forEach(Action1)
      • subscribe

        @Experimental
        public void subscribe​(Action1<? super T> onNext,
                              Action1<? super java.lang.Throwable> onError)
        Subscribes to the source and calls the given actions on the current thread.
        Parameters:
        onNext - the callback action for each source value
        onError - the callback action for an error event
      • subscribe

        @Experimental
        public void subscribe​(Action1<? super T> onNext,
                              Action1<? super java.lang.Throwable> onError,
                              Action0 onCompleted)
        Subscribes to the source and calls the given actions on the current thread.
        Parameters:
        onNext - the callback action for each source value
        onError - the callback action for an error event
        onCompleted - the callback action for the completion event.