reactivemongo.api.bson

BSON main API

import reactivemongo.api.bson._

// { "name": "Johny", "surname": "Doe", "age": 28, "months": [1, 2, 3] }
BSONDocument.empty ++ ("name" -> "Johny") ++ ("surname" -> "Doe") ++
("age" -> 28) ++ ("months" -> array(1, 2, 3))

// { "_id": generatedId, "name": "Jane", "surname": "Doe", "age": 28,
//   "months": [1, 2, 3], "details": { "salary": 12345,
//   "inventory": ["foo", 7.8, 0, false] } }
document.++("_id" -> generateId, "name" -> "Jane", "surname" -> "Doe",
 "age" -> 28, "months" -> array(1, 2, 3),
 "details" -> document(
   "salary" -> 12345L, "inventory" -> array("foo", 7.8, 0L, false)))

'''System properties:'''

The following properties can be set (e.g. using JVM -D options).

  • reactivemongo.api.bson.bufferSizeBytes (integer; default: 96): Number of bytes used as initial size when allocating a new buffer.
  • reactivemongo.api.bson.document.strict (boolean; default: false): Flag to enable strict reading of document (filter duplicate fields, see BSONDocument.asStrict).

Type members

Classlikes

object BSON

Utility functions

Utility functions

sealed abstract class BSONArray extends BSONValue

A BSONArray (type 0x04) is a indexed sequence of BSONValue.

A BSONArray (type 0x04) is a indexed sequence of BSONValue.

import reactivemongo.api.bson._

BSONArray(BSONString("foo"), BSONDouble(1.2D))
Companion:
object
object BSONArray

BSONArray utilities

BSONArray utilities

import reactivemongo.api.bson.{ BSONArray, BSONString }

BSONArray("foo", 1) match {
 case BSONArray(BSONString(s) +: _) => s == "foo"
 case _ => false
}
Companion:
class
final class BSONBinary extends BSONValue

A BSON binary value.

A BSON binary value.

import reactivemongo.api.bson.{ BSONBinary, Subtype }

BSONBinary("foo".getBytes("UTF-8"), Subtype.GenericBinarySubtype)
Value parameters:
subtype

The type of the binary content.

value

The binary content.

Companion:
object
object BSONBinary

BSONBinary utilities

BSONBinary utilities

import reactivemongo.api.bson.{ BSONBinary, Subtype }

val bin1 = BSONBinary(
 "foo".getBytes("UTF-8"), Subtype.GenericBinarySubtype)

// See Subtype.UuidSubtype
val uuid = BSONBinary(java.util.UUID.randomUUID())
Companion:
class
final class BSONBoolean extends BSONValue

BSON boolean value

BSON boolean value

Companion:
object

BSONBoolean factories & utilities

BSONBoolean factories & utilities

Companion:
class
sealed trait BSONBooleanLike

A BSON value that can be seen as a boolean.

A BSON value that can be seen as a boolean.

Conversions:

  • number = 0 ~> false
  • number != 0 ~> true
  • boolean
  • undefined ~> false
  • null ~> false
import scala.util.Success
import reactivemongo.api.bson.{ BSONBooleanLike, BSONDocument, BSONInteger }

val bi = BSONInteger(1)
assert(bi.asTry[BSONBooleanLike].flatMap(_.toBoolean) == Success(true))

val doc = BSONDocument("field" -> bi)
assert(doc.getAsTry[BSONBooleanLike]("field").
 flatMap(_.toBoolean) == Success(true))
Companion:
object

BSONBooleanLike utilities

BSONBooleanLike utilities

Companion:
class
final class BSONDateTime extends BSONValue

BSON date time value

BSON date time value

Companion:
object

BSONDateTime factories & utilities

BSONDateTime factories & utilities

Companion:
class
final class BSONDecimal extends BSONValue

Value wrapper for a BSON 128-bit decimal.

Value wrapper for a BSON 128-bit decimal.

Value parameters:
high

the high-order 64 bits

low

the low-order 64 bits

Companion:
object

BSONDecimal factories & utilities

BSONDecimal factories & utilities

Companion:
class
sealed abstract class BSONDocument extends BSONValue with ElementProducer

