What is ObjectBox? It’s a mobile database that makes object persistence simple and super fast.

This tutorial will walk you through a simple ObjectBox example project available on GitHub. If you already know the basics you can also skip ahead to the Introduction.

It’s a good idea to clone the example project right now so you can run the code and explore it in its entirety. Once you have cloned the repository, you will find the example project discussed here in the objectbox-example folder. It is a simple Android app for taking notes where you can add new notes by typing in some text and delete notes by clicking on an existing note.

The Note entity and Box class

To begin let’s jump right into the code: in the src folder you will find the entity class for a note, Note.java. It is persisted to the database and contains all data that is part of a note, like an id, note text and the creation date.

@Entity
public class Note {
​
    @Id
    long id;
​
    String text;
    Date date;
    ...
}

In general, an ObjectBox entity is an annotated class persisted in the database with its properties. In order to extend our note or to create new entities, you simply modify or create new plain Java classes and annotate them in the same way.

Next go ahead and build the project, for example by using Build > Make project in Android Studio. This triggers ObjectBox to generate some classes, like MyObjectBox.java, and some other classes used by ObjectBox internally.

Inserting and deleting notes

To see how new notes are added to the database, take a look at the NoteActivity class. First of all we have to prepare a Box object for our Note class, which we do in onCreate():

notesBox = ((App) getApplication()).getBoxStore().boxFor(Note.class);

When the user clicks the add button the method addNote() is called. There, we create a new Note object and put it into the database using the Box:

Note note = new Note(0, noteText, comment, new Date());
notesBox.put(note);
Log.d(App.TAG, "Inserted new note, ID: " + note.getId());

Note that we did pass 0 as an id when creating the note. In this case ObjectBox assigns an id during put().

Deleting a note is also straightforward. In ObjectBox terms, you remove the note object from its box, see NoteClickListener:

notesBox.remove(note);

Updating notes and more

What is not shown in the example, but is just as easy is updating a note. Just modify any of its properties and call put() again with the changed object:

note.setText("This note has changed.");
noteDao.put(note);

There are additional methods to put, find, query, count or remove entities. Check out the methods of the Box class to learn more.

Setting up the database

Now that you saw ObjectBox in action, how did we get that BoxStore instance? Typically you should set up the BoxStore once for the whole app inside the Application class:

boxStore = MyObjectBox.builder().androidContext(App.this).build();

Remember: ObjectBox is a NoSQL database on its own and thus NOT based on SQL or SQLite. That’s why you do not need to set up “CREATE TABLE” statements during initialization.

You may then add a getter like getBoxStore() that activities and fragments may call to get access to boxes, as seen above when inserting and deleting notes.

​