ObjectBox – Embedded Database for Java Desktop Apps

ObjectBox does not only work with Android projects, but also for plain Java (JVM) desktop apps running on Windows, Linux, and macOS. Just like on Android, ObjectBox stands for a super simple API and high performance. It’s designed for objects and outperforms other database and ORM solutions. Because it is an embedded database, ObjectBox runs in your apps’ process and needs no maintenance. Read on to learn how to create a Java project using ObjectBox. We believe it’s fairly easy. Please let us know your thoughts on it.

Desktop Project Setup

Because ObjectBox comes with a Gradle plugin, you use Gradle as a build system. For this, in your project’s build.gradle file, you simply apply an annotation processor plugin (e.g. via  gradle-apt-plugin) and the ObjectBox Gradle plugin. This must be done after applying the Java plugin.

This is how a Gradle build file using ObjectBox typically looks like:

This set up is the main difference between the Android and plain Java desktop setup. Other than this, ObjectBox works the same across platforms.

Native Libraries

Under the hood, ObjectBox is an object database running mostly in native code written in C/C++ for optimal performance (there’s no way to make this work as fast in plain Java). Thus, ObjectBox will load a native library: a “.dll” on Windows, a “.so” on Linux, and a “.dylib” on macOS. By default, the ObjectBox Gradle plugin adds a dependency to the native library matching your system. This means that your app is already set up to run on your system.

Note that ObjectBox binaries are build for 64 bit systems for best performance. Talk to us if you require 32 bit support.

Add Libraries for distribution

While the default build configuration ensures that your app runs on your development system, you may want to support all major platforms (Windows, Linux, macOS) when you distribute your app. For this, just add all platform dependencies to your project’s build.gradle file like this:

For reference, the following dependencies to the ObjectBox Java API and annotation processor are added by default by the ObjectBox Gradle plugin. Usually, there’s no need to set them up manually:

Optional: Change the Model File Path

By default, the ObjectBox model file is stored in module-name/objectbox-models/default.json. You can change the file path and name by passing the objectbox.modelPath argument to the ObjectBox annotation processor.

In your project’s build.gradle file after the java plugin, add the necessary compiler argument:

Optional: Enable Debug Mode

You can enable debug output for the plugin and for the annotation processor if you encounter issues while setting up your project.

Just add the necessary options in your project’s build.gradle file after the java and io.objectbox plugin:

Add Entity Classes

You must create at least one class annotated with @Entity to use ObjectBox. If you don’t know yet how to do this, learn here how to create and annotate entity classes.

The following code snippet shows how a simple entity class might look like:

Build BoxStore

To get a Box for saving your entities you need to build a BoxStore first. After creating your entity classes and building your project, e.g. by running gradlew build, the class MyObjectBox will be generated. Use MyObjectBox.builder() to build your BoxStore.

This code snippet demonstrates a simple program that builds a BoxStore and saves a Note entity object:

You can use the name(String) method of the builder to change the directory name your database files are stored in. See the BoxStoreBuilder documentation for more configuration options.

Building Unit Tests

In your project’s build.gradle file, add the JUnit testing framework to your test dependencies:

You create your unit test classes as usual under module-name/src/test/java/. To use ObjectBox in your test methods you need to build a BoxStore instance using the generated MyObjectBox class of your project. You can use the directory(File) method on the BoxStore builder to ensure the test database is stored in a specific folder on your machine. To start with a clean database for each test you can delete the existing database using BoxStore.deleteAllFiles(File).

The following example shows how you could implement a unit test class that uses ObjectBox:

To help diagnose issues you can enable log output for ObjectBox actions, such as queries, by specifying one or more debug flags when building BoxStore.

Next steps


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