Java Desktop Apps
ObjectBox database does not only work with Android projects, but also for plain Java (JVM) desktop apps running on Windows, Linux, and macOS. How to build and test Java Desktop apps using ObjectBox.
ObjectBox – Embedded Database for Java Desktop Apps
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.
To get set up, in your project’s
build.gradle file, you apply 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:
Gradle 5.2 or newer
Gradle 5.1 or older
1
buildscript {
2
ext.objectboxVersion = "3.0.1"
3
repositories {
4
mavenCentral() // Note: 2.9.0 and older are available on jcenter()
5
}
6
dependencies {
7
classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion")
8
}
9
}
10
11
repositories {
12
mavenCentral()
13
}
14
15
apply plugin: "java-library"
16
apply plugin: "io.objectbox"
Copied!
In Gradle 5.1 or older annotation processor support is incomplete, so adding an annotation processor plugin (e.g. gradle-apt-plugin) is recommended:
1
buildscript {
2
ext.objectboxVersion = '2.9.1'
3
repositories {
4
mavenCentral() // Note: 2.9.0 and older are available on jcenter()
5
maven { url "https://plugins.gradle.org/m2/" }
6
}
7
dependencies {
8
classpath "net.ltgt.gradle:gradle-apt-plugin:0.20"
9
classpath "io.objectbox:objectbox-gradle-plugin:$objectboxVersion"
10
}
11
}
12
13
repositories {
14
jcenter()
15
}
16
17
apply plugin: 'java'
18
// Annotation processor plugin for better Gradle + IntelliJ support.
19
apply plugin: 'net.ltgt.apt-idea'
20
apply plugin: 'io.objectbox'
Copied!
Using your IDE of choice with a Gradle project might require additional configuration. E.g.
- For IntelliJ IDEA see the help page for Gradle. Also make sure to use version 2019.1 or newer as it has improved Gradle support, like delegating build actions to Gradle.
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: on Windows you might have to install the Microsoft Visual C++ 2015 Redistributable (x64) packages to use the ObjectBox DLL.
Note that ObjectBox binaries are built 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:1
dependencies {
2
// Optional: include all native libraries for distribution
3
implementation("io.objectbox:objectbox-linux:$objectboxVersion")
4
implementation("io.objectbox:objectbox-macos:$objectboxVersion")
5
implementation("io.objectbox:objectbox-windows:$objectboxVersion")
6
// Since 2.9.0 we also provide ARM support for the Linux library
7
implementation("io.objectbox:objectbox-linux-arm64:$objectboxVersion")
8
implementation("io.objectbox:objectbox-linux-armv7:$objectboxVersion")
9
}
10
11
// Apply plugin after dependencies block so they are not overwritten.
12
apply plugin: "io.objectbox"
13
// Or using Kotlin DSL:
14
apply(plugin = "io.objectbox")
Copied!
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:
1
dependencies {
2
// Added automatically by the plugin - just for reference.
3
implementation("io.objectbox:objectbox-java:$objectboxVersion")
4
annotationProcessor("io.objectbox:objectbox-processor:$objectboxVersion")
5
}
6
7
// Apply plugin after dependencies block so they are not overwritten.
8
apply plugin: "io.objectbox"
9
// Or using Kotlin DSL:
10
apply(plugin = "io.objectbox")
Copied!
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:1
// Groovy DSL
2
tasks.withType(JavaCompile) {
3
options.compilerArgs += [ "-Aobjectbox.modelPath=$projectDir/schemas/objectbox.json" ]
4
}
5
6
// Kotlin DSL
7
tasks.withType<JavaCompile>() {
8
options.compilerArgs.add("-Aobjectbox.modelPath=$projectDir/schemas/objectbox.json")
9
}
Copied!
Optional: Change the MyObjectBox package
1.5 or newer
By default the MyObjectBox class is generated in the same or a parent package of your entity classes. You can define a specific package by passing the
objectbox.myObjectBoxPackage argument to the ObjectBox annotation processor.In your project’s
build.gradle file after the java plugin, add the necessary compiler argument:1
// Groovy DSL
2
tasks.withType(JavaCompile) {
3
options.compilerArgs += [ "-Aobjectbox.myObjectBoxPackage=com.example.custom" ]
4
}
5
6
// Kotlin DSL
7
tasks.withType<JavaCompile>() {
8
options.compilerArgs.add("-Aobjectbox.myObjectBoxPackage=com.example.custom")
9
}
Copied!
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 plugin1
// enable debug output for plugin
2
objectbox {
3
debug = true
4
}
5
// enable debug output for annotation processor
6
// Groovy DSL
7
tasks.withType(JavaCompile) {
8
options.compilerArgs += [ "-Aobjectbox.debug=true" ]
9
}
10
11
// Kotlin DSL
12
tasks.withType<JavaCompile>() {
13
options.compilerArgs.add("-Aobjectbox.debug=true")
14
}
Copied!
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:
1
@Entity
2
public class Note {
3
4
@Id
5
public long id;
6
7
public String text;
8
public String comment;
9
public Date date;
10
11
public Note(long id, String text, String comment, Date date) {
12
this.id = id;
13
this.text = text;
14
this.comment = comment;
15
this.date = date;
16
}
17
18
public Note() {
19
}
20
}
Copied!
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:
1
public static void main(String[] args) {
2
BoxStore store = MyObjectBox.builder().name("objectbox-notes-db").build();
3
Box<Note> box = store.boxFor(Note.class);
4
5
String text = args.length > 0 ? String.join(" ", args) : "No text given";
6
box.put(new Note(text));
7
8
System.out.println(box.count() + " notes in ObjectBox database:");
9
for (Note note : box.getAll()) {
10
System.out.println(note);
11
}
12
store.close();
13
}
Copied!
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:1
dependencies {
2
testCompile 'junit:junit:4.12'
3
}
Copied!
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:
1
public class NoteTest {
2
private File boxStoreDir;
3
private BoxStore store;
4
5
@Before
6
public void setUp() throws IOException {
7
// store the database in the systems temporary files folder
8
File tempFile = File.createTempFile("object-store-test", "");
9
// ensure file does not exist so builder creates a directory instead
10
tempFile.delete();
11
boxStoreDir = tempFile;
12
store = MyObjectBox.builder()
13
// add directory flag to change where ObjectBox puts its database files
14
.directory(boxStoreDir)
15
// optional: add debug flags for more detailed ObjectBox log output
16
.debugFlags(DebugFlags.LOG_QUERIES | DebugFlags.LOG_QUERY_PARAMETERS)
17
.build();
18
}
19
20
@After
21
public void tearDown() throws Exception {
22
if (store != null) {
23
store.close();
24
store.deleteAllFiles();
25
}
26
}
27
28
@Test
29
public void testPutAndGet() {
30
Box<Note> box = store.boxFor(Note.class);
31
assertEquals(...);
32
}
33
}
Copied!
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.
Last modified 1mo ago
Export as PDF
Copy link