Merge branch 'v2.4.1'

Author: greenrobot-team

README.md

@@ -4,7 +4,7 @@
 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.4.0 (2019/10/15)](https://objectbox.io/changelog)**
+**Latest version: [2.4.1 (2019/10/29)](https://objectbox.io/changelog)**
 
 Demo code using ObjectBox:
 
@@ -30,7 +30,7 @@ Add this to your root build.gradle (project level):
 
 ```groovy
 buildscript {
-    ext.objectboxVersion = '2.4.0'
+    ext.objectboxVersion = '2.4.1'
     dependencies {
         classpath "io.objectbox:objectbox-gradle-plugin:$objectboxVersion"
     }

build.gradle

@@ -6,16 +6,16 @@ buildscript {
         // version post fix: '-<value>' or '' if not defined; e.g. used by CI to pass in branch name
         def versionPostFixValue = project.findProperty('versionPostFix')
         def versionPostFix = versionPostFixValue ? "-$versionPostFixValue" : ''
-//        ob_version = "2.4.0$versionPostFix-SNAPSHOT"
-        ob_version = "2.4.0"
+//        ob_version = "2.4.1$versionPostFix-SNAPSHOT"
+        ob_version = "2.4.1"
         println "ObjectBox Java version $ob_version"
 
         ob_expected_version = project.hasProperty('expectedVersion') ? project.property('expectedVersion') : 'UNDEFINED'
 
         // Core version for tests
         // Be careful to diverge here; easy to forget and hard to find JNI problems
-//        ob_native_version = "2.4.0-dev-SNAPSHOT"
-        ob_native_version = "2.4.0"
+//        ob_native_version = "2.4.1-dev-SNAPSHOT"
+        ob_native_version = "2.4.1"
 
         def osName = System.getProperty("os.name").toLowerCase()
         objectboxPlatform = osName.contains('linux') ? 'linux'

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

@@ -22,7 +22,11 @@
 import java.lang.annotation.Target;
 
 /**
- * Marks field is the primary key of the entity's table
+ * Marks the ID property of an {@link Entity @Entity}.
+ * The property must be of type long (or Long in Kotlin) and have not-private visibility
+ * (or a not-private getter and setter method).
+ * <p>
+ * ID properties are unique and indexed by default.
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.FIELD)
@@ -35,8 +39,10 @@
 //    boolean monotonic() default false;
 
     /**
-     * Allows IDs to be assigned by the developer. This may make sense for using IDs originating somewhere else, e.g.
-     * from the server.
+     * Allows IDs of new entities to be assigned manually.
+     * Warning: This has side effects, check the online documentation on self-assigned object IDs for details.
+     * <p>
+     * This may allow re-use of IDs assigned elsewhere, e.g. by a server.
      */
     boolean assignable() default false;
 }

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

@@ -21,15 +21,20 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-import io.objectbox.annotation.apihint.Internal;
-
 /**
- * Specifies that the property should be indexed, which is highly recommended if you do queries using this property.
- *
- * To fine tune indexing you can specify {@link IndexType} if necessary.
+ * Specifies that the property should be indexed.
+ * <p>
+ * It is highly recommended to index properties that are used in a query to improve query performance.
+ * <p>
+ * To fine tune indexing of a property you can override the default index {@link #type()}.
+ * <p>
+ * Note: indexes are currently not supported for byte array, float or double properties.
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.FIELD)
 public @interface Index {
+    /**
+     * Sets the {@link IndexType}, defaults to {@link IndexType#DEFAULT}.
+     */
     IndexType type() default IndexType.DEFAULT;
 }

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

@@ -17,20 +17,22 @@
 package io.objectbox.annotation;
 
 /**
- * ObjectBox offers three index types, from which it chooses from with a reasonable default (see {@link #DEFAULT}).
+ * ObjectBox offers a value and two hash index types, from which it chooses a reasonable default (see {@link #DEFAULT}).
  * <p>
  * For some queries/use cases it might make sense to override the default choice for optimization purposes.
+ * <p>
+ * Note: hash indexes are currently only supported for string properties.
  */
 public enum IndexType {
     /**
      * Use the default index type depending on the property type:
-     * {@link #VALUE} for scalars and {@link #HASH} for Strings and byte arrays.
+     * {@link #VALUE} for scalars and {@link #HASH} for Strings.
      */
     DEFAULT,
 
     /**
      * Use the property value to build the index.
-     * For Strings and byte arrays this may occupy more space than the default setting.
+     * For Strings this may occupy more space than the default setting.
      */
     VALUE,
 

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

@@ -22,12 +22,12 @@
 import java.lang.annotation.Target;
 
 /**
- * Marks values of a property to be unique.
- * The property will be indexed behind the scenes, just like using @{@link Index}.
- * Thus you do not need to put an extra @{@link Index} on the property, unless you want to configure the index with
- * additional parameters.
- *
- * Trying to put object with offending values will result in a UniqueViolationException.
+ * Enforces that the value of a property is unique among all objects in a box before an object can be put.
+ * <p>
+ * Trying to put an object with offending values will result in a UniqueViolationException.
+ * <p>
+ * Unique properties are based on an {@link Index @Index}, so the same restrictions apply.
+ * It is supported to explicitly add the {@link Index @Index} annotation to configure the index.
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.FIELD)

objectbox-java/src/main/java/io/objectbox/BoxStore.java

@@ -64,9 +64,9 @@ public class BoxStore implements Closeable {
     @Nullable public static Object relinker;
 
     /** Change so ReLinker will update native library when using workaround loading. */
-    public static final String JNI_VERSION = "2.4.0";
+    public static final String JNI_VERSION = "2.4.1";
 
-    private static final String VERSION = "2.4.0-2019-10-03";
+    private static final String VERSION = "2.4.1-2019-10-29";
     private static BoxStore defaultStore;
 
     /** Currently used DB dirs with values from {@link #getCanonicalPath(File)}. */
@@ -999,4 +999,23 @@ long panicModeRemoveAllObjects(int entityId) {
         return nativePanicModeRemoveAllObjects(handle, entityId);
     }
 
+    /**
+     * If you want to use the same ObjectBox store using the C API, e.g. via JNI, this gives the required pointer,
+     * which you have to pass on to obx_store_wrap().
+     * The procedure is like this:<br>
+     * 1) you create a BoxStore on the Java side<br>
+     * 2) you call this method to get the native store pointer<br>
+     * 3) you pass the native store pointer to your native code (e.g. via JNI)<br>
+     * 4) your native code calls obx_store_wrap() with the native store pointer to get a OBX_store pointer<br>
+     * 5) Using the OBX_store pointer, you can use the C API.
+     *
+     * Note: Once you {@link #close()} this BoxStore, do not use it from the C API.
+     */
+    public long getNativeStore() {
+        if (closed) {
+            throw new IllegalStateException("Store must still be open");
+        }
+        return handle;
+    }
+
 }