Advanced Setup

Last updated 18 hours ago

ObjectBox - Advanced Setup

First, add and apply the ObjectBox plugin to your project.

To then change the default behavior of the ObjectBox plugin and processor read on for advanced setup options.

Manually Add Libraries

If the ObjectBox plugin does not automatically add the required library and annotation processor to your dependencies, you can add them manually. In your app’s build.gradle file, add the objectbox-android library and the objectbox-processor annotation processor.

For Android projects using Java:

dependencies {
// all below should be added automatically by the plugin
compile "io.objectbox:objectbox-android:$objectboxVersion"
annotationProcessor "io.objectbox:objectbox-processor:$objectboxVersion"
}

For Android projects using Kotlin:

dependencies {
// all below should be added automatically by the plugin
compile "io.objectbox:objectbox-android:$objectboxVersion"
kapt "io.objectbox:objectbox-processor:$objectboxVersion"
// some useful Kotlin extension functions
compile "io.objectbox:objectbox-kotlin:$objectboxVersion"
}

Change the Model File Path

By default the ObjectBox model file is stored in module-name/objectbox-models/default.json. You can change the file path and name by passing the objectbox.modelPath argument to the ObjectBox annotation processor.

In your app’s build.gradle file, add the necessary processor option.

For Android projects using Java:

android {
defaultConfig {
javaCompileOptions {
annotationProcessorOptions {
arguments = [ "objectbox.modelPath" : "$projectDir/schemas/objectbox.json".toString() ]
}
}
}
}

For Android projects using Kotlin:

kapt {
arguments {
arg("objectbox.modelPath", "$projectDir/schemas/objectbox.json")
}
}

Change the MyObjectBox package

Since 1.5.0

By default the MyObjectBox class is generated in the same or a parent package of your entity classes. You can define a specific package by passing the objectbox.myObjectBoxPackage argument to the ObjectBox annotation processor.

In your app’s build.gradle file, add the necessary processor option.

For Android projects using Java:

android {
defaultConfig {
javaCompileOptions {
annotationProcessorOptions {
arguments = [ "objectbox.myObjectBoxPackage" : "com.example.custom" ]
}
}
}
}

For Android projects using Kotlin:

kapt {
arguments {
arg("objectbox.myObjectBoxPackage", "com.example.custom")
}
}

Enable Debug Mode

You can enable debug output for the annotation processor if you encounter issues while setting up your project and entity classes.

In your app’s build.gradle file, add the necessary options and then run Gradle with the --info option to see the debug output.

For Android projects using Java:

android {
defaultConfig {
javaCompileOptions {
annotationProcessorOptions {
arguments = [ 'objectbox.debug' : 'true' ]
}
}
}
}

For Android projects using Kotlin:

kapt {
arguments {
arg("objectbox.debug", true)
}
}

Enable DaoCompat mode

ObjectBox can help you migrate from greenDAO by generating classes with a greenDAO-like API.

See the DaoCompat documentation on how to enable and use this feature.

Next steps

Tips when using Kotlin