Merge branch '36-property-query-updates' into dev

Author: greenrobot

objectbox-java/src/main/java/io/objectbox/exception/NumericOverflowException.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2019 ObjectBox Ltd. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.objectbox.exception;
+
+/**
+ * Thrown if a property query aggregate function can not compute a result due to a number type overflowing.
+ */
+public class NumericOverflowException extends DbException {
+
+    public NumericOverflowException(String message) {
+        super(message);
+    }
+}

objectbox-java/src/main/java/io/objectbox/query/PropertyQuery.java

@@ -94,6 +94,8 @@ native String nativeFindString(long handle, long cursorHandle, int propertyId, b
 
     native double nativeAvg(long handle, long cursorHandle, int propertyId);
 
+    native long nativeAvgLong(long handle, long cursorHandle, int propertyId);
+
     native long nativeCount(long handle, long cursorHandle, int propertyId, boolean distinct);
 
     /** Clears all values (e.g. distinct and null value). */
@@ -179,7 +181,7 @@ public PropertyQuery nullValue(Object nullValue) {
      * <p>
      * Note: results are not guaranteed to be in any particular order.
      * <p>
-     * See also: {@link #distinct}, {@link #distinct(QueryBuilder.StringOrder)}
+     * See also: {@link #distinct()}, {@link #distinct(QueryBuilder.StringOrder)}
      *
      * @return Found strings
      */
@@ -202,7 +204,7 @@ public String[] call() {
      * <p>
      * Note: results are not guaranteed to be in any particular order.
      * <p>
-     * See also: {@link #distinct}
+     * See also: {@link #distinct()}
      *
      * @return Found longs
      */
@@ -223,7 +225,7 @@ public long[] call() {
      * <p>
      * Note: results are not guaranteed to be in any particular order.
      * <p>
-     * See also: {@link #distinct}
+     * See also: {@link #distinct()}
      */
     public int[] findInts() {
         return (int[]) query.callInReadTx(new Callable<int[]>() {
@@ -242,7 +244,7 @@ public int[] call() {
      * <p>
      * Note: results are not guaranteed to be in any particular order.
      * <p>
-     * See also: {@link #distinct}
+     * See also: {@link #distinct()}
      */
     public short[] findShorts() {
         return (short[]) query.callInReadTx(new Callable<short[]>() {
@@ -261,7 +263,7 @@ public short[] call() {
      * <p>
      * Note: results are not guaranteed to be in any particular order.
      * <p>
-     * See also: {@link #distinct}
+     * See also: {@link #distinct()}
      */
     public char[] findChars() {
         return (char[]) query.callInReadTx(new Callable<char[]>() {
@@ -297,7 +299,7 @@ public byte[] call() {
      * <p>
      * Note: results are not guaranteed to be in any particular order.
      * <p>
-     * See also: {@link #distinct}
+     * See also: {@link #distinct()}
      */
     public float[] findFloats() {
         return (float[]) query.callInReadTx(new Callable<float[]>() {
@@ -316,7 +318,7 @@ public float[] call() {
      * <p>
      * Note: results are not guaranteed to be in any particular order.
      * <p>
-     * See also: {@link #distinct}
+     * See also: {@link #distinct()}
      */
     public double[] findDoubles() {
         return (double[]) query.callInReadTx(new Callable<double[]>() {
@@ -381,8 +383,17 @@ public Double findDouble() {
         return (Double) findNumber();
     }
 
-
-    /** Sums up all values for the given property over all Objects matching the query. */
+    /**
+     * Sums up all values for the given property over all Objects matching the query.
+     *
+     * Note: this method is not recommended for properties of type long unless you know the contents of the DB not to
+     *       overflow. Use {@link #sumDouble()} instead if you cannot guarantee the sum to be in the long value range.
+     * 
+     * @return 0 in case no elements matched the query
+     * @throws io.objectbox.exception.NumericOverflowException if the sum exceeds the numbers {@link Long} can
+     * represent.
+     * This is different from Java arithmetic where it would "wrap around" (e.g. max. value + 1 = min. value).
+     */
     public long sum() {
         return (Long) query.callInReadTx(new Callable<Long>() {
             @Override
@@ -392,7 +403,13 @@ public Long call() {
         });
     }
 
-    /** Sums up all values for the given property over all Objects matching the query. */
+    /** 
+     * Sums up all values for the given property over all Objects matching the query.
+     * 
+     * Note: for integer types int and smaller, {@link #sum()} is usually preferred for sums.
+     *       
+     * @return 0 in case no elements matched the query
+     */
     public double sumDouble() {
         return (Double) query.callInReadTx(new Callable<Double>() {
             @Override
@@ -402,7 +419,11 @@ public Double call() {
         });
     }
 
-    /** Finds the maximum value for the given property over all Objects matching the query. */
+    /**
+     * Finds the maximum value for the given property over all Objects matching the query.
+     *
+     * @return Long.MIN_VALUE in case no elements matched the query
+     */
     public long max() {
         return (Long) query.callInReadTx(new Callable<Long>() {
             @Override
@@ -412,7 +433,11 @@ public Long call() {
         });
     }
 
-    /** Finds the maximum value for the given property over all Objects matching the query. */
+    /** 
+     * Finds the maximum value for the given property over all Objects matching the query.
+     * 
+     * @return NaN in case no elements matched the query
+     */
     public double maxDouble() {
         return (Double) query.callInReadTx(new Callable<Double>() {
             @Override
@@ -422,7 +447,11 @@ public Double call() {
         });
     }
 
-    /** Finds the minimum value for the given property over all Objects matching the query. */
+    /**
+     * Finds the minimum value for the given property over all Objects matching the query.
+     *
+     * @return Long.MAX_VALUE in case no elements matched the query
+     */
     public long min() {
         return (Long) query.callInReadTx(new Callable<Long>() {
             @Override
@@ -432,7 +461,11 @@ public Long call() {
         });
     }
 
-    /** Finds the minimum value for the given property over all Objects matching the query. */
+    /**
+     * Finds the minimum value for the given property over all objects matching the query.
+     *
+     * @return NaN in case no elements matched the query
+     */
     public double minDouble() {
         return (Double) query.callInReadTx(new Callable<Double>() {
             @Override
@@ -442,7 +475,13 @@ public Double call() {
         });
     }
 
-    /** Calculates the average of all values for the given property over all Objects matching the query. */
+    /**
+     * Calculates the average of all values for the given number property over all Objects matching the query.
+     * <p>
+     * For integer properties you can also use {@link #avgLong()}.
+     *
+     * @return NaN in case no elements matched the query
+     */
     public double avg() {
         return (Double) query.callInReadTx(new Callable<Double>() {
             @Override
@@ -452,6 +491,27 @@ public Double call() {
         });
     }
 
+    /**
+     * Calculates the average of all values for the given integer property over all Objects matching the query.
+     * <p>
+     * For floating-point properties use {@link #avg()}.
+     *
+     * @return 0 in case no elements matched the query
+     */
+    public long avgLong() {
+        return (Long) query.callInReadTx(new Callable<Long>() {
+            @Override
+            public Long call() {
+                return nativeAvgLong(queryHandle, query.cursorHandle(), propertyId);
+            }
+        });
+    }
+
+    /**
+     * The count of non-null values.
+     * <p>
+     * See also: {@link #distinct()}
+     */
     public long count() {
         return (Long) query.callInReadTx(new Callable<Long>() {
             @Override

tests/objectbox-java-test/src/main/java/io/objectbox/TestEntity.java

@@ -16,8 +16,10 @@
 
 package io.objectbox;
 
+/** In "real" entity would be annotated with @Entity. */
 public class TestEntity {
 
+    /** In "real" entity would be annotated with @Id. */
     private long id;
     private boolean simpleBoolean;
     private byte simpleByte;
@@ -30,6 +32,12 @@ public class TestEntity {
     private String simpleString;
     /** Not-null value. */
     private byte[] simpleByteArray;
+    /** In "real" entity would be annotated with @Unsigned. */
+    private short simpleShortU;
+    /** In "real" entity would be annotated with @Unsigned. */
+    private int simpleIntU;
+    /** In "real" entity would be annotated with @Unsigned. */
+    private long simpleLongU;
 
     transient boolean noArgsConstructorCalled;
 
@@ -41,7 +49,7 @@ public TestEntity(long id) {
         this.id = id;
     }
 
-    public TestEntity(long id, boolean simpleBoolean, byte simpleByte, short simpleShort, int simpleInt, long simpleLong, float simpleFloat, double simpleDouble, String simpleString, byte[] simpleByteArray) {
+    public TestEntity(long id, boolean simpleBoolean, byte simpleByte, short simpleShort, int simpleInt, long simpleLong, float simpleFloat, double simpleDouble, String simpleString, byte[] simpleByteArray, short simpleShortU, int simpleIntU, long simpleLongU) {
         this.id = id;
         this.simpleBoolean = simpleBoolean;
         this.simpleByte = simpleByte;
@@ -52,6 +60,9 @@ public TestEntity(long id, boolean simpleBoolean, byte simpleByte, short simpleS
         this.simpleDouble = simpleDouble;
         this.simpleString = simpleString;
         this.simpleByteArray = simpleByteArray;
+        this.simpleShortU = simpleShortU;
+        this.simpleIntU = simpleIntU;
+        this.simpleLongU = simpleLongU;
     }
 
     public long getId() {
@@ -138,4 +149,30 @@ public void setSimpleByteArray(byte[] simpleByteArray) {
         this.simpleByteArray = simpleByteArray;
     }
 
+    public short getSimpleShortU() {
+        return simpleShortU;
+    }
+
+    public TestEntity setSimpleShortU(short simpleShortU) {
+        this.simpleShortU = simpleShortU;
+        return this;
+    }
+
+    public int getSimpleIntU() {
+        return simpleIntU;
+    }
+
+    public TestEntity setSimpleIntU(int simpleIntU) {
+        this.simpleIntU = simpleIntU;
+        return this;
+    }
+
+    public long getSimpleLongU() {
+        return simpleLongU;
+    }
+
+    public TestEntity setSimpleLongU(long simpleLongU) {
+        this.simpleLongU = simpleLongU;
+        return this;
+    }
 }

tests/objectbox-java-test/src/main/java/io/objectbox/TestEntityCursor.java

@@ -16,14 +16,15 @@
 
 package io.objectbox;
 
-
 import io.objectbox.annotation.apihint.Internal;
 import io.objectbox.internal.CursorFactory;
 
-// THIS CODE IS based on GENERATED code BY ObjectBox
+// NOTE: Copied from a plugin project (& removed some unused Properties).
+// THIS CODE IS GENERATED BY ObjectBox, DO NOT EDIT.
 
 /**
- * Cursor for DB entity "TestEntity".
+ * ObjectBox generated Cursor implementation for "TestEntity".
+ * Note that this is a low-level class: usually you should stick to the Box class.
  */
 public final class TestEntityCursor extends Cursor<TestEntity> {
 
@@ -32,14 +33,15 @@ public final class TestEntityCursor extends Cursor<TestEntity> {
 
     @Internal
     static final class Factory implements CursorFactory<TestEntity> {
-        public Cursor<TestEntity> createCursor(Transaction tx, long cursorHandle, BoxStore boxStoreForEntities) {
+        @Override
+        public Cursor<TestEntity> createCursor(io.objectbox.Transaction tx, long cursorHandle, BoxStore boxStoreForEntities) {
             return new TestEntityCursor(tx, cursorHandle, boxStoreForEntities);
         }
     }
 
     private static final TestEntity_.TestEntityIdGetter ID_GETTER = TestEntity_.__ID_GETTER;
 
-    // Property IDs get verified in Cursor base class
+
     private final static int __ID_simpleBoolean = TestEntity_.simpleBoolean.id;
     private final static int __ID_simpleByte = TestEntity_.simpleByte.id;
     private final static int __ID_simpleShort = TestEntity_.simpleShort.id;
@@ -49,8 +51,11 @@ public Cursor<TestEntity> createCursor(Transaction tx, long cursorHandle, BoxSto
     private final static int __ID_simpleDouble = TestEntity_.simpleDouble.id;
     private final static int __ID_simpleString = TestEntity_.simpleString.id;
     private final static int __ID_simpleByteArray = TestEntity_.simpleByteArray.id;
+    private final static int __ID_simpleShortU = TestEntity_.simpleShortU.id;
+    private final static int __ID_simpleIntU = TestEntity_.simpleIntU.id;
+    private final static int __ID_simpleLongU = TestEntity_.simpleLongU.id;
 
-    public TestEntityCursor(Transaction tx, long cursor, BoxStore boxStore) {
+    public TestEntityCursor(io.objectbox.Transaction tx, long cursor, BoxStore boxStore) {
         super(tx, cursor, TestEntity_.__INSTANCE, boxStore);
     }
 
@@ -66,14 +71,25 @@ public final long getId(TestEntity entity) {
      */
     @Override
     public final long put(TestEntity entity) {
-        long __assignedId = collect313311(cursor, entity.getId(), PUT_FLAG_FIRST | PUT_FLAG_COMPLETE,
-                __ID_simpleString, entity.getSimpleString(), 0, null,
-                0, null, __ID_simpleByteArray, entity.getSimpleByteArray(),
-                0, 0, __ID_simpleLong, entity.getSimpleLong(),
-                INT_NULL_HACK ? 0 : __ID_simpleInt, entity.getSimpleInt(), __ID_simpleShort, entity.getSimpleShort(),
-                __ID_simpleByte, entity.getSimpleByte(), __ID_simpleBoolean, entity.getSimpleBoolean() ? 1 : 0,
+        String simpleString = entity.getSimpleString();
+        int __id8 = simpleString != null ? __ID_simpleString : 0;
+        byte[] simpleByteArray = entity.getSimpleByteArray();
+        int __id9 = simpleByteArray != null ? __ID_simpleByteArray : 0;
+
+        collect313311(cursor, 0, PUT_FLAG_FIRST,
+                __id8, simpleString, 0, null,
+                0, null, __id9, simpleByteArray,
+                __ID_simpleLong, entity.getSimpleLong(), __ID_simpleLongU, entity.getSimpleLongU(),
+                INT_NULL_HACK ? 0 : __ID_simpleInt, entity.getSimpleInt(), __ID_simpleIntU, entity.getSimpleIntU(),
+                __ID_simpleShort, entity.getSimpleShort(), __ID_simpleShortU, entity.getSimpleShortU(),
                 __ID_simpleFloat, entity.getSimpleFloat(), __ID_simpleDouble, entity.getSimpleDouble());
+
+        long __assignedId = collect004000(cursor, entity.getId(), PUT_FLAG_COMPLETE,
+                __ID_simpleByte, entity.getSimpleByte(), __ID_simpleBoolean, entity.getSimpleBoolean() ? 1 : 0,
+                0, 0, 0, 0);
+
         entity.setId(__assignedId);
+
         return __assignedId;
     }