Merge branch '259-fix-javadoc-errors' into dev

Author: greenrobot-team

.gitignore

@@ -12,7 +12,6 @@ gen/
 target/
 out/
 classes/
-gradle.properties
 
 # Local build properties
 build.properties

.gitlab-ci.yml

@@ -16,9 +16,8 @@ variables:
   # 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
   # Gradle daemons may get killed, preventing proper clean-up of lock files in GRADLE_USER_HOME.
-  # Configure file.encoding to always use UTF-8 when running Gradle.
   # Use low priority processes to avoid Gradle builds consuming all build machine resources.
-  GRADLE_OPTS: "-Dorg.gradle.daemon=false -Dfile.encoding=UTF-8 -Dorg.gradle.priority=low"
+  GRADLE_OPTS: "-Dorg.gradle.daemon=false -Dorg.gradle.priority=low"
   GITLAB_REPO_ARGS: "-PgitlabUrl=$CI_SERVER_URL -PgitlabPrivateTokenName=Deploy-Token -PgitlabPrivateToken=$OBX_READ_PACKAGES_TOKEN"
   GITLAB_PUBLISH_ARGS: "-PgitlabPublishTokenName=Job-Token -PgitlabPublishToken=$CI_JOB_TOKEN"
   CENTRAL_PUBLISH_ARGS: "-PsonatypeUsername=$SONATYPE_USER -PsonatypePassword=$SONATYPE_PWD"

build.gradle.kts

@@ -87,6 +87,13 @@ allprojects {
             cacheChangingModulesFor(0, "seconds")
         }
     }
