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:

The Gradle plugin generates code and a data meta model at build time.

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

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 putted 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 example. Docs will follow, 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