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

This tutorial will walk you through a simple note-taking app explaining how to do basic operations with ObjectBox. To just integrate ObjectBox into your project, look for the Getting Started page.

It’s a good idea to clone the example project repository from GitHub right now:

git clone https://github.com/objectbox/objectbox-examples.git

This allows you to run the code and explore it in its entirety. The example project discussed here is in the android-app folder (or android-app-kotlin for the Kotlin version). 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. 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;
    String comment;
    Date date;
    
    ...
}

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

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 with @Entity and @Id.

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 notes

To see how new notes are added to the database, take a look at the NoteActivity class. First of all a Box object for the Note class is prepared, which is done in onCreate():

@Override
public void onCreate(Bundle savedInstanceState) {
    ...
    notesBox = ObjectBox.get().boxFor(Note.class);
    ...
}

public override fun onCreate(savedInstanceState: Bundle?) {
    ...
    notesBox = ObjectBox.boxStore.boxFor()
    ...
}

When the user clicks the ADD button the method addNote() is called. There, a new Note object is created and put into the database using the Box reference:

private void addNote() {
    ...
    Note note = new Note();
    note.setText(noteText);
    note.setComment(comment);
    note.setDate(new Date());
    notesBox.put(note);
    Log.d(App.TAG, "Inserted new note, ID: " + note.getId());
    ...
}

private fun addNote() {
    ...
    val note = Note(text = noteText, comment = comment, date = Date())
    notesBox.put(note)
    Log.d(App.TAG, "Inserted new note, ID: " + note.id)
    ...
}

Note that the ID is left at 0 when creating the note. In this case ObjectBox assigns an ID during put().

Removing/deleting notes

When the user taps a note it should be deleted. To remove (or delete) a note from its box use remove() or one of its overloads. See noteClickListener:

OnItemClickListener noteClickListener = new OnItemClickListener() {
    @Override
    public void onItemClick(AdapterView<?> parent, View view, int position, long id) {
        Note note = notesAdapter.getItem(position);
        notesBox.remove(note);
        Log.d(App.TAG, "Deleted note, ID: " + note.getId());
        ...
    }
};

private val noteClickListener = OnItemClickListener { _, _, position, _ ->
    notesAdapter.getItem(position)?.also {
        notesBox.remove(it)
        Log.d(App.TAG, "Deleted note, ID: " + it.id)
    }
    ...
}

Querying notes

To query and display notes with a list adapter a Query instance is built once in onCreate():

@Override
public void onCreate(Bundle savedInstanceState) {
    ...
    // Query all notes, sorted a-z by their text.
    notesQuery = notesBox.query().order(Note_.text).build();
    ...
}

public override fun onCreate(savedInstanceState: Bundle?) {
    ...
    // Query all notes, sorted a-z by their text.
    notesQuery = notesBox.query {
        order(Note_.text)
    }
    ...
}

And then executed each time any notes change:

private void updateNotes() {
    List<Note> notes = notesQuery.find();
    notesAdapter.setNotes(notes);
}

private fun updateNotes() {
    val notes = notesQuery.find()
    notesAdapter.setNotes(notes)
}

In addition to an order, you can add various conditions, like equality or less/greater than, when building a query.

Updating notes and more

What is not shown in the example, but is just as easy is how to update an existing (== the ID is not 0) note. Just modify any of its properties and call put() again with the changed object:

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

note.text = "This note has changed."
notesBox.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 a BoxStore once for the whole app. This example uses a helper class as recommended in the Getting Started guide.

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.