ObjectBox and Kotlin

ObjectBox comes with full Kotlin support for Android. This allows entities to be modeled in Kotlin classes (regular and data classes). With Kotlin support you can build faster apps even faster.

Kotlin Entities

In Kotlin, @Id properties must be var (not val) because ObjectBox assigns the ID after putting a new entity. They also should be of non-null type Long with the special value of zero for marking entities as new.

So a simple data class (regular classes are supported as well) looks like this:

@Entity
data class Note(
        @Id var id: Long = 0,
        var text: String?
)

// set default values to ensure default constructor
@Entity
data class Note(
        @Id var id: Long = 0,
        var text: String? = null,
        @Convert(converter = StringsConverter::class, dbType = String::class)
        var strings: List<String> = listOf()
)

Background: ObjectBox requires a compatible all-args or a default constructor to construct entity instances. It prefers a compatible all-args constructor as it is a little faster.

Defining Relations in Kotlin Entities

When defining relations in Kotlin, keep in mind that relation properties must be var. Otherwise they can not be initialized as described in the relations docs.

To avoid null checks use a lateinit modifier. When using a data class this requires the relation property to be moved to the body. An example:

@Entity
data class Order(
        @Id var id: Long = 0
) {
    lateinit var customer: ToOne<Customer>
}
​
@Entity
data class Customer(
        @Id var id: Long = 0,
        var name: String? = null
) {    
    @Backlink(to = "customer")
    lateinit var orders: ToMany<Order>
}

As mentioned above (warning box), make sure to provide default values for all constructor properties. This creates a default constructor that ObjectBox can use to construct entity instances.

Using the provided extension functions

​After setting up your project, you also might want to add our Kotlin extension functions. We provide a tiny additional library that we intend to grow in the future (see below for what works today).

Just add it to the existing dependencies in your app's build.gradle file:

dependencies {
    implementation "io.objectbox:objectbox-kotlin:$objectboxVersion"
}

Now have a look at what is possible with the extensions compared to standard Kotlin idioms:

Get a box:

// Regular
val box = store.boxFor(DataClassEntity::class.java)
​
// With extension
val box: Box<DataClassEntity> = store.boxFor()

Build a query:

// Regular
val query = box.query().run {
    equal(property, value)
    order(property)
    build()
}
​
// With extension
val query = box.query {
    equal(property, value)
    order(property)
}

Use the in filter of a query:

// Regular
val query = box.query().`in`(property, array).build()
​
// With extension
val query = box.query().inValues(property, array).build()

Modify a ToMany:

// Regular
toMany.apply { 
    reset()
    add(entity)
    removeById(id)
    applyChangesToDb()
}
​
// With extension
toMany.applyChangesToDb(resetFirst = true) { // default is false
    add(entity)
    removeById(id)
}

Something missing? Let us know what other extension functions you want us to add.

Next Steps

• Check out the Kotlin example on GitHub.

• Continue with Getting Started.