A BSONDocument structure (BSON type 0x03).

A BSONDocument structure (BSON type 0x03).

A BSONDocument is an unordered set of fields (String, BSONValue).

'''Note:''' The insertion/initial order of the fields may not be maintained through the operations.

Companion:
object

BSONDocument factories & utilities.

BSONDocument factories & utilities.

reactivemongo.api.bson.BSONDocument("foo" -> 1, "bar" -> "lorem")
Companion:
class

Reads and writers T values to/from BSONDocument.

Reads and writers T values to/from BSONDocument.

Companion:
object
trait BSONDocumentReader[T] extends BSONReader[T]

BSONReader specialized for BSONDocument

BSONReader specialized for BSONDocument

Companion:
object
trait BSONDocumentWriter[T] extends BSONWriter[T]

BSONWriter specialized for BSONDocument

BSONWriter specialized for BSONDocument

Companion:
object

BSONDocumentWriter factories.

BSONDocumentWriter factories.

Companion:
class
final class BSONDouble extends BSONValue

A BSON Double.

A BSON Double.

reactivemongo.api.bson.BSONDouble(1.23D)
Companion:
object
object BSONDouble

BSONDouble utilities

BSONDouble utilities

import reactivemongo.api.bson.BSONDouble

BSONDouble(1.23D) match {
 case BSONDouble(v) => assert(v == 1.23D)
 case _ => ???
}
Companion:
class
sealed abstract class BSONElement extends ElementProducer

BSON element, typically a pair of name and BSONValue.

BSON element, typically a pair of name and BSONValue.

import reactivemongo.api.bson.{ BSONElement, BSONString }

BSONElement("name", BSONString("value"))
Companion:
object

BSONElement factories and utilities.

BSONElement factories and utilities.

Companion:
class
trait BSONHandler[T] extends BSONReader[T] with BSONWriter[T]

A BSON handler is able to both read and write T values from/to BSON representation.

A BSON handler is able to both read and write T values from/to BSON representation.

import scala.util.Try
import reactivemongo.api.bson.{ BSONHandler, BSONValue }

def roundtrip[T](value: T)(implicit handler: BSONHandler[T]): Try[Boolean] =
 for {
   bson: BSONValue <- handler.writeTry(value)
   dser <- handler.readTry(bson)
 } yield (dser == value) // true
Companion:
object

BSONHandler factories

BSONHandler factories

Companion:
class
final class BSONInteger extends BSONValue

BSON Integer value

BSON Integer value

Companion:
object

BSONInteger factories & utilities

BSONInteger factories & utilities

Companion:
class
final class BSONJavaScript extends BSONValue

BSON JavaScript value.

BSON JavaScript value.

Value parameters:
value

The JavaScript source code.

Companion:
object

BSONJavaScript factories & utilities

BSONJavaScript factories & utilities

Companion:
class
final class BSONJavaScriptWS extends BSONValue

BSON JavaScript value with scope (WS).

BSON JavaScript value with scope (WS).

Value parameters:
value

The JavaScript source code.

Companion:
object

BSONJavaScriptWS factories & utilities

BSONJavaScriptWS factories & utilities

Companion:
class
final class BSONLong extends BSONValue

BSON Long value

BSON Long value

Companion:
object
object BSONLong

BSONLong factories & utilities

BSONLong factories & utilities

Companion:
class
sealed trait BSONMaxKey extends BSONValue

BSON Max key value

BSON Max key value

Companion:
object
object BSONMaxKey extends BSONMaxKey
Companion:
class
sealed trait BSONMinKey extends BSONValue

BSON Min key value

BSON Min key value

Companion:
object
object BSONMinKey extends BSONMinKey
Companion:
class
sealed trait BSONNull extends BSONValue

BSON null value

BSON null value

Companion:
object
object BSONNull extends BSONNull
Companion:
class
sealed trait BSONNumberLike

A BSON value that can be seen as a number.

A BSON value that can be seen as a number.

Conversions:

import scala.util.Success
import reactivemongo.api.bson.{ BSONNumberLike, BSONDocument, BSONInteger }

