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.

open fun readArray(array: BsonArray): BsonArray

Returns a BsonArray that is tied to this factory, that represents the same data as array.

This method is useful when you need to convert from a different BsonArray implementation to the one returned by this factory. For example, if you have a BsonArray from the Multiplatform driver and you want to convert it to one from the official driver.

The returned array may be referentially identical to array if array was already produced by this factory.

The returned array may share memory with array.

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.

open fun readDocument(document: BsonDocument): BsonDocument

Returns a BsonDocument that is tied to this factory, that represents the same data as document.

This method is useful when you need to convert from a different BsonDocument implementation to the one returned by this factory. For example, if you have a BsonDocument from the Multiplatform driver and you want to convert it to one from the official driver.

The returned document may be referentially identical to document if document was already produced by this factory.

The returned document may share memory with document.

readValue¶

open fun readValue(value: BsonValue): BsonValue

Returns a BsonValue that is tied to this factory, that represents the same data as value.

This method is useful when you need to convert from a different BsonValue implementation to the one returned by this factory. For example, if you have a BsonValue from the Multiplatform driver and you want to convert it to one from the official driver.

The returned value may be referentially identical to value if value was already produced by this factory.

The returned value may share memory with value.