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:

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).

BSON Description JVM type
BSONBinary binary data Array[Byte]
BSONBoolean boolean Boolean
BSONDBPointer deprecated in the protocol None
BSONDateTime UTC Date Time java.util.Date
BSONDouble 64-bit IEEE 754 floating point Double
BSONInteger 32-bit integer Int
BSONJavaScript JavaScript code None
BSONJavaScriptWS JavaScript scoped code None
BSONLong 64-bit integer Long
BSONMaxKey max key None
BSONMinKey min key None
BSONNull null None
BSONObjectID 12 bytes default id type in MongoDB None
BSONRegex regular expression None
BSONString UTF-8 string String
BSONSymbol deprecated in the protocol None
BSONTimestamp special date type used in MongoDB internals None
BSONUndefined deprecated in the protocol None

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

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