val bi = BSONInteger(1)
assert(bi.asTry[BSONNumberLike].flatMap(_.toLong) == Success(1L))

val doc = BSONDocument("field" -> bi)
assert(doc.getAsTry[BSONNumberLike]("field").
 flatMap(_.toDouble) == Success(1D))
Companion:
object

BSONNumberLike utilities

BSONNumberLike utilities

Companion:
class
sealed abstract class BSONObjectID extends BSONValue

BSON ObjectId value.

import scala.util.Try
import reactivemongo.api.bson.BSONObjectID

val oid: BSONObjectID = BSONObjectID.generate()

def foo: Try[BSONObjectID] = BSONObjectID.parse(oid.stringify)
Timestamp (seconds)Machine identifierThread identifierIncrement
4 bytes3 bytes2 bytes3 bytes
Companion:
object

BSONObjectID utilities

BSONObjectID utilities

Companion:
class
trait BSONReader[T]

A reader that produces an instance of T from a subtype of BSONValue.

A reader that produces an instance of T from a subtype of BSONValue.

Companion:
object
object BSONReader

BSONReader factories

BSONReader factories

Companion:
class
final class BSONRegex extends BSONValue

BSON Regex value.

BSON Regex value.

Value parameters:
flags

the regex flags

value

the regex value (expression)

Companion:
object
object BSONRegex

BSONRegex factories & utilities

BSONRegex factories & utilities

Companion:
class
sealed abstract class BSONStrictDocument extends BSONDocument

'''EXPERIMENTAL:''' Strict documentation representation with at most one value per field name (no duplicate).

'''EXPERIMENTAL:''' Strict documentation representation with at most one value per field name (no duplicate).

import reactivemongo.api.bson.BSONDocument

def strict1 = // { 'foo': 1 }
 BSONDocument.strict("foo" -> 1, "foo" -> 2)

def strict2 = BSONDocument("foo" -> 1, "foo" -> 2).asStrict

assert(strict1 == strict2)
final class BSONString extends BSONValue

A BSON string.

reactivemongo.api.bson.BSONString("foo")
Companion:
object
object BSONString

BSONString utilities

BSONString utilities

import reactivemongo.api.bson.BSONString

BSONString("foo") match {
 case BSONString(v) => v == "foo"
 case _ => false
}
Companion:
class
final class BSONSymbol extends BSONValue

BSON Symbol value.

BSON Symbol value.

Value parameters:
value

the symbol value (name)

Companion:
object
object BSONSymbol

BSONSymbol factories & utilities

BSONSymbol factories & utilities

Companion:
class
sealed abstract class BSONTimestamp extends BSONValue
Companion:
object

Timestamp companion

Timestamp companion

Companion:
class
sealed trait BSONUndefined extends BSONValue

BSON undefined value

BSON undefined value

Companion:
object

Single value for BSONUndefined type

Single value for BSONUndefined type

Companion:
class
sealed trait BSONValue

A BSON value

A BSON value

Companion:
object
object BSONValue

BSONValue factories and utilities

BSONValue factories and utilities

Companion:
class
trait BSONWriter[T]

A writer that produces a subtype of BSONValue from an instance of T.

A writer that produces a subtype of BSONValue from an instance of T.

Companion:
object
object BSONWriter

BSONWriter factories.

BSONWriter factories.

Companion:
class
sealed trait DocumentClass[T]

Evidence that T can be serialized as a BSON document.

Evidence that T can be serialized as a BSON document.

Companion:
object
sealed trait ElementProducer extends Producer[BSONElement]
Companion:
object
Companion:
class
trait FieldNaming extends String => String

Naming strategy, to map each class property to the corresponding field.

Naming strategy, to map each class property to the corresponding field.

import reactivemongo.api.bson.{ FieldNaming, MacroConfiguration }

def initCfg(naming: FieldNaming): MacroConfiguration =
 MacroConfiguration(fieldNaming = naming)
See also:
Companion:
object

Naming companion

Naming companion

Companion:
class
final class IsNot[A, B]()

Type level evidence that type A is not type B.

Type level evidence that type A is not type B.

