Merge branch 'dev' into main

Author: greenrobot

README.md

@@ -1,12 +1,12 @@
 <img width="466" src="https://raw.githubusercontent.com/objectbox/objectbox-java/master/logo.png">
 
-[![Follow ObjectBox on Twitter](https://img.shields.io/twitter/follow/ObjectBox_io.svg?style=flat-square&logo=twitter&color=fff)](https://twitter.com/ObjectBox_io)
+[![Follow ObjectBox on Twitter](https://img.shields.io/twitter/follow/ObjectBox_io.svg?style=flat-square&logo=twitter)](https://twitter.com/intent/follow?screen_name=ObjectBox_io)
 
 # ObjectBox Java (Kotlin, Android)
 ObjectBox is a superfast object-oriented database with strong relation support.
 ObjectBox is embedded into your Android, Linux, macOS, or Windows app.
 
-**Latest version: [2.7.1 (2020/08/19)](https://docs.objectbox.io/#objectbox-changelog)**
+**Latest version: [2.8.0 (2020/11/04)](https://docs.objectbox.io/#objectbox-changelog)**
 
 Demo code using ObjectBox:
 
@@ -33,7 +33,7 @@ Add this to your root build.gradle (project level):
 
 ```groovy
 buildscript {
-    ext.objectboxVersion = '2.7.1'
+    ext.objectboxVersion = '2.8.0'
     dependencies {
         classpath "io.objectbox:objectbox-gradle-plugin:$objectboxVersion"
     }

build.gradle

@@ -1,7 +1,7 @@
 buildscript {
     ext {
         // Typically, only edit those two:
-        def objectboxVersionNumber = '2.7.1' // without "-SNAPSHOT", e.g. '2.5.0' or '2.4.0-RC'
+        def objectboxVersionNumber = '2.8.0' // without "-SNAPSHOT", e.g. '2.5.0' or '2.4.0-RC'
         def objectboxVersionRelease = true  // set to true for releasing to ignore versionPostFix to avoid e.g. "-dev" versions
 
         // version post fix: '-<value>' or '' if not defined; e.g. used by CI to pass in branch name
@@ -19,9 +19,10 @@ buildscript {
                 : 'unsupported'
         ob_native_dep = "io.objectbox:objectbox-$objectboxPlatform:$nativeVersion"
 
-        junit_version = '4.13'
+        essentials_version = '3.1.0'
+        junit_version = '4.13.1'
         mockito_version = '3.3.3'
-        kotlin_version = '1.3.72'
+        kotlin_version = '1.4.10'
         dokka_version = '0.10.1'
 
         println "version=$ob_version"
@@ -39,7 +40,8 @@ buildscript {
     dependencies {
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
         classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokka_version"
-        classpath "gradle.plugin.com.github.spotbugs.snom:spotbugs-gradle-plugin:4.0.5"
+        // https://github.com/spotbugs/spotbugs-gradle-plugin/releases
+        classpath "gradle.plugin.com.github.spotbugs.snom:spotbugs-gradle-plugin:4.5.1"
     }
 }
 
@@ -113,7 +115,7 @@ configure(subprojects.findAll { projectNamesToPublish.contains(it.name) }) {
 
                     if (preferredRepo == 'local') {
                         repository url: repositories.mavenLocal().url
-                        println "Uploading archives to mavenLocal()."
+                        println "uploadArchives repo is mavenLocal()."
                     } else if (preferredRepo != null
                             && project.hasProperty('preferredUsername') 
                             && project.hasProperty('preferredPassword')) {
@@ -131,7 +133,7 @@ configure(subprojects.findAll { projectNamesToPublish.contains(it.name) }) {
                             authentication(userName: preferredUsername, password: preferredPassword)
                         }
 
-                        println "Uploading archives to $repositoryUrl."
+                        println "uploadArchives repo is $repositoryUrl."
                     } else if (project.hasProperty('sonatypeUsername')
                             && project.hasProperty('sonatypePassword')) {
                         beforeDeployment { MavenDeployment deployment -> signing.signPom(deployment) }
@@ -144,9 +146,9 @@ configure(subprojects.findAll { projectNamesToPublish.contains(it.name) }) {
                             authentication(userName: sonatypeUsername, password: sonatypePassword)
                         }
 
-                        println "Uploading archives to $sonatypeRepositoryUrl."
+                        println "uploadArchives repo is $sonatypeRepositoryUrl."
                     } else {
-                        println "WARNING: preferredRepo or credentials NOT set, can not upload archives."
+                        println "WARNING: uploadArchives settings incomplete, can not upload archives."
                     }
 
                     pom.project {

gradle/wrapper/gradle-wrapper.jar

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-6.3-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-6.7-all.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

gradle/wrapper/gradle-wrapper.properties

@@ -82,6 +82,7 @@ esac
 
 CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
 
+
 # Determine the Java command to use to start the JVM.
 if [ -n "$JAVA_HOME" ] ; then
     if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
@@ -129,6 +130,7 @@ fi
 if [ "$cygwin" = "true" -o "$msys" = "true" ] ; then
     APP_HOME=`cygpath --path --mixed "$APP_HOME"`
     CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
+
     JAVACMD=`cygpath --unix "$JAVACMD"`
 
     # We build the pattern for arguments to be converted via cygpath

gradlew

@@ -40,7 +40,7 @@ if defined JAVA_HOME goto findJavaFromJavaHome
 
 set JAVA_EXE=java.exe
 %JAVA_EXE% -version >NUL 2>&1
-if "%ERRORLEVEL%" == "0" goto init
+if "%ERRORLEVEL%" == "0" goto execute
 
 echo.
 echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
@@ -54,7 +54,7 @@ goto fail
 set JAVA_HOME=%JAVA_HOME:"=%
 set JAVA_EXE=%JAVA_HOME%/bin/java.exe
 
-if exist "%JAVA_EXE%" goto init
+if exist "%JAVA_EXE%" goto execute
 
 echo.
 echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
@@ -64,28 +64,14 @@ echo location of your Java installation.
 
 goto fail
 
-:init
-@rem Get command-line arguments, handling Windows variants
-
-if not "%OS%" == "Windows_NT" goto win9xME_args
-
-:win9xME_args
-@rem Slurp the command line arguments.
-set CMD_LINE_ARGS=
-set _SKIP=2
-
-:win9xME_args_slurp
-if "x%~1" == "x" goto execute
-
-set CMD_LINE_ARGS=%*
-
 :execute
 @rem Setup the command line
 
 set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
 
+
 @rem Execute Gradle
-"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS%
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
 
 :end
 @rem End local scope for the variables with windows NT shell

gradlew.bat

@@ -6,8 +6,9 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation for an entity base class.
- * ObjectBox will include properties of an entity super class marked with this annotation.
+ * Marks a class as an ObjectBox Entity super class.
+ * ObjectBox will store properties of this class as part of an Entity that inherits from this class.
+ * See <a href="https://docs.objectbox.io/advanced/entity-inheritance">the Entity Inheritance documentation</a> for details.
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.TYPE)

objectbox-java-api/src/main/java/io/objectbox/annotation/BaseEntity.java

@@ -16,25 +16,29 @@
 
 package io.objectbox.annotation;
 
-import io.objectbox.converter.PropertyConverter;
-
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import io.objectbox.converter.PropertyConverter;
+
 /**
- * Specifies {@link PropertyConverter} for the field to support custom types
+ * Supplies a {@link PropertyConverter converter} to store custom Property types as a supported {@link #dbType()}.
+ * See the <a href="https://docs.objectbox.io/advanced/custom-types">Custom Types documentation</a> for details.
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.FIELD)
 public @interface Convert {
-    /** Converter class */
+    /**
+     * The converter class that ObjectBox should use. See {@link PropertyConverter} for implementation guidelines.
+     */
     Class<? extends PropertyConverter> converter();
 
     /**
-     * Class of the DB type the Java property is converted to/from.
-     * This is limited to all java classes which are supported natively by ObjectBox.
+     * The Property type the Java field value is converted to/from.
+     * See the <a href="https://docs.objectbox.io/advanced/custom-types">Custom Types documentation</a> for a list
+     * of supported types.
      */
     Class dbType();
 }

objectbox-java-api/src/main/java/io/objectbox/annotation/Convert.java

@@ -22,8 +22,8 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation for entities
- * ObjectBox only persist objects of classes which are marked with this annotation
+ * Marks a class as an ObjectBox Entity.
+ * Allows to obtain a Box for this Entity from BoxStore to persist Objects of this class.
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.TYPE)

objectbox-java-api/src/main/java/io/objectbox/annotation/Entity.java

@@ -0,0 +1,17 @@
+package io.objectbox.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Enables sync for an {@link Entity} class.
+ * <p>
+ * Note that currently sync can not be enabled or disabled for existing entities.
+ * Also synced entities can not have relations to non-synced entities.
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.TYPE)
+public @interface Sync {
+}

objectbox-java-api/src/main/java/io/objectbox/annotation/Sync.java

@@ -16,9 +16,9 @@
 
 /**
  * Annotations to mark a class as an {@link io.objectbox.annotation.Entity @Entity},
- * to specify the {@link io.objectbox.annotation.Id @Id} property,
+ * to specify the {@link io.objectbox.annotation.Id @Id} Property,
  * to create an {@link io.objectbox.annotation.Index @Index} or
- * a {@link io.objectbox.annotation.Transient @Transient} property.
+ * a {@link io.objectbox.annotation.Transient @Transient} Property.
  * <p>
  * For more details look at the documentation of individual classes and
  * <a href="https://docs.objectbox.io/entity-annotations">docs.objectbox.io/entity-annotations</a>.

objectbox-java-api/src/main/java/io/objectbox/annotation/apihint/Temporary.java

@@ -16,7 +16,7 @@
 
 /**
  * For use with {@link io.objectbox.annotation.Convert @Convert}: {@link io.objectbox.converter.PropertyConverter}
- * to convert custom property types.
+ * to convert custom Property types.
  * <p>
  * For more details look at the documentation of individual classes and
  * <a href="https://docs.objectbox.io/advanced/custom-types">docs.objectbox.io/advanced/custom-types</a>.

objectbox-java-api/src/main/java/io/objectbox/annotation/package-info.java

@@ -10,11 +10,12 @@ ext {
 
 dependencies {
     api project(':objectbox-java-api')
-    implementation 'org.greenrobot:essentials:3.0.0-RC1'
+    implementation "org.greenrobot:essentials:$essentials_version"
     implementation 'com.google.flatbuffers:flatbuffers-java:1.12.0'
     api 'com.google.code.findbugs:jsr305:3.0.2'
 
-    compileOnly 'com.github.spotbugs:spotbugs-annotations:4.0.4'
+    // https://github.com/spotbugs/spotbugs/blob/master/CHANGELOG.md
+    compileOnly 'com.github.spotbugs:spotbugs-annotations:4.1.4'
 }
 
 spotbugs {

objectbox-java-api/src/main/java/io/objectbox/converter/package-info.java

@@ -39,11 +39,10 @@
 import io.objectbox.relation.RelationInfo;
 
 /**
- * A box to store objects of a particular class.
+ * A Box to put and get Objects of a specific Entity class.
  * <p>
  * Thread-safe.
  */
-@Beta
 @ThreadSafe
 @SuppressWarnings("WeakerAccess,UnusedReturnValue,unused")
 public class Box<T> {