Tutorial: Demo Project

Learn how to build a simple note-taking app with ObjectBox.

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 at the Getting Started page.

You can check out the example code from GitHub. This allows you to run the code and explore it in its entirety. It is a simple app for taking notes where you can add new notes by typing in some text and delete notes by clicking on an existing note.

Java

git clone https://github.com/objectbox/objectbox-examples.git
cd objectbox-examples/android-app

Kotlin

Dart

Python

The Note entity and Box class

To store notes there is an entity class called Note (or Task in Python). It defines the structure or model of the data persisted (saved) in the database for a note: its id, the note text and the creation date.

Java

src/Note.java

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

Kotlin

Dart

Python

In general, an ObjectBox entity is an annotated class persisted in the database with its properties. In order to extend the note or to create new entities, you simply modify or create new plain classes and annotate them with @Entity and @Id; in Python opt-in uid argument i.e. @Entity(uid=).

Entity Annotations

Java

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.

Kotlin

Dart

Python

Inserting notes

To see how new notes are added to the database, take a look at the following code fragments. The Box provides database operations for Note objects. A Box is the main interaction with object data.

Java

NoteActivity.java

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

Note: In the example project, ObjectBox is the name of a helper class to set up and keep a reference to BoxStore.

Kotlin

Dart

Python

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

Java

NoteActivity.java

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());
    ...
}

Kotlin

Dart

Python

Note that the ID property (0 when creating the Note object), is assigned by ObjectBox during a put.

Removing/deleting notes

When the user taps a note, it is deleted. The Box provides remove() to achieve this:

Java

NoteActivity.java

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());
        ...
    }
};

Kotlin

Dart

Python

Querying notes

To query and display notes in a list a Query instance is built once:

Java

NoteActivity.java

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

Kotlin

Dart

Python

And then executed each time any notes change:

Java

NoteActivity.java

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

Kotlin

Dart

Python

In addition to a result sort order, you can add various conditions to filter the results, like equality or less/greater than, when building a query.

ObjectBox Queries

Updating notes and more

What is not shown in the example, is how to update an existing (== the ID is not 0) note. Do so by just modifying any of its properties and then put it again with the changed object:

Java

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

Kotlin

Dart

Python

There are additional methods to put, find, query, count or remove entities. Check out the methods of the Box class in API docs (for Java/Kotlin or Dart) to learn more.

Getting started

Setting up the database

Now that you saw ObjectBox in action, how did we get that database (or store) instance? Typically you should set up a BoxStore or Store once for the whole app. This example uses a helper class as recommended in the Getting Started guide.

Getting started

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.

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