Companion:
object
object IsNot
Companion:
class
trait KeyReader[T]

Mapping from a BSON string to T; Used by scala.collection.Map handlers.

Mapping from a BSON string to T; Used by scala.collection.Map handlers.

final class Foo(val v: String) extends AnyVal

val bson = reactivemongo.api.bson.BSONDocument(
 "foo:key" -> 1, "foo:name" -> 2)

import reactivemongo.api.bson.KeyReader

implicit def fooKeyReader: KeyReader[Foo] =
 KeyReader[Foo] { str =>
   new Foo(str.stripPrefix("foo:"))
 }

reactivemongo.api.bson.BSON.readDocument[Map[Foo, Int]](bson)
// Success: Map[Foo, Int](
//  (new Foo("key") -> 1),
//  (new Foo("name") -> 2))
Companion:
object
object KeyReader
Companion:
class
trait KeyWriter[T]

Mapping from a BSON string to T. Used by scala.collection.Map handlers.

Mapping from a BSON string to T. Used by scala.collection.Map handlers.

final class Foo(val v: String) extends AnyVal

val dict = Map[Foo, Int](
 (new Foo("key") -> 1),
 (new Foo("name") -> 2))

import reactivemongo.api.bson.KeyWriter

implicit def fooKeyWriter: KeyWriter[Foo] =
 KeyWriter[Foo] { foo =>
   "foo:" + foo.v
 }

reactivemongo.api.bson.BSON.writeDocument(dict)
// Success = {'foo:key': 1, 'foo:name': 2}
Companion:
object
object KeyWriter

KeyWriter factories

KeyWriter factories

Companion:
class
sealed trait MacroConfiguration

Macro configuration;

Macro configuration;

It allows to configure compile time options, and behaviour to be retained at runtime (field & type naming).

import reactivemongo.api.bson.{
 BSONDocumentReader, MacroConfiguration, Macros
}

case class Foo(name: String)

val r1: BSONDocumentReader[Foo] = Macros.configured.reader[Foo]

val r2: BSONDocumentReader[Foo] = Macros.configured(
 MacroConfiguration.simpleTypeName).reader[Foo]

See also:
Companion:
object

MacroConfiguration factories and utilities

MacroConfiguration factories and utilities

Companion:
class
sealed trait MacroOptions

Macros with 'Opts' suffix will take additional options in the form of type parameters that will customize behaviour of the macros during compilation.

Macros with 'Opts' suffix will take additional options in the form of type parameters that will customize behaviour of the macros during compilation.

import reactivemongo.api.bson.{ BSONDocumentWriter, Macros, MacroOptions }

case class Bar(score: Float)

val w: BSONDocumentWriter[Bar] =
 Macros.using[MacroOptions.Default].writer[Bar]
Companion:
object

MacroOptions factories & utilities.

MacroOptions factories & utilities.

Companion:
class
object Macros

Macros for generating BSONReader and BSONWriter at compile time.

Macros for generating BSONReader and BSONWriter at compile time.

import reactivemongo.api.bson.Macros

case class Person(name: String, surname: String)

implicit val personHandler = Macros.handler[Person]
See also:

MacroOptions for specific options

MacroConfiguration for extended configuration

sealed trait OpaqueAlias[T]
Companion:
object
Companion:
class
sealed trait Producer[T]
object Sandbox
sealed trait SomeTypeclass[T]
Companion:
object
Companion:
class
sealed trait Subtype

Binary Subtype

Binary Subtype

Companion:
object
object Subtype
Companion:
class
trait TypeNaming extends Class[_] => String

Naming strategy, to map each class to a discriminator value.

Naming strategy, to map each class to a discriminator value.

import reactivemongo.api.bson.{ MacroConfiguration, TypeNaming }

val cfg1 = MacroConfiguration(typeNaming = TypeNaming.FullName)

val cfg2 = MacroConfiguration(typeNaming = TypeNaming.FullName)

val cfg3 = MacroConfiguration(
 typeNaming = TypeNaming { (cls: Class[_]) =>
   "_" + cls.getSimpleName
 })
See also:
Companion:
object
object TypeNaming

TypeNaming factories

TypeNaming factories

