Reactive Scala Driver for MongoDB

Asynchronous & Non-Blocking

Overview of the ReactiveMongo BSON library

The BSON library of ReactiveMongo implements the BSON protocol, or Binary JSON, which is used by MongoDB to encode data. Because of that, when we use MongoDB we tend to manipulate a lot of BSON structures; Thus the BSON library is designed with the following points in mind:

• ease of use
• strong typing
• efficiency

Documents and values

There is one Scala class for each BSON type, all in the reactivemongo.bson package.

BSONDocument: set of key-value pairs

import reactivemongo.bson._

// BSONDocument(BSONElement*)
val doc1 = BSONDocument("foo" -> BSONString("bar"))
val doc2 = BSONDocument("lorem" -> 1)

Any type T for which a BSONWriter[T, _] is available can be used as value for a BSONElement in a BSONDocument, as in the doc2 of the previous example (see BSON typeclasses).

BSONArray: sequence of values

import reactivemongo.bson._

val arr1 = BSONArray(BSONString("foo"), BSONString("bar"))
val arr2 = BSONArray("lorem", "ipsum")

val arrField = BSONDocument("array_field" -> List("written", "values"))

As for BSONDocument, any type with a BSONWriter (see provided handlers) can be added to a BSONArray (see arr2 in the previous example). Moreover, a Traversable[T] whose element type T has a BSONWriter[T, _] can be used a BSON array (see arrField in the previous example).

The traits BSONNumberLike and BSONBooleanLike can be used to generalize the handling of numerical and boolean values.

import reactivemongo.bson.{ BSONBooleanLike, BSONDocument, BSONNumberLike }

val doc = BSONDocument("ok" -> 1.0D /* BSON double */ )

val bsonNumLike: Option[BSONNumberLike] = doc.getAs[BSONNumberLike]("ok")
val intLike: Option[Int] = bsonNumLike.map(_.toInt) // = Some(1)

val bsonBoolLike: Option[BSONBooleanLike] = doc.getAs[BSONBooleanLike]("ok")
val boolLike: Option[Boolean] = bsonBoolLike.map(_.toBoolean) // = Some(true)

All these classes extend BSONValue.

See how to handle the optional values.

A document is represented by BSONDocument, which is basically an immutable list of key-value pairs. Since it is the most used BSON type, one of the main focuses of the ReactiveMongo BSON library is to make manipulations of BSONDocument as easy as possible.

import reactivemongo.bson._

val album = BSONDocument(
  "title" -> BSONString("Everybody Knows this is Nowhere"),
  "releaseYear" -> BSONInteger(1969))

val albumTitle = album.getAs[String]("title")
albumTitle match {
  case Some(title) => println(s"The title of this album is $title")
  case _           => println("this document does not contain a title (or title is not a BSONString)")
}

Furthermore, the whole library is articulated around the concept of BSONDocumentWriter and BSONDocumentReader. These are typeclasses whose purpose is to serialize/deserialize objects of arbitrary types into/from BSON. This makes usage of MongoDB much less verbose and more natural.

Next: The readers and writers

Suggest changes