JarCasting
kbson
What is this?
This adapter adds BSON support to kotlinx.serialization.
BSON types supported:
- Double
- String
- Array
- Binary
- UUID
- ObjectId
- Boolean
- Date
- Symbol
- 32-bit integer
- Long
- Decimal128
Install
build.gradle.kts
dependencies {
// kotlin 1.3
implementation("com.github.jershell:kbson:0.3.0")
// kotlin 1.4.20 & kotlinx.serialization 1.0.1
implementation("com.github.jershell:kbson:0.4.4")
}
or
build.gradle
dependencies {
// kotlin 1.3
implementation 'com.github.jershell:kbson:0.3.0'
// kotlin 1.4.20 & kotlinx.serialization 1.0.1
implementation 'com.github.jershell:kbson:0.4.4'
}
Usage samples
Parsing from BSON to a Kotlin object
import kotlinx.serialization.Serializable
import com.github.jershell.kbson.ObjectIdSerializer
val kBson = KBson()
@Serializable
data class Simple (
val valueString: String,
val valueDouble: Double,
val valueFloat: Float,
val valueLong: Long,
val valueChar: Char,
val valueBool: Boolean,
@NonEncodeNull
@ContextualSerialization
val _id: ObjectId? = null,
@ContextualSerialization
val uuid: UUID,
val valueInt: Int
)
val simple = kBson.parse(Simple.serializer(), bsonDocFromMongoJavaDriver)
Serializing from a Kotlin object to BSON
import kotlinx.serialization.Serializable
import com.github.jershell.kbson.Configuration
import com.github.jershell.kbson.KBson
import com.github.jershell.kbson.ObjectIdSerializer
@Serializable
data class Simple (
val valueString: String = "default",
val valueDouble: Double,
val valueFloat: Float,
val valueLong: Long,
val valueChar: Char,
val valueBool: Boolean,
@NonEncodeNull
@ContextualSerialization
val _id: ObjectId? = null,
val valueInt: Int
)
// Optional configuration
val kBson = KBson(Configuration(encodeDefaults = false))
val bsonDoc = kBson.stringify(Simple.serializer(), simpleModel)
// You can override default serializers or add your serializer
val kBson = KBson(context = serializersModuleOf(mapOf(
ObjectId::class to ObjectIdSerializer,
Date::class to DateSerializer
)))
// You can use load and dump with ByteArray
val simple = kBson.load(Simple.serializer(), bsonDoc)
// also
val simple2 = kBson.load(Simple.serializer(), bsonDoc.toByteArray())
// !!!! The method load() use BsonDecoder and strict order of fields
See the tests for more examples
API
val kBson = KBson()
kBson.parse(deserializer: DeserializationStrategy<T>, doc: BsonDocument) :T
// !!!! The method load() use BsonDecoder and strict order of fields
// https://docs.mongodb.com/manual/tutorial/update-documents/#field-order
kBson.load(deserializer: DeserializationStrategy<T>, doc: ByteArray): T
kBson.load(deserializer: DeserializationStrategy<T>, doc: BsonDocument): T
kBson.stringify(): BsonDocument
kBson.dump(serializer: SerializationStrategy<T>, obj: T): ByteArray
// Extension functions
BsonDocument.toByteArray(): ByteArray
BsonDocument.toDocument(): Document
Configuration
classDiscriminator = "___type" // name of the class descriptor property in polymorphic serialization.
encodeDefaults = "true" // specifies whether default values are encoded.
ps
@NonEncodeNull useful for item _id mongodb
The default enum class supported like string. You can also override it
kbson before 0.1.5 use kotlinx.serialization 0.11.x
kbson after 0.1.5 use kotlinx.serialization 0.13.x
kbson after 0.2.0 use kotlinx.serialization 0.14.x
kbson after 0.2.2 use kotlinx.serialization 0.20.0 and kotlin 1.3.71
kbson after 0.4.0 use kotlinx.serialization "1.0-M1-1.4.0-rc" and kotlin 1.4.0-rc
kbson after 0.4.1 use kotlinx.serialization "1.0.0" and kotlin 1.4.10
kbson after 0.4.3 use kotlinx.serialization "1.0.0" and kotlin 1.4.20
Contributing to kbson
Pull requests and bug reports are always welcome!
To run the tests: ./gradlew check