com.github.jershell:kbson

This adapter adds BSON support to kotlinx.serialization.

License

License

GroupId

GroupId

com.github.jershell
ArtifactId

ArtifactId

kbson
Last Version

Last Version

0.4.4
Release Date

Release Date

Type

Type

jar
Description

Description

com.github.jershell:kbson
This adapter adds BSON support to kotlinx.serialization.
Project URL

Project URL

https://github.com/jershell/kbson.git
Source Code Management

Source Code Management

https://github.com/jershell/kbson/issues

Download kbson

How to add to project

<!-- https://jarcasting.com/artifacts/com.github.jershell/kbson/ -->
<dependency>
    <groupId>com.github.jershell</groupId>
    <artifactId>kbson</artifactId>
    <version>0.4.4</version>
</dependency>
// https://jarcasting.com/artifacts/com.github.jershell/kbson/
implementation 'com.github.jershell:kbson:0.4.4'
// https://jarcasting.com/artifacts/com.github.jershell/kbson/
implementation ("com.github.jershell:kbson:0.4.4")
'com.github.jershell:kbson:jar:0.4.4'
<dependency org="com.github.jershell" name="kbson" rev="0.4.4">
  <artifact name="kbson" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.github.jershell', module='kbson', version='0.4.4')
)
libraryDependencies += "com.github.jershell" % "kbson" % "0.4.4"
[com.github.jershell/kbson "0.4.4"]

Dependencies

runtime (4)

Group / Artifact Type Version
org.jetbrains.kotlin : kotlin-stdlib-jdk8 jar 1.4.20
org.jetbrains.kotlinx : kotlinx-serialization-core-jvm jar 1.0.1
org.jetbrains.kotlinx : kotlinx-serialization-json-jvm jar 1.0.1
org.mongodb : bson jar 4.1.0

Project Modules

There are no modules declared in this project.

Maven Central Bintray

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

Reference links

Versions

Version
0.4.4
0.4.3
0.4.2
0.4.1
0.4.1-rc
0.4.0-rc
0.3.0
0.2.3
0.2.2
0.2.1
0.2.0
0.1.5
0.1.4
0.1.3