Docs Menu
Docs Home
/
Languages
/
Scala
/
Scala
/
Get Started

Primer

On this page

  • Reactive Streams
  • Observables
  • Back Pressure
  • Helpers Used in the in the Quick Start

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:

  1. Observable: a custom implementation of a Publisher

  2. Observer: a custom implementation of a Subscriber

  3. Subscription

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 the Observable is completed and returns the collected results

  • headResult(): blocks until the first result of the Observable can be returned

  • printResults(): blocks until the Observable is completed, and prints out each result

  • printHeadResult(): blocks until the first result of the Observable is available and then prints it

Back

Get Started

Next

Quick Start