Adding ObjectBox to your Android Project

ObjectBox is available from the jcenter repository. To add ObjectBox to your Android project, open the build.gradlefile for your project (not the ones for your app or module) and add a global variable for the version and the ObjectBox Gradle plugin:

buildscript {
    ext.objectboxVersion = '2.3.1'
    respositories {
        jcenter()
    }
    dependencies {
        // Android Gradle Plugin 3.0.0 or later supported
        classpath 'com.android.tools.build:gradle:3.2.1'
        classpath "io.objectbox:objectbox-gradle-plugin:$objectboxVersion"
    }
}

Open the build.gradle file for your app or module and, after the com.android.application plugin, apply the io.objectbox plugin:

apply plugin: 'com.android.application'
apply plugin: 'io.objectbox' // apply last

Optional: Kotlin

For Android projects using Kotlin, make sure to add kotlin-kapt as well:

apply plugin: 'com.android.application'
apply plugin: 'kotlin-android' // if using Kotlin
apply plugin: 'kotlin-kapt' // if using Kotlin
apply plugin: 'io.objectbox' // apply last

When syncing the Gradle plugin now automatically adds the required ObjectBox libraries and code generation tasks.

Optional: Advanced Setup

The ObjectBox plugin uses reasonable defaults and detects most configurations automatically. However, if needed you can configure the model file path, the MyObjectBox package, enable debug mode and more using advanced setup options.

Entity Classes

Next, define your model by annotating at least one class with @Entity:

@Entity
public class ExampleEntity {
    @Id public long id;
}

Note that ObjectBox uses IDs of type long (see Object IDs doc). For details on @Entity and other annotations, check the entity annotations documentation.

Then build your project to generate required classes, for example using Build > Make Project in Android Studio.

Core Classes

The following core classes are the essential interface to ObjectBox:

MyObjectBox: Generated based on your entity classes, MyObjectBox supplies a builder to set up a BoxStore for your app.

BoxStore: The entry point for using ObjectBox. BoxStore is your direct interface to the database and manages Boxes.

Box: A box persists and queries for entities. For each entity, there is a Box (supplied by BoxStore).

Core Initialization

Finally, the basic steps to initialize the core ObjectBox classes:

// do this once, for example in your Application class
boxStore = MyObjectBox.builder().androidContext(App.this).build();
// do this in your activities/fragments to get hold of a Box
notesBox = ((App) getApplication()).getBoxStore().boxFor(Note.class);

The example assumes a Note entity exists. With its Box ( notesBox object), we can call the persistence operation for this specific entity.

Basic Box operations

The Box class is likely the class you interact with most. As seen previously, you get Box instances via BoxStore.boxFor(). A Box instance gives you access to objects of a particular type. For example, if you have Customer and Order entities, you need two Box objects to interact with each:

Box<Customer> customerBox = boxStore.boxFor(Customer.class);
Box<Order> orderBox = boxStore.boxFor(Order.class);

These are some of the operations offered by the Box class:

• put: Persist an object, which may overwrite an existing object with the same ID. In other words, use put to insert or update objects (see also the docs for object IDs). When put returns, an ID will be assigned to the object. The various put overloads support putting multiple objects, which is convenient and more efficient.

• get: Given an object’s ID, you can get it very efficiently using get. To get all objects of a type, use getAll .

• remove: Remove a previously put object from its box (deletes it). There are method overloads to remove multiple entities, and removeAll to remove (delete) all objects of a type.

• count: Returns the number of objects stored in this box.

• query: Returns a query builder. See queries for details.

For a complete list of methods available in the Box class, check its JavaDoc.

Transactions

While ObjectBox offers powerful transactions, it is sufficient for many apps to consider just some basics guidelines about transactions:

• A put runs an implicit transaction.

• Prefer put bulk overloads for lists (like put(entities)) when possible.

• For a high number of DB interactions in loops, consider explicit transactions, such as using runInTx().

For more details please check the separate transaction documentation.

Have an app with greenDAO? DaoCompat is for you!

DaoCompat is a compatibility layer that gives you a greenDAO like API for ObjectBox. It makes switching from greenDAO to ObjectBox simple. Have a look at the documentation and the example. Contact us if you have any questions!