BsonFactory

common

expect class BsonFactory : BsonFactory

Creates KtMongo BsonDocument and BsonArray instances by wrapping the equivalents from the official drivers.

jvm

actual class BsonFactory(codecRegistry: CodecRegistry) : BsonFactory

BsonDocument and BsonArray factory that uses the official MongoDB driver's CodecRegistry machinery.

Documents and arrays created from this class follow your existing configuration of the official MongoDB driver, including any library supported by the official MongoDB driver (KotlinX.Serialization, Jackson…).

This factory also adds support for the types specific to KtMongo. If you also use the official driver directly, you will need to configure it to access the KtMongo codecs. To learn more, see BsonFactory.codecRegistry.

Constructors

BsonFactory

constructor(codecRegistry: CodecRegistry)

Types

Companion

object Companion

Properties

codecRegistry

val codecRegistry: CodecRegistry

The CodecRegistry used by this factory to create and read documents.

This registry includes codecs for KtMongo-specific types. When mixing KtMongo with the official driver, it is recommended to configure the official driver using this registry to ensure types are serialized identically by both libraries.

val client = MongoClient.create("mongodb://mongo:27017")
val factory = BsonFactory(client.codecRegistry)
val clientWithKotlin = client.withCodecRegistry(factory.codecRegistry)

val database = clientWithKotlin.getDatabase("myDatabase")
val collection = database.getCollection<MyType>("myCollection").asKtMongo()

If you only use the KtMongo DSL to write queries, you do not need this configuration.

Functions

buildArray

common

@LowLevelApi
@LowLevelApi
expect open override fun buildArray(block: BsonValueWriter.() -> Unit): BsonArray

jvm

@LowLevelApi
@LowLevelApi
actual open override fun buildArray(block: BsonValueWriter.() -> Unit): BsonArray

common

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

jvm

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

buildDocument

common

@LowLevelApi
@LowLevelApi
expect open override fun buildDocument(block: BsonFieldWriter.() -> Unit): BsonDocument

jvm

@LowLevelApi
@LowLevelApi
actual open override fun buildDocument(block: BsonFieldWriter.() -> Unit): BsonDocument

common

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

jvm

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

encode

common

@LowLevelApi
@LowLevelApi
expect open override fun <T : AnyT : Any> encode(obj: T, type: KType): BsonDocument

jvm

@LowLevelApi
@LowLevelApi
actual open override fun <T : AnyT : Any> encode(obj: T, type: KType): BsonDocument

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.

findCodecForType

@LowLevelApi
fun <T> findCodecForType(type: KType): Codec<T>

Returns the instance of Codec (from the official MongoDB driver) that is used to encode or decode the given type.

If <strong>type</strong> and <strong>T</strong> do not match, the behavior is unspecified. Prefer using the no-argument of this method.

See also

• codecRegistry: The codec registry used by this BSON factory.

Throws

BsonDecodingException

If no matching codec is found for the given type.

@LowLevelApi
inline fun <T> findCodecForType(): Codec<T>

Returns the instance of Codec (from the official MongoDB driver) that is used to encode or decode the given type T.

Example

val client = MongoClient.create("mongodb://mongo:27017")
val factory = BsonFactory(client.codecRegistry)

val codec = factory.findCodecForType<String>()

See also

• codecRegistry: The codec registry used by this BSON factory.

Throws

BsonDecodingException

If no matching codec is found for the given type.

readArray

fun readArray(raw: BsonArray): BsonArray

Wraps a org.bson.BsonArray from the official MongoDB driver into its KtMongo equivalent.

common

@LowLevelApi
@LowLevelApi
expect open override fun readArray(bytes: ByteArray): BsonArray

jvm

@LowLevelApi
@LowLevelApi
actual open override fun readArray(bytes: ByteArray): BsonArray

common

@LowLevelApi
@LowLevelApi
expect open override fun readArray(array: BsonArray): BsonArray

jvm

@LowLevelApi
@LowLevelApi
actual open override fun readArray(array: BsonArray): BsonArray

readDocument

fun readDocument(official: BsonDocument): BsonDocument

Wraps a org.bson.BsonDocument from the official MongoDB driver into its KtMongo equivalent.

common

@LowLevelApi
@LowLevelApi
expect open override fun readDocument(bytes: ByteArray): BsonDocument

jvm

@LowLevelApi
@LowLevelApi
actual open override fun readDocument(bytes: ByteArray): BsonDocument

common

@LowLevelApi
@LowLevelApi
expect open override fun readDocument(document: BsonDocument): BsonDocument

jvm

@LowLevelApi
@LowLevelApi
actual open override fun readDocument(document: BsonDocument): BsonDocument

readValue

fun readValue(raw: BsonValue): BsonValue

Wraps a org.bson.BsonValue from the official MongoDB driver into its KtMongo equivalent.

common

@LowLevelApi
@LowLevelApi
expect open override fun readValue(value: BsonValue): BsonValue

jvm

@LowLevelApi
@LowLevelApi
actual open override fun readValue(value: BsonValue): BsonValue