BsonFactory

interface BsonFactory

Entrypoint for creating BsonDocument and BsonArray instances.

Navigating BSON types

This interface is part of the BSON trinity:

• BsonDocument represents an entire BSON document.

• BsonArray represents an array of BSON values.

• BsonValue represents a single value in isolation.

Serialization

This interface encapsulates the configuration of the serialization library in use.

For example, if you use the official java or Kotlin MongoDB drivers, all BSON values built by this factory will respect the configured CodecRegistry.

Usage

To create the following BSON document:

{
    "name": "Bob",
    "isAlive": true,
    "children": [
        {
            "name": "Alice"
        },
        {
            "name": "Charles"
        }
    ]
}

use the code:

val document = factory.buildDocument {
    writeString("name", "Alice")
    writeBoolean("isAlive", true)
    writeArray("children") {
        writeDocument {
            writeString("name", "Alice")
        }
        writeDocument {
            writeString("name", "Charles")
        }
    }
}

The value can then be read into Kotlin types:

data class User(
    val name: String,
    val isAlive: Boolean,
    val children: List<Child>,
)

data class Child(
    val name: String,
)

val user = document.decode<User>()

println(user.children[0].name)  // Alice

Functions

buildArray

@LowLevelApi
abstract fun buildArray(block: BsonValueWriter.() -> Unit): BsonArray

Instantiates a new BSON array.

Example

To create the following BSON array:

[
    12,
    null,
    {
        "name": "Barry"
    }
]

use the code:

buildArray {
    writeInt32(12)
    writeNull()
    writeDocument {
        writeString("name", "Barry")
    }
}

@LowLevelApi
open fun buildArray(instance: BsonValueWriteable): BsonArray

Instantiates a new BSON array representing the provided instance.

buildDocument

@LowLevelApi
abstract fun buildDocument(block: BsonFieldWriter.() -> Unit): BsonDocument

Instantiates a new BSON document.

Example

To create the following BSON document:

{
    "name": "Bob",
    "isAlive": true,
    "children": [
        {
            "name": "Alice"
        },
        {
            "name": "Charles"
        }
    ]
}

use the code:

factory.buildDocument {
    writeString("name", "Alice")
    writeBoolean("isAlive", true)
    writeArray("children") {
        writeDocument {
            writeString("name", "Alice")
        }
        writeDocument {
            writeString("name", "Charles")
        }
    }
}

@LowLevelApi
open fun buildDocument(instance: BsonFieldWriteable): BsonDocument

Instantiates a new BSON document representing the provided instance.

encode

@LowLevelApi
abstract fun <T : Any> encode(obj: T, type: KType): BsonDocument

Writes an arbitrary Kotlin obj into a top-level BSON document.

Prefer using the overload with a single parameter.

A top-level BSON document cannot be null, cannot be a primitive, and cannot be a collection. If obj is not representable as a document, an exception is thrown.

encode

inline fun <T : Any> BsonFactory.encode(obj: T): BsonDocument

Writes an arbitrary Kotlin obj into a top-level BSON document.

A top-level BSON document cannot be null, cannot be a primitive, and cannot be a collection. If obj is not representable as a document, an exception is thrown.

See also

• BsonDocument.decode: The inverse operation.

readArray

@LowLevelApi
abstract fun readArray(bytes: ByteArray): BsonArray

Instantiates a new BSON array by reading its bytes representation.

The reverse operation is available as BsonArray.toByteArray.

readDocument

@LowLevelApi
abstract fun readDocument(bytes: ByteArray): BsonDocument

Instantiates a new BSON document by reading its bytes representation.

The reverse operation is available as BsonDocument.toByteArray.