Tutorial: How to get started with ObjectBox

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. It’s a good idea to clone it now because we will use it in this guide. You don’t have to, but it usually helps if 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. 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

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.

In general, an entity is a class persisted in the database with its properties.

Now make 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 learn how to add some notes, take a look at the NoteActivity class. First, we have to prepare a Box object for our Note class, which we do in onCreate():

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 that we did not pass an id when creating the note. In this case ObjectBox assigns an id during put().

Deleting a note is also straight forward. In ObjectBox terms, you remove an object from its box – see NoteClickListener:

Updating notes and more

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

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

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

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.

Activities and fragments may then call getBoxStore() to get access to boxes, as seen above when inserting and deleting notes.

Note: it is perfectly fine to never close the database. That’s even recommended for most apps.

Extending and adding entities

In order to extend our note or to create new entities, you simply modify or create Java classes and annotate them in the same way. Then rebuild your project.

See ObjectBox Entity Annotations for details.

Next steps

Now that you have an impression of how ObjectBox works, it’s a good idea to get your hands dirty and try it for yourself. Continue by having a look at the full documentation, starting with the Introduction.

Spread the love