ObjectBox Introduction: Setup and Basics

ObjectBox is a super fast mobile database that persists objects. It lets you avoid many repetitive tasks and offers a simple interface to your data.

Gradle setup

In order to use ObjectBox in your Android project, you need to add its Gradle plugin and Android library:

Note: to use ObjectBox in a plain Java project the setup differs a little, see the example project build.gradle file.

The Gradle plugin automatically adds the objectbox library dependency and configures an annotation processor which will generate code and a JSON data meta model file at build time.

Then model your entities and compile your project, for example using Build > Make Project in Android Studio.

If for some reason the library or annotation processor is not automatically added to your dependencies by the Gradle plugin, you can add them manually. For the processor use the annotationProcessor keyword for Java-only projects, or the kapt keyword if your project uses Kotlin:

Optional Configuration

In your app module Gradle build file (where your entities are), you can add some optional configuration. For example, you can switch on debug mode for the ObjectBox annotation processor (then run Gradle with the --info  option to see the debug output):

Other annotation processor arguments are:

  • objectbox.modelPath: override the default location for the JSON model file (“objectbox-models/default.json”).
  • objectbox.daoCompat: set to true if you want to use DAO compat (greenDAO-like API).

Core Classes

Once you have defined at least one entity and successfully built your project, you can start using ObjectBox in your Android project.

The following core classes are the essential interface to ObjectBox:

MyObjectBox: Generated based on your entity classes, MyObjectBox supplies a builder to set up a BoxStore for your app.

BoxStore: The entry point for using ObjectBox. BoxStore is your direct interface to the database and manages Boxes.

Box: A box persists and queries for entities. For each entity, there is a Box (supplied by BoxStore).

Entities: Use ObjectBox annotations to mark your object classes as persistable.

Core Initialization

Finally, the basic steps to initialize the core ObjectBox classes:

The example assumes a Note entity exists. With its Box ( notesBox object), we can call the persistence operation for this specific entity.

Basic Box operations

The Box class is likely the class you interact with most. As seen previously, you get Box instances via BoxStore.boxFor(). A Box instance gives you access to objects of a particular type. For example, if you have Customer and Order entities, you need two Box objects to interact with each:

These are some of the operations offered by the Box class:

  • put: Persist an object, which may overwrite an existing object with the same ID. In other words, use put  to insert or update objects (see also the docs for object IDs). When put returns, an ID will be assigned to the object. The various put overloads support putting multiple objects, which is convenient and more efficient.
  • get: Given an object’s ID, you can get it very efficiently using get. To get all objects of a type, use getAll .
  • remove: Remove a previously put object from its box (deletes it). There are method overloads to remove multiple entities, and removeAll  to remove (delete) all objects of a type.
  • count: Returns the number of objects stored in this box.
  • query: Returns a query builder. See queries for details.

For a complete list of methods available in the Box class, check its JavaDoc.

Object IDs

Objects must have an ID property of type long . You are free to use the wrapper type  java.lang.Long , but we advise against it in most cases. long IDs are enforced to make ObjectBox very efficient internally.

If your application requires other ID types (such as a string UID given by a server), you can model them as standard properties and use queries to look up entities by your application specific ID.

Special Object IDs

Object IDs may be any long value, with two exceptions:

  • 0 (zero): Objects with an ID of zero (and  null  if the ID is of type  Long) are considered new. Putting such an object will always insert a new object and assign an unused ID to it.
  • 0xFFFFFFFFFFFFFFFF (-1 in Java): This value is reserved for internal use by ObjectBox and may not be used by the app.

Object ID assignment

By default object IDs are assigned by ObjectBox. For each new object, ObjectBox will assign an unused ID that is above the current highest ID value used in a box. For example, if there are two objects with ID 1 and ID 100 in a box the next object that is put will be assigned ID 101.

By default, only ObjectBox may assign IDs. If you try to put an object with an ID greater than the currently highest ID, ObjectBox will throw an error.

However, if you need to assign IDs by yourself you can change the ID annotation to   @Id(assignable = true) . This will allow putting an entity with any valid ID, including zero to let ObjectBox auto assign a new ID.

Transactions

While ObjectBox offers powerful transactions, it is sufficient for many apps to consider just some basics guidelines about transactions:

  • A put  runs an implicit transaction.
  • Prefer put  bulk overloads for lists (like put(entities)) when possible.
  • For a high number of DB interactions in loops, consider explicit transactions, such as using  runInTx() .

For more details please check the separate transaction documentation.

Have an app with greenDAO? DaoCompat is for you!

DaoCompat is a compatibility layer that gives you a greenDAO like API for ObjectBox. It makes switching from greenDAO to ObjectBox simple. Have a look at the documentation and the example. Contact us if you have any questions!

Further Docs

ObjectBox Documentation

 

Spread the love
Sign up for fresh ObjectBOX news here. No spam, just fresh developer news once in a while.
x