+
+    tasks.withType<Javadoc>().configureEach {
+        // To support Unicode characters in API docs force the javadoc tool to use UTF-8 encoding.
+        // Otherwise, it defaults to the system file encoding. This is required even though setting file.encoding
+        // for the Gradle daemon (see gradle.properties) as Gradle does not pass it on to the javadoc tool.
+        options.encoding = "UTF-8"
+    }
 }
 
 tasks.wrapper {

buildSrc/src/main/kotlin/objectbox-publish.gradle.kts

@@ -17,13 +17,6 @@ plugins {
     id("signing")
 }
 
-// Make javadoc task errors not break the build, some are in third-party code.
-if (JavaVersion.current().isJava8Compatible) {
-    tasks.withType<Javadoc> {
-        isFailOnError = false
-    }
-}
-
 publishing {
     repositories {
         maven {

gradle.properties

@@ -0,0 +1,8 @@
+# Gradle configuration
+# https://docs.gradle.org/current/userguide/build_environment.html
+
+# To support Unicode characters in source code, set UTF-8 as the file encoding for the Gradle daemon,
+# which will make most Java tools use it instead of the default system file encoding. Note that for API docs,
+# the javadoc tool must be configured separately, see the root build script.
+# https://docs.gradle.org/current/userguide/common_caching_problems.html#system_file_encoding
+org.gradle.jvmargs=-Dfile.encoding=UTF-8

objectbox-java/build.gradle

@@ -35,18 +35,28 @@ tasks.spotbugsMain {
     }
 }
 
+// Note: used for the Maven javadoc artifact, a separate task is used to build API docs to publish online
 javadoc {
-    // Hide internal API from javadoc artifact.
+    // Internal Java APIs
     exclude("**/io/objectbox/Cursor.java")
     exclude("**/io/objectbox/KeyValueCursor.java")
     exclude("**/io/objectbox/ModelBuilder.java")
     exclude("**/io/objectbox/Properties.java")
     exclude("**/io/objectbox/Transaction.java")
-    exclude("**/io/objectbox/model/**")
     exclude("**/io/objectbox/ideasonly/**")
     exclude("**/io/objectbox/internal/**")
     exclude("**/io/objectbox/reactive/DataPublisherUtils.java")
     exclude("**/io/objectbox/reactive/WeakDataObserver.java")
+    exclude("**/io/objectbox/sync/server/ClusterPeerInfo.java")
+    // Repackaged FlatBuffers distribution
+    exclude("**/io/objectbox/flatbuffers/**")
+    // FlatBuffers generated files only used internally (note: some are part of the public API)
+    exclude("**/io/objectbox/model/**")
+    exclude("**/io/objectbox/sync/Credentials.java")
+    exclude("**/io/objectbox/sync/CredentialsType.java")
+    exclude("**/io/objectbox/sync/server/ClusterPeerConfig.java")
+    exclude("**/io/objectbox/sync/server/JwtConfig.java")
+    exclude("**/io/objectbox/sync/server/SyncServerOptions.java")
 }
 
 // Note: use packageJavadocForWeb to get as ZIP.
@@ -55,33 +65,41 @@ tasks.register('javadocForWeb', Javadoc) {
     description = 'Builds Javadoc incl. objectbox-java-api classes with web tweaks.'
 
     javadocTool = javaToolchains.javadocToolFor {
-        // Note: the style changes only work if using JDK 10+, 11 is latest LTS.
-        languageVersion = JavaLanguageVersion.of(11)
+        // Note: the style changes only work if using JDK 10+, 17 is the LTS release used to publish this
+        languageVersion = JavaLanguageVersion.of(17)
     }
 
     def srcApi = project(':objectbox-java-api').file('src/main/java/')
     if (!srcApi.directory) throw new GradleScriptException("Not a directory: ${srcApi}", null)
     // Hide internal API from javadoc artifact.
     def filteredSources = sourceSets.main.allJava.matching {
+        // Internal Java APIs
         exclude("**/io/objectbox/Cursor.java")
         exclude("**/io/objectbox/KeyValueCursor.java")
         exclude("**/io/objectbox/ModelBuilder.java")
         exclude("**/io/objectbox/Properties.java")
         exclude("**/io/objectbox/Transaction.java")
-        exclude("**/io/objectbox/flatbuffers/**")
         exclude("**/io/objectbox/ideasonly/**")
         exclude("**/io/objectbox/internal/**")
-        exclude("**/io/objectbox/model/**")
         exclude("**/io/objectbox/reactive/DataPublisherUtils.java")
         exclude("**/io/objectbox/reactive/WeakDataObserver.java")
+        exclude("**/io/objectbox/sync/server/ClusterPeerInfo.java")
+        // Repackaged FlatBuffers distribution
+        exclude("**/io/objectbox/flatbuffers/**")
+        // FlatBuffers generated files only used internally (note: some are part of the public API)
+        exclude("**/io/objectbox/model/**")
+        exclude("**/io/objectbox/sync/Credentials.java")
+        exclude("**/io/objectbox/sync/CredentialsType.java")
+        exclude("**/io/objectbox/sync/server/ClusterPeerConfig.java")
+        exclude("**/io/objectbox/sync/server/JwtConfig.java")
+        exclude("**/io/objectbox/sync/server/SyncServerOptions.java")
     }
     source = filteredSources + srcApi
 
     classpath = sourceSets.main.output + sourceSets.main.compileClasspath
     destinationDir = file(javadocForWebDir)
 
     title = "ObjectBox Java ${version} API"
-    options.encoding = 'UTF-8' // Set UTF-8 encoding to support unicode characters used in docs
     options.overview = "$projectDir/src/web/overview.html"
     options.bottom = 'Available under the Apache License, Version 2.0 - <i>Copyright &#169; 2017-2024 <a href="https://objectbox.io/">ObjectBox Ltd</a>. All Rights Reserved.</i>'
 

objectbox-java/src/main/java/io/objectbox/relation/ToMany.java

@@ -58,7 +58,7 @@
  * <pre>{@code
  * // Java
  * @Entity
- * public class Student{
+ * public class Student {
  *     private ToMany<Teacher> teachers;
  * }
  *
@@ -85,7 +85,6 @@
  * <p>
  * To apply (persist) the changes to the database, call {@link #applyChangesToDb()} or put the object with the ToMany.
  * For important details, see the notes about relations of {@link Box#put(Object)}.
- * <p>
  * <pre>{@code
  * // Example 1: add target objects to a relation
  * student.getTeachers().add(teacher1);

objectbox-java/src/main/java/io/objectbox/relation/ToOne.java

@@ -61,7 +61,6 @@
  * </ul>
  * <p>
  * Then, to persist the changes {@link Box#put} the object with the ToOne.
- * <p>
  * <pre>{@code
  * // Example 1: create a relation
  * order.getCustomer().setTarget(customer);

objectbox-java/src/main/java/io/objectbox/sync/Sync.java

@@ -44,7 +44,7 @@ public static boolean isServerAvailable() {
     }
 
     /**
-     * Returns true if the included native (JNI) ObjectBox library supports Sync hybrids (server & client).
+     * Returns true if the included native (JNI) ObjectBox library supports Sync hybrids (server and client).
      */
     public static boolean isHybridAvailable() {
         return isAvailable() && isServerAvailable();

objectbox-java/src/main/java/io/objectbox/sync/SyncFlags.java

@@ -25,7 +25,7 @@
 public final class SyncFlags {
   private SyncFlags() { }
   /**
-   * Enable (rather extensive) logging on how IDs are mapped (local <-> global)
+   * Enable (rather extensive) logging on how IDs are mapped (local &lt;-&gt; global)
    */
   public static final int DebugLogIdMapping = 1;
   /**