Macros

New in 2.0, the Scala driver allows you to use case classes to represent documents in a collection via the Macros helper. Simple case classes and nested case classes are supported. Hierarchical modelling can be achieve by using a sealed trait or class and having case classes implement the parent trait.

Many simple Scala types are supported and they will be marshaled into their corresponding BsonValue type. Below is a list of Scala types and their type-safe BSON representation:

Scala type	BSON type
case class	Document
Iterable	Array
Date	Date
Boolean	Boolean
Double	Double
Int	Int32
Long	Int64
String	String
Array[Byte]	Binary
None	Null

Creating Codecs

To create a codec for your case class use the Macros object helper methods. Unless there is a good reason you should use the Macros.createCodecProvider method to create a CodecProvider. A CodecProvider will pass the configured CodecRegistry to the underlying Codec and provide access to all the configured codecs.

To create a CodecProvider all you need to do is to set the case class type when calling createCodecProvider like so:

import org.mongodb.scala.bson.codecs.Macros

case class Person(firstName: String, secondName: String)

val personCodecProvider = Macros.createCodecProvider[Person]()

The personCodecProvider can then be used when converted into a CodecRegistry by using the CodecRegistries static helpers. Below we create a new codec registry combining the new personCodecProvider and the the default codec registry:

import org.mongodb.scala.bson.codecs.DEFAULT_CODEC_REGISTRY
import org.bson.codecs.configuration.CodecRegistries.{fromRegistries, fromProviders}

val codecRegistry = fromRegistries( fromProviders(personCodecProvider), DEFAULT_CODEC_REGISTRY )

The Macros helper also has an implicit createCodecProvider method that takes the Class[T] and will create a CodecProvider from that. As you can see in the example below it’s much more concise especially when defining multiple providers:

import org.mongodb.scala.bson.codecs.Macros._
import org.mongodb.scala.bson.codecs.DEFAULT_CODEC_REGISTRY
import org.bson.codecs.configuration.CodecRegistries.{fromRegistries, fromProviders}

case class Address(firstLine: String, secondLine: String, thirdLine: String, town: String, zipCode: String)
case class ClubMember(person: Person, address: Address, paid: Boolean)

val codecRegistry = fromRegistries( fromProviders(classOf[ClubMember], classOf[Person], classOf[Address]), DEFAULT_CODEC_REGISTRY )

Sealed classes and ADTs

Hierarchical class structures are supported via sealed traits and classes. Each subclass is handled specifically by the generated codec, so you only need create a CodecProvider for the parent sealed trait/class. Internally an extra field (_t) is stored alongside the data so that the correct subclass can be hydrated when decoding the data. Below is an example of a tree like structure containing branch and leaf nodes:

sealed class Tree
case class Branch(b1: Tree, b2: Tree, value: Int) extends Tree
case class Leaf(value: Int) extends Tree

val codecRegistry = fromRegistries( fromProviders(classOf[Tree]), DEFAULT_CODEC_REGISTRY )

Options and None values.

By default Option values are always stored. In 2.1.0 a new macro helpers were added so that None values would not be stored in the database. In the following example only if an address is present will it be stored in the database:

import org.mongodb.scala.bson.codecs.Macros

case class Person(firstName: String, secondName: String, address: Option[Address])

val personCodecProvider = Macros.createCodecProviderIgnoreNone[Person]()

Alternative field names

The BsonProperty annotation can be used to configure a the bson field key to be used for a given property. In the following example uses the BsonProperty annotation to change how the firstName property is stored:

case class Person(@BsonProperty("first_name") firstName: String, secondName: String)