From a9e9626b5c1450df4f1035ee95298b6ae20de30b Mon Sep 17 00:00:00 2001 From: Uwe Date: Mon, 9 Feb 2026 11:51:42 +0100 Subject: [PATCH 1/9] README: improve and fix Gradle setup instructions Add all required plugins, add missing repository declaration for plugins syntax. Add inline instructions. Also make TOML variant the default, move others to an alternatives section. --- README.md | 136 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 106 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 3c254992..b0ec5d09 100644 --- a/README.md +++ b/README.md @@ -108,10 +108,10 @@ box.remove(person) // Delete > [!NOTE] > Prefer to look at example code? Check out [our examples repository](https://github.com/objectbox/objectbox-examples). -You can add the ObjectBox Java SDK to your project using: +You can add the ObjectBox Java SDK using a: -- a [Gradle setup](#gradle-setup) -- a [Maven setup](#maven-setup) +- [Gradle setup](#gradle-setup) +- [Maven setup](#maven-setup) ObjectBox tools and dependencies are available on [the Maven Central repository](https://central.sonatype.com/namespace/io.objectbox). @@ -131,31 +131,68 @@ The APIs and tools of the ObjectBox Java SDK support: ### Gradle setup -For Gradle projects, add the ObjectBox Gradle plugin to your root Gradle script. +For Gradle projects, add the required plugins to your root Gradle script. -When using a TOML version catalog and plugins syntax (for alternatives see below): +When using a [TOML version catalog](https://docs.gradle.org/current/userguide/version_catalogs.html) and plugins syntax +(for alternatives see below): ```toml # gradle/libs.versions.toml + [versions] +# Define a variable for the version of the plugin objectbox = "5.1.0" +# For an Android project +agp = "" + +# If using Kotlin +kotlin = "" + [plugins] +# Add an alias for the plugin objectbox = { id = "io.objectbox", version.ref = "objectbox" } + +# For an Android project +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" } ``` ```kotlin // build.gradle.kts + plugins { + // Add the plugin alias(libs.plugins.objectbox) apply false + + // For an Android project + 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 } ``` ```kotlin // settings.gradle.kts + pluginManagement { + repositories { + // Add the Maven Central repository + mavenCentral() + } + resolutionStrategy { eachPlugin { + // Map the plugin ID to the Maven artifact if (requested.id.id == "io.objectbox") { useModule("io.objectbox:objectbox-gradle-plugin:${requested.version}") } @@ -164,22 +201,57 @@ pluginManagement { } ``` -Alternatives: +Then, in the Gradle script of your subproject apply the necessary plugins: + +```kotlin +// app/build.gradle.kts + +plugins { + // For an Android project + 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 plugin + alias(libs.plugins.objectbox) +} +``` + +Finally, sync the Gradle project with your IDE (for ex. using "Sync Project with Gradle Files" in Android Studio). + +Your project can now use ObjectBox, continue by [defining entity classes](https://docs.objectbox.io/getting-started#define-entity-classes). -
Using plugins syntax +#### Alternatives + +
Using plugins syntax with plugin IDs ```kotlin // build.gradle.kts + plugins { + // Add the plugin id("io.objectbox") version "5.1.0" apply false } ``` ```kotlin // settings.gradle.kts + pluginManagement { + repositories { + // Add the Maven Central repository + mavenCentral() + } + resolutionStrategy { eachPlugin { + // Map the plugin ID to the Maven artifact if (requested.id.id == "io.objectbox") { useModule("io.objectbox:objectbox-gradle-plugin:${requested.version}") } @@ -194,12 +266,18 @@ pluginManagement { ```kotlin // build.gradle.kts + buildscript { + // Define a variable for the plugin version val objectboxVersion by extra("5.1.0") - repositories { + + repositories { + // Add the Maven Central repository mavenCentral() } + dependencies { + // Add the plugin classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion") } } @@ -211,12 +289,18 @@ buildscript { ```groovy // build.gradle + buildscript { + // Define a variable for the plugin version ext.objectboxVersion = "5.1.0" + repositories { + // Add the Maven Central repository mavenCentral() } + dependencies { + // Add the plugin classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion") } } @@ -224,36 +308,28 @@ buildscript {
-Then, in the Gradle script of your subproject apply the plugin: +Then, in the Gradle script of your subproject apply the necessary plugins using their IDs: ```kotlin // app/build.gradle.kts -plugins { - alias(libs.plugins.android.application) // When used in an Android project - alias(libs.plugins.kotlin.android) // When used in an Android project - alias(libs.plugins.kotlin.kapt) // When used in an Android or Kotlin project - alias(libs.plugins.objectbox) // Add after other plugins -} -``` - -
Alternative: when not using a version catalog, using the plugin id -```kotlin -// app/build.gradle.kts plugins { - id("com.android.application") // When used in an Android project - kotlin("android") // When used in an Android project - kotlin("kapt") // When used in an Android or Kotlin project - id("io.objectbox") // Add after other plugins + // For an Android project + id("com.android.application") // or id("com.android.library") + id("org.jetbrains.kotlin.android") // or kotlin("android") + id("org.jetbrains.kotlin.kapt") // or kotlin("kapt") + + // For a JVM project + id("application") // or id("java-library") + // Optional, if using Kotlin + id("org.jetbrains.kotlin.jvm") // or kotlin("jvm") + id("org.jetbrains.kotlin.kapt") // or kotlin("kapt") + + // Finally, apply the plugin + id("io.objectbox") } ``` -
- -Finally, sync the Gradle project with your IDE (for ex. using "Sync Project with Gradle Files" in Android Studio). - -Your project can now use ObjectBox, continue by [defining entity classes](https://docs.objectbox.io/getting-started#define-entity-classes). - ### Maven setup This is currently only supported for JVM projects. From 1d28a0fbc9888b6f673731c8007d87ac737cada2 Mon Sep 17 00:00:00 2001 From: Uwe Date: Mon, 9 Feb 2026 12:01:04 +0100 Subject: [PATCH 2/9] README: update setup instructions for AGP 9.0 --- README.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b0ec5d09..cc40359f 100644 --- a/README.md +++ b/README.md @@ -153,7 +153,11 @@ kotlin = "" # Add an alias for the plugin objectbox = { id = "io.objectbox", version.ref = "objectbox" } -# For an Android project +# 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" } @@ -170,7 +174,11 @@ plugins { // Add the plugin alias(libs.plugins.objectbox) apply false - // For an Android project + // 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 @@ -207,7 +215,11 @@ Then, in the Gradle script of your subproject apply the necessary plugins: // app/build.gradle.kts plugins { - // For an Android project + // 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) @@ -314,7 +326,11 @@ Then, in the Gradle script of your subproject apply the necessary plugins using // app/build.gradle.kts plugins { - // For an Android project + // For an Android project, using Android Gradle Plugin 9.0 or newer + id("com.android.application") // or id("com.android.library") + id("com.android.legacy-kapt") + + // For an Android project, using Android Gradle Plugin 8.13 or older id("com.android.application") // or id("com.android.library") id("org.jetbrains.kotlin.android") // or kotlin("android") id("org.jetbrains.kotlin.kapt") // or kotlin("kapt") From 66da77d02632ea597b77d8c9e19926f4d82de9a5 Mon Sep 17 00:00:00 2001 From: Uwe Date: Mon, 16 Feb 2026 14:04:46 +0100 Subject: [PATCH 3/9] Build: don't use snapshots on main branch This is safe, because Maven artifacts are not published from main branch on CI. --- build.gradle.kts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/build.gradle.kts b/build.gradle.kts index 3f25d922..cc428eb0 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -26,7 +26,8 @@ buildscript { // see the release checklist in the objectbox repo. // If true won't build snapshots and removes version post fix (e.g. "-dev-SNAPSHOT"), // uses release versions of dependencies. - val isRelease = System.getenv("OBX_RELEASE") == "true" + // val isRelease = System.getenv("OBX_RELEASE") == "true" + val isRelease = true // On (public) main branch don't use snapshots (publishing is disabled in CI for main branch) // version post fix: "-" or "" if not defined; e.g. used by CI to pass in branch name val versionPostFixValue = project.findProperty("versionPostFix") From eedc4d1dbf2952a5aaadc3c9c898f090d70147d0 Mon Sep 17 00:00:00 2001 From: Uwe Date: Tue, 17 Feb 2026 09:56:55 +0100 Subject: [PATCH 4/9] Changelog: add Admin changes for 5.2.0 release --- CHANGELOG.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d8a7993f..3b77d5b4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,13 +2,17 @@ Notable changes to the ObjectBox Java library. -For more insights into what changed in the ObjectBox C++ core, [check the ObjectBox C changelog](https://github.com/objectbox/objectbox-c/blob/main/CHANGELOG.md). +For more insights into what changed in the database libraries, [check the ObjectBox C changelog](https://github.com/objectbox/objectbox-c/blob/main/CHANGELOG.md). ## 5.2.0 - 2026-02-16 - The [ObjectBox Gradle plugin](https://github.com/objectbox/objectbox-java-generator) requires JDK 11 and Android Gradle Plugin 8.1 or newer. - Update database libraries for Android and JVM to database version `5.1.1-pre-2026-02-16`. +- Admin: new "Counts and Sizes" view (via Status page) to give an overview over all types their object counts and sizes +- Admin: fix reload via browser to stay on the page +- Admin: schema view to display flags as text +- Admin: refresh button for the data view ### Sync From cdc03bb0e433e501e065c288de5edc381d9bf843 Mon Sep 17 00:00:00 2001 From: Uwe Date: Tue, 17 Feb 2026 12:57:34 +0100 Subject: [PATCH 5/9] README: drop duplicate snippet introduced by merge --- README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/README.md b/README.md index efbf47c1..75479010 100644 --- a/README.md +++ b/README.md @@ -154,12 +154,6 @@ agp = "" # If using Kotlin kotlin = "" -# For an Android project -agp = "" - -# If using Kotlin -kotlin = "" - [plugins] # Add an alias for the plugin objectbox = { id = "io.objectbox", version.ref = "objectbox" } From 2191d94730263d3805c6c94ed01ca9e3371738a3 Mon Sep 17 00:00:00 2001 From: Uwe Date: Tue, 17 Feb 2026 13:19:35 +0100 Subject: [PATCH 6/9] README: note to add Maven Central to dependency repos as well --- README.md | 38 +++++++++++++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 75479010..601d6ea2 100644 --- a/README.md +++ b/README.md @@ -192,6 +192,13 @@ plugins { alias(libs.plugins.kotlin.jvm) apply false alias(libs.plugins.kotlin.kapt) apply false } + +allprojects { + repositories { + // Add Maven Central to the dependency repositories + mavenCentral() + } +} ``` ```kotlin @@ -199,7 +206,7 @@ plugins { pluginManagement { repositories { - // Add the Maven Central repository + // Add Maven Central to the plugin repositories mavenCentral() } @@ -255,6 +262,13 @@ plugins { // Add the plugin id("io.objectbox") version "5.2.0" apply false } + +allprojects { + repositories { + // Add Maven Central to the dependency repositories + mavenCentral() + } +} ``` ```kotlin @@ -262,7 +276,7 @@ plugins { pluginManagement { repositories { - // Add the Maven Central repository + // Add Maven Central to the plugin repositories mavenCentral() } @@ -288,8 +302,8 @@ buildscript { // Define a variable for the plugin version val objectboxVersion by extra("5.2.0") - repositories { - // Add the Maven Central repository + repositories { + // Add Maven Central to the plugin repositories mavenCentral() } @@ -298,6 +312,13 @@ buildscript { classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion") } } + +allprojects { + repositories { + // Add Maven Central to the dependency repositories + mavenCentral() + } +} ```
@@ -312,7 +333,7 @@ buildscript { ext.objectboxVersion = "5.2.0" repositories { - // Add the Maven Central repository + // Add Maven Central to the plugin repositories mavenCentral() } @@ -321,6 +342,13 @@ buildscript { classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion") } } + +allprojects { + repositories { + // Add Maven Central to the dependency repositories + mavenCentral() + } +} ``` From 31bba7e16e2843864bb71a468500b95dabe1c553 Mon Sep 17 00:00:00 2001 From: Uwe Date: Wed, 11 Mar 2026 07:29:38 +0100 Subject: [PATCH 7/9] README: remove outdated repositories block added during merge --- README.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/README.md b/README.md index 2e2a85a8..1e636af9 100644 --- a/README.md +++ b/README.md @@ -191,13 +191,6 @@ plugins { // Add the ObjectBox plugin alias(libs.plugins.objectbox) apply false } - -allprojects { - repositories { - // Add Maven Central to the dependency repositories - mavenCentral() - } -} ``` ```kotlin @@ -260,13 +253,6 @@ plugins { // Add the ObjectBox plugin id("io.objectbox") version "5.3.0" apply false } - -allprojects { - repositories { - // Add Maven Central to the dependency repositories - mavenCentral() - } -} ``` ```kotlin From 99aaf32dfce7fceec6508ed52f99a3a3c3fd27ac Mon Sep 17 00:00:00 2001 From: Uwe Date: Mon, 30 Mar 2026 12:19:53 +0200 Subject: [PATCH 8/9] Changelog: not update to database version 5.3.1-2026-03-26 --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ed503246..c9307d6b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ For more insights into what changed in the database libraries, [check the Object ## 5.4.1 - 2026-03-26 +- Update Android and JVM libraries to database version `5.3.1-2026-03-26` + ### Sync - Critical fix for sync clock property handling From 45126c80fd6f39e0e1a32000cf2f6e79b7b6e787 Mon Sep 17 00:00:00 2001 From: Uwe Date: Mon, 30 Mar 2026 14:42:15 +0200 Subject: [PATCH 9/9] Build: merge-resistant way of enabling release versions on main branch --- .gitlab-ci.yml | 33 +++++++++++++++++++++++---------- build.gradle.kts | 22 ++++++---------------- 2 files changed, 29 insertions(+), 26 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 8554478c..fa0442a9 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -16,12 +16,16 @@ image: objectboxio/buildenv-core:2025-07-03 # With JDK 21 # - ORG_GRADLE_PROJECT_signingPassword variables: - OBX_RELEASE: + OBX_PUBLISH_RELEASE: value: "false" options: [ "false", "true" ] - description: "Turns on the release flag in the Gradle root build script, which triggers building and publishing a - release of Java libraries to the internal GitLab repository and Maven Central. + description: "If enabled, builds and depends on release versions and triggers publishing a + release of the Java library artifacts to the internal GitLab repository and Maven Central. + Don't run multiple times to avoid duplicate artifacts in the GitLab repository. Consult the release checklist before turning this on." + # If enabled, builds and depends on release versions. Doesn't publish a release. + # See the root Gradle build script for details. + OBX_RELEASE: "false" # Disable the Gradle daemon. Gradle may run in a Docker container with a shared # Docker volume containing GRADLE_USER_HOME. If the container is stopped after a job @@ -50,6 +54,14 @@ workflow: # Never create a pipeline when a tag is pushed (to simplify version computation in root build script) - if: $CI_COMMIT_TAG when: never + # On main branch, always use release versions as old snapshots of dependencies are deleted + - if: $CI_COMMIT_REF_NAME == "main" + variables: + OBX_RELEASE: "true" + # To publish a release must use release versions + - if: $OBX_PUBLISH_RELEASE == "true" + variables: + OBX_RELEASE: "true" # In all other cases, create a pipeline - when: always @@ -166,8 +178,9 @@ publish-maven-internal: - linux - x64 rules: - # Not for main branch, doing so may duplicate release artifacts (uploaded from publish branch) - - if: $CI_COMMIT_BRANCH == "main" + # Not when using release versions and not publishing a release to avoid duplicate artifacts + # (GitLab would allow to upload duplicates for a release version) + - if: $OBX_RELEASE == "true" && $OBX_PUBLISH_RELEASE != "true" when: never # Not if triggered by upstream project to save on disk space - if: $CI_PIPELINE_SOURCE == "pipeline" @@ -188,8 +201,8 @@ publish-maven-central: - linux - x64 rules: - # Only if release mode is on, only if no previous stages failed - - if: $OBX_RELEASE == "true" + # Only if publishing a release, only if no previous stages failed + - if: $OBX_PUBLISH_RELEASE == "true" when: on_success before_script: - ci/send-to-gchat.sh "$GOOGLE_CHAT_WEBHOOK_JAVA_CI" --thread $CI_COMMIT_SHA "*Releasing Java library:* job $CI_JOB_NAME from branch $CI_COMMIT_BRANCH ($CI_COMMIT_SHORT_SHA)..." @@ -209,8 +222,8 @@ package-api-docs: - linux - x64 rules: - # Only if release mode is on, only if no previous stages failed - - if: $OBX_RELEASE == "true" + # Only if publishing a release, only if no previous stages failed + - if: $OBX_PUBLISH_RELEASE == "true" when: on_success script: - ./gradlew $GITLAB_REPO_ARGS $VERSION_ARGS :objectbox-java:packageJavadocForWeb @@ -225,7 +238,7 @@ trigger-plugin: stage: triggers rules: # Not when publishing a release - - if: $OBX_RELEASE == "true" + - if: $OBX_PUBLISH_RELEASE == "true" when: never # Do not trigger publishing of plugin - if: $CI_COMMIT_BRANCH == "publish" diff --git a/build.gradle.kts b/build.gradle.kts index de34bb68..cc781b3d 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -5,8 +5,7 @@ // - sonatypeUsername: Maven Central credential used by Nexus publishing. // - sonatypePassword: Maven Central credential used by Nexus publishing. // This script supports the following environment variables: -// - OBX_RELEASE: If set to "true" builds release versions without version postfix. -// Otherwise, will build snapshot versions. +// - OBX_RELEASE: If set to "true" builds and depends on release versions, without branch name and snapshot suffix. plugins { // https://github.com/ben-manes/gradle-versions-plugin/releases @@ -22,12 +21,11 @@ buildscript { // Should only be changed as part of the release process, see the release checklist in the objectbox repo val versionNumber = "5.4.1" - // Release mode should only be enabled when manually triggering a CI pipeline, - // see the release checklist in the objectbox repo. - // If true won't build snapshots and removes version post fix (e.g. "-dev-SNAPSHOT"), - // uses release versions of dependencies. - // val isRelease = System.getenv("OBX_RELEASE") == "true" - val isRelease = true // On (public) main branch don't use snapshots (publishing is disabled in CI for main branch) + // If OBX_RELEASE is set, build and depend on release versions. Doesn't publish a release. + // See the release checklist in the objectbox repo on how to publish a release. + // If true, Maven artifacts use a release version, so without branch name and snapshot suffix + // (such as "-dev-SNAPSHOT"), including for dependencies (such as objectbox-java). + val isRelease = System.getenv("OBX_RELEASE") == "true" // version post fix: "-" or "" if not defined; e.g. used by CI to pass in branch name val versionPostFixValue = project.findProperty("versionPostFix") @@ -49,14 +47,6 @@ buildscript { println("version=$obxJavaVersion") println("objectboxNativeDependency=$obxJniLibVersion") - // To avoid duplicate release artifacts on the internal repository, - // prevent publishing from branches other than publish, and main (for which publishing is turned off). - val isCI = System.getenv("CI") == "true" - val branchOrTag = System.getenv("CI_COMMIT_REF_NAME") - if (isCI && isRelease && !("publish" == branchOrTag || "main" == branchOrTag)) { - throw GradleException("isRelease = true only allowed on publish or main branch, but is $branchOrTag") - } - // Versions for third party dependencies and plugins val essentialsVersion by extra("3.1.0") val junitVersion by extra("4.13.2")