This guide provides background about the Scala driver and its asynchronous API before showing you how to use the driver and MongoDB in the Quick Start guide.
Note
See the Installation guide for instructions on how to install the driver.
Reactive Streams
The Scala driver is built upon the MongoDB Java Reactive Streams driver. The reactive stream API consists of the following components:
Observable: a custom implementation of a PublisherObserver: a custom implementation of a Subscriber
An Observable is a provider of a potentially unbounded number of
sequenced elements, published according to the demand received from its
Observer or multiple instances of Observer.
In response to a call to Observable.subscribe(Observer), the
possible invocation sequences for methods on the Observer class
are given by the following protocol:
onSubscribe onNext* (onError | onComplete)?
This means that onSubscribe() is always
signaled, followed by a possibly unbounded number
of onNext() signals, as requested by
Observer. This is followed by an onError() signal
if there is a failure or an onComplete() signal
when no more elements are available, as long as
the Subscription is not canceled.
Tip
To learn more about reactive streams, visit the Reactive Streams documentation.
Observables
The Scala driver API mirrors the Java Sync driver API and any methods that cause network
I/O to return an Observable<T> type, where T is the type of response
for the operation.
Note
All Observable types returned from the API are
cold,
meaning that nothing happens until they are subscribed to. So just
creating an Observable won’t cause any network I/O. It’s not until
you call the Subscription.request() method that the driver executes
the operation.
Publishers in this implementation are unicast. Each
Subscription to an Observable relates to a single MongoDB
operation, and the Observable instance's Observer receives its
own specific set of results.
Back Pressure
By default, the Observer trait will request all the results from the
Observer as soon as the Observable is subscribed to. Ensure that
the Observer can handle all the results from the
Observable. Custom implementations of the Observer.onSubscribe()
method can save the Subscription so that data is only
requested when the Observer has the capacity.
Helpers Used in the in the Quick Start
In the Quick Start, we have implemented custom implicit helpers defined
in the Helpers.scala
file in the driver source GitHub repository.
These helpers retrieve and print results. Though the Quick Start is an
artificial scenario for asynchronous code, the examples block on the
results of one example before starting the next, to ensure the
state of the database. The Helpers object provides the following
methods:
results(): blocks until theObservableis completed and returns the collected resultsheadResult(): blocks until the first result of theObservablecan be returnedprintResults(): blocks until theObservableis completed, and prints out each resultprintHeadResult(): blocks until the first result of theObservableis available and then prints it