Creating Observables

Creating Observables

This section explains methods that create Observables.

• toObservable( ) — convert an Iterable into an Observable
• from( ) — convert an Iterable or a Future into an Observable
• just( ) — convert an object into an Observable that emits that object
• create( ) — create an Observable from scratch by means of a function
• range( ) — create an Observable that emits a range of sequential integers
• empty( ) — create an Observable that emits nothing and then completes
• error( ) — create an Observable that emits nothing and then signals an error
• never( ) — create an Observable that emits nothing at all

toObservable( ) & from( )

convert an Iterable (or a Future) into an Observable

You can convert an object that supports the Iterable<> interface into an Observable that emits each iterable item in the object, simply by passing the object into the toObservable( ) or from( ) methods, for example:

myObservable = Observable.toObservable(myIterable);

or

myObservable = Observable.from(myIterable);

You can also do this with arrays, for example:

myArray = [1, 2, 3, 4, 5];
myArrayObservable = Observable.toObservable(myArray);

or

myArrayObservable = Observable.from(myArray);

This converts the sequence of values in the iterable object or array into a sequence of items emitted, one at a time, by an Observable.

An empty iterable (or array) can be converted to an Observable in this way. The resulting Observable will invoke onCompleted() without first invoking onNext().

The from( ) method is also capable of transforming a Future into an Observable. (This is not true of from()'s cousin toObservable( ).)

just( )

convert an object into an Observable that emits that object

To convert any object into an Observable that emits that object, pass that object into the just( ) method.

// Observable emits "some string" as a single item
def observableThatEmitsAString = Observable.just("some string"); 
// Observable emits the list [1, 2, 3, 4, 5] as a single item
def observableThatEmitsAList = Observable.just([1, 2, 3, 4, 5]); 

This has some similarities to the toObservable( ) method, but note that if you pass an iterable to toObservable( ), it will convert an iterable object into an Observable that emits each of the items in the iterable, one at a time, while the just( ) method would convert the iterable into an Observable that emits the entire iterable as a single item.

If you pass nothing or null to just( ), the resulting Observable will not merely call onCompleted( ) without calling onNext( ). It will instead call onNext( null ) before calling onCompleted( ).

create( )

create an Observable from scratch by means of a function

You can create an Observable from scratch by using the create( ) method. You pass this method a function that accepts as its parameter the Observer that is passed to an Observable’s subscribe( ) method. Write the function you pass to create( ) so that it behaves as an Observable — calling the passed-in Observer’s onNext( ), onError( ), and onCompleted( ) methods appropriately. For example:

def myObservable = Observable.create({ anObserver ->
  anObserver.onNext('One');
  anObserver.onNext('Two');
  anObserver.onNext('Three');
  anObserver.onNext('Four');
  anObserver.onCompleted();
})

NOTE: A well-formed Observable must call either the observer’s onCompleted( ) method exactly once or its onError( ) method exactly once, and must not thereafter call any of the observer’s other methods.

range( )

create an Observable that emits a range of sequential integers

To create an Observable that emits a range of sequential integers, pass the starting integer and the number of integers to emit to the range( ) method.

// myObservable emits the integers 5, 6, and 7 before completing:
def myObservable = Observable.range(5, 3);

In calls to range(m,n), values less than 1 for n will result in no numbers being emitted. m may be any integer that can be represented as a BigDecimal — posititve, negative, or zero.

empty( ), error( ), and never( )

Observables that can be useful for testing purposes

• empty( ) creates an Observable that does not emit any items but instead immediately calls the observer’s onCompleted( ) method.
• error( ) creates an Observable that does not emit any items but instead immediately calls the observer’s onError( ) method.
• never( ) creates an Observable that does not emit any items, nor does it call either the observer’s onCompleted( ) or onError( ) methods.

myWriter.println("*** empty() ***");
Observable.empty().subscribe(
  [ onNext:{ myWriter.println("empty: " + it); },
    onCompleted:{ myWriter.println("empty: Sequence complete"); },
    onError:{ myWriter.println("empty: Error encountered"); } ]
);

myWriter.println("*** error() ***");
Observable.error().subscribe(
  [ onNext:{ myWriter.println("error: " + it); },
    onCompleted:{ myWriter.println("error: Sequence complete"); },
    onError:{ myWriter.println("error: Error encountered"); } ]
);

myWriter.println("*** never() ***");
Observable.never().subscribe(
  [ onNext:{ myWriter.println("never: " + it); },
    onCompleted:{ myWriter.println("never: Sequence complete"); },
    onError:{ myWriter.println("never: Error encountered"); } ]
);
myWriter.println("*** END ***");
myWriter.flush();

*** empty() ***
empty: Sequence complete
*** error() ***
error: Error encountered
*** never() ***
*** END ***