How to get started

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

This tutorial will walk you through a simple ObjectBox example project, which you probably got as an early tester.

ObjectBoxExample 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 the database decides on the note id. The Box automatically sets the new id before returning from insert (see the log statement).

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

The Box class is the central interface to ObjectBox. Check out its methods to get an impression.

Setting up the database

You already saw ObjectBox in action, but how did we get the Box(Store) 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.

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.

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.

Latest versions and updates

Please keep an eye on the changelog to track new features and fixes of recent versions.