Companion:
class
@SuppressWarnings(scala.Array.apply[java.lang.String]("ClassNames")(scala.reflect.ClassTag.apply[java.lang.String](classOf[java.lang.String])))
final class ¬[A, B]

Type level evidence that type A is not type B.

Type level evidence that type A is not type B.

Companion:
object
@SuppressWarnings(scala.Array.apply[java.lang.String]("ObjectNames")(scala.reflect.ClassTag.apply[java.lang.String](classOf[java.lang.String])))
object ¬
Companion:
class

Inherited classlikes

abstract protected class BSONArrayCollectionReader[M[_], T] extends BSONReader[M[T]]
protected class BSONArrayCollectionWriter[T, Repr](implicit ev: Repr => Iterable[T], writer: BSONWriter[T]) extends BSONWriter[Repr]
object BSONDateTimeHandler extends BSONHandler[Instant]
Inherited from:
DefaultBSONHandlers
object BSONLocalTimeHandler extends BSONHandler[LocalTime]
Inherited from:
DefaultBSONHandlers
object BSONLocaleHandler extends BSONHandler[Locale]
Inherited from:
DefaultBSONHandlers
Inherited from:
DefaultBSONHandlers
object BSONURIHandler extends BSONHandler[URI]
Inherited from:
DefaultBSONHandlers
object BSONURLHandler extends BSONHandler[URL]
Inherited from:
DefaultBSONHandlers
object BSONUUIDHandler extends BSONHandler[UUID]
Inherited from:
DefaultBSONHandlers

Inherited types

type BaseColl[T] = Iterable[T]
Inherited from:
Aliases
Inherited from:
Aliases

Value members

Concrete methods

Returns a BSON Null value

Returns a BSON Null value

Returns an empty array.

Returns an empty array.

import reactivemongo.api.bson._

val arr1 = BSONString("bar") +: array // [ 'bar' ]
val arr2 = BSONInteger(1) +: arr1 // [ 1, 'bar' ]

Returns an array with given values.

Returns an array with given values.

import reactivemongo.api.bson._

val arr = array("bar", 1L) // [ 'bar', NumberLong(1) ]

Returns an empty document.

Returns an empty document.

import reactivemongo.api.bson._

val doc = document ++ ("foo" -> 1)
// { 'foo': 1 }

Returns a document with given elements.

Returns a document with given elements.

import reactivemongo.api.bson._

val doc = document("foo" -> 1)
// { 'foo': 1 }

Returns a newly generated object ID.

Returns a newly generated object ID.

Returns a BSON MaxKey value

Returns a BSON MaxKey value

Returns a BSON MinKey value

Returns a BSON MinKey value

Returns a BSON Undefined value

Returns a BSON Undefined value

Inherited methods

inline def migrationRequired[A](inline details: String): A

Keeps a A statement but raise a migration error at compile-time.

Keeps a A statement but raise a migration error at compile-time.

The compilation error can be disabled by setting the system property reactivemongo.api.migrationRequired.nonFatal to true.

Inherited from:
PackageCompat

Inherited fields

Inherited from:
DefaultBSONHandlers
Inherited from:
DefaultBSONHandlers
Inherited from:
DefaultBSONHandlers
Inherited from:
DefaultBSONHandlers

Givens

Inherited givens

given collectionWriter[T, Repr <: Iterable[T]](using BSONWriter[T], Repr ¬ Option[T]): BSONWriter[Repr]
Inherited from:
LowPriority1BSONHandlers

Implicits

Implicits

implicit def nameValueOrdering[T <: BSONValue]: Ordering[(String, T)]

Key/value ordering

Key/value ordering

import reactivemongo.api.bson.{ BSONString, nameValueOrdering }

Seq("foo" -> BSONString("1"), "bar" -> BSONString("1")).
 sorted // == [ "bar" -> .., "foo" -> .. ]

Inherited implicits

Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
Inherited from:
BSONIdentityHandlers
final implicit def collectionReader[M[_], T](implicit f: Factory[T, M[T]], reader: BSONReader[T]): BSONReader[M[T]]
Inherited from:
LowPriority1BSONHandlers