ObjectBox Java Documentation

repository·main·Indexed 26 days ago

https://github.com/objectbox/objectbox-java

A fast, efficient, on-device database for Java and Kotlin applications supporting standard object storage and vector search for AI/RAG. Designed for Android and JVM (Linux, macOS, Windows), it includes specialized libraries for AndroidX Paging, LiveData, RxJava 2/3, and Mesh Sync for peer-to-peer synchronization via Google Nearby Connections.

Tokens
6.3K
Snippets
12
Records
24
Agent score
85%

What's inside ObjectBox Java

  1. Available ObjectBox Android APIs

    main

    The objectbox-android library provides several Android-specific APIs to integrate ObjectBox with Android frameworks:

    • Admin: API to enable the ObjectBox Admin web app on Android for data browsing.
    • AndroidScheduler: Used to observe query results specifically on the Android main thread.
    • ObjectBoxDataSource: A reference implementation of a data source designed for use with the AndroidX Paging library.
    • ObjectBoxLiveData: A reference implementation of AndroidX LiveData for observing database changes.
  2. Understand FlatBuffers integration in ObjectBox Java

    main

    ObjectBox Java includes a custom-packaged copy of Google's FlatBuffers for Java. This is done specifically to prevent namespace conflicts with any FlatBuffers-generated Java code that a developer might be using within their own application.

    Note that the version of FlatBuffers used in this library is 23.5.26, though the version specified in Constants.java might differ.

  3. Add ObjectBox Mesh Sync for Android to your project

    main

    ObjectBox Mesh Sync for Android enables peer-to-peer (P2P) mesh synchronization between ObjectBox Sync clients on Android using Google Nearby Connections, without requiring a central server.

    Important Integration Note: This library must be added in addition to the Sync variant of the ObjectBox Android library (e.g., objectbox-sync-android). This library provides the Android-specific glue, the play-services-nearby dependency, and the necessary manifest permissions, while the native mesh sync implementation resides in the main Sync variant.

  4. Include the build-logic project as a composite build

    main

    The build-logic project provides common build logic and convention plugins. To use these plugins in your project, you must include build-logic as a composite build within the pluginManagement block of your settings.gradle(.kts) file. This must be done before the standard include statements.

    pluginManagement {
        includeBuild("build-logic")
    }
  5. Setup ObjectBox for an Android project

    main

    To use ObjectBox in an Android project, you must configure your Gradle files. The setup process depends on whether you are using Kotlin and which version of the Android Gradle Plugin (AGP) your project uses.

    For Android projects using AGP 9.0 or newer

    Follow the specific configuration steps for AGP 9.0+ in your build files.

    For Android projects using AGP 8.13 or older

    Follow the specific configuration steps for AGP 8.13 or older in your build files.

    If using Kotlin

    Ensure you follow the additional steps required for Kotlin integration within your Android setup.

  6. Install ObjectBox via Gradle (Plugin ID / Buildscript syntax)

    main

    If you are not using TOML version catalogs, you can install the ObjectBox plugin using the plugins block or the buildscript block.

    Option 1: Using plugins block (KTS) In your root build.gradle.kts:

    plugins {
        id("io.objectbox") version "6.0.0-beta" apply false
    }

    Option 2: Using buildscript block (KTS) In your root build.gradle.kts:

    buildscript {
        val objectboxVersion by extra("6.0.0-beta")
        repositories {
            mavenCentral()
        }
        dependencies {
            classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion")
        }
    }

    Option 3: Using buildscript block (Groovy) In your root build.gradle:

    buildscript {
        ext.objectboxVersion = "6.0.0-beta"
        repositories {
            mavenCentral()
        }
        dependencies {
            classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion")
        }
    }

    After configuring the root script, apply the plugin in your subproject (e.g., app/build.gradle.kts) using id("io.objectbox").

    // build.gradle.kts
    
    plugins {
        // Add the ObjectBox plugin
        id("io.objectbox") version "6.0.0-beta" apply false
    }
    // build.gradle.kts
    
    buildscript {
        // Define a variable for the ObjectBox plugin version
        val objectboxVersion by extra("6.0.0-beta")
      
        repositories {
            mavenCentral()    
        }
      
        dependencies {
            // Add the ObjectBox plugin
            classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion")
        }
    }
    
    allprojects {
        repositories {
            mavenCentral()
        }
    }
    // build.gradle
    
    buildscript {
        // Define a variable for the ObjectBox plugin version
        ext.objectboxVersion = "6.0.0-beta"
      
        repositories {
            mavenCentral()    
        }
      
        dependencies {
            // Add the ObjectBox plugin
            classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion")
        }
    }
    
    allprojects {
        repositories {
            mavenCentral()
        }
    }
    // app/build.gradle.kts
    
    plugins {
        // ... other plugins ...
    
        // Finally, apply the ObjectBox plugin
        id("io.objectbox")
    }
  7. Install ObjectBox via Gradle (TOML Version Catalog)

    main

    To use ObjectBox in a Gradle project with a TOML version catalog, follow these steps:

    1. Define versions and plugins in gradle/libs.versions.toml:

      • Set objectbox = "6.0.0-beta" (or your desired version).
      • Add the objectbox plugin alias: objectbox = { id = "io.objectbox", version.ref = "objectbox" }.
    2. Configure root build.gradle.kts:

      • Use alias(libs.plugins.objectbox) apply false to declare the plugin.
    3. Configure settings.gradle.kts:

      • Ensure mavenCentral() is added to both pluginManagement.repositories and dependencyResolutionManagement.repositories.
    4. Apply plugins in your subproject (e.g., app/build.gradle.kts):

      • Apply the appropriate Android or JVM plugins.
      • Apply the ObjectBox plugin using alias(libs.plugins.objectbox).
    # gradle/libs.versions.toml
    
    [versions]
    # For an Android project
    agp = "AGP_VERSION"
    # If using Kotlin
    kotlin = "KOTLIN_VERSION"
    
    # Define a variable for the version of the ObjectBox plugin
    objectbox = "6.0.0-beta"
    
    [plugins]
    # For an Android project, using Android Gradle Plugin 9.0 or newer
    android-application = { id = "com.android.application", version.ref = "agp" }
    kotlin-kapt = { id = "com.android.legacy-kapt", version.ref = "agp" }
    
    # For an Android project, using Android Gradle Plugin 8.13 or older
    android-application = { id = "com.android.application", version.ref = "agp" }
    kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
    kotlin-kapt = { id = "org.jetbrains.kotlin.kapt", version.ref = "kotlin" }
    
    # For a JVM project, if using Kotlin 
    kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
    kotlin-kapt = { id = "org.jetbrains.kotlin.kapt", version.ref = "kotlin" }
    
    # Add an alias for the ObjectBox plugin
    objectbox = { id = "io.objectbox", version.ref = "objectbox" }
    // build.gradle.kts
    
    plugins {
        // For an Android project, using Android Gradle Plugin 9.0 or newer
        alias(libs.plugins.android.application) apply false
        alias(libs.plugins.kotlin.kapt) apply false  
      
        // For an Android project, using Android Gradle Plugin 8.13 or older
        alias(libs.plugins.android.application) apply false
        alias(libs.plugins.kotlin.android) apply false
        alias(libs.plugins.kotlin.kapt) apply false
    
        // For a JVM project, if using Kotlin
        alias(libs.plugins.kotlin.jvm) apply false
        alias(libs.plugins.kotlin.kapt) apply false
      
        // Add the ObjectBox plugin
        alias(libs.plugins.objectbox) apply false  
    }
    // settings.gradle.kts
    
    pluginManagement {
        repositories {
            // Add Maven Central to the plugin repositories
            mavenCentral()
        }
    }
    
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            // Add Maven Central to the dependency repositories
            mavenCentral()
        }
    }
    // app/build.gradle.kts
    
    plugins {
        // For an Android project, using Android Gradle Plugin 9.0 or newer
        alias(libs.plugins.android.application)
        alias(libs.plugins.kotlin.kapt)
        
        // For an Android project, using Android Gradle Plugin 8.13 or older
        alias(libs.plugins.android.application)
        alias(libs.plugins.kotlin.android)
        alias(libs.plugins.kotlin.kapt)
        
        // For a JVM project
        id("application") // or id("java-library")
        // Optional, if using Kotlin
        alias(libs.plugins.kotlin.jvm)
        alias(libs.plugins.kotlin.kapt)
    
        // Finally, apply the ObjectBox plugin
        alias(libs.plugins.objectbox)
    }
  8. Migrate from RxJava 2 to RxJava 3

    main

    If you are migrating from the previous ObjectBox RxJava 2 library, apply the following changes:

    1. Dependency: Change the dependency from the old RxJava 2 artifact to io.objectbox:objectbox-rxjava3.
    2. Package Name: Update your imports from io.objectbox.rx to io.objectbox.rx3.

    These changes allow you to run both versions side-by-side during your migration process.

  9. Manage Mesh Sync permissions

    main

    This library automatically merges permissions required by Google Nearby Connections into your app's manifest. Depending on the Android SDK version, some permissions (like location) might not be strictly necessary.

    To remove unnecessary permissions from your final merged manifest, use tools:node="remove" in your AndroidManifest.xml.

    Additionally, you must request any dangerous (runtime) permissions at runtime. Use the MeshSyncPermissions helper class provided by this library to request the default set of permissions.

    <uses-permission
        android:name="android.permission.ACCESS_COARSE_LOCATION"
        tools:node="remove" />
    <uses-permission
        android:name="android.permission.ACCESS_FINE_LOCATION"
        tools:node="remove" />
  10. Add ObjectBox RxJava 2 support to your project

    main

    To use RxJava 2 APIs with ObjectBox, add the objectbox-rxjava dependency to your Gradle configuration. Note that this library is in maintenance mode and will receive no new features; for new projects, consider using the RxJava 3 APIs.

    implementation "io.objectbox:objectbox-rxjava:$objectboxVersion"