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.
In order to use ObjectBox in your Android project, you need to add its Gradle plugin and Android library:
// In your root build.gradle file:
// In your project build.gradle file:
apply plugin: 'com.android.application'
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.
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.
Finally, the basic steps to initialize the core ObjectBox classes:
// do this once, for example in your Application class
boxStore = MyObjectBox.builder().androidContext(App.this).build();
// do this in your activities/fragments to get hold of a Box
notesBox = ((App) getApplication()).getBoxStore().boxFor(Note.class);
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:
Box<Customer> customerBox = boxStore.boxFor(Customer.class);
Box<Order> orderBox = boxStore.boxFor(Order.class);
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.
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.
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!