renamed to queryAttempts, etc., JavaDocs

Author: greenrobot

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

@@ -138,7 +138,7 @@ static native void nativeRegisterCustomType(long store, int entityId, int proper
     public static native boolean isObjectBrowserAvailable();
 
     public static String getVersion() {
-        return "1.3.2-2017-11-30";
+        return "1.3.3-2017-12-03";
     }
 
     private final File directory;
@@ -169,9 +169,9 @@ public static String getVersion() {
 
     private int objectBrowserPort;
 
-    private final int defaultQueryAttempts;
+    private final int queryAttempts;
 
-    private final TxCallback defaultFailedReadTxAttemptCallback;
+    private final TxCallback failedReadTxAttemptCallback;
 
     BoxStore(BoxStoreBuilder builder) {
         NativeLibraryLoader.ensureLoaded();
@@ -231,8 +231,8 @@ public static String getVersion() {
 
         objectClassPublisher = new ObjectClassPublisher(this);
 
-        defaultFailedReadTxAttemptCallback = builder.defaultFailedReadTxAttemptCallback;
-        defaultQueryAttempts = builder.defaultQueryAttempts < 1 ? 1 : builder.defaultQueryAttempts;
+        failedReadTxAttemptCallback = builder.failedReadTxAttemptCallback;
+        queryAttempts = builder.queryAttempts < 1 ? 1 : builder.queryAttempts;
     }
 
     private static void verifyNotAlreadyOpen(String canonicalPath) {
@@ -635,8 +635,8 @@ public <T> T callInReadTxWithRetry(Callable<T> callable, int attempts, int initi
                     System.runFinalization();
                     cleanStaleReadTransactions();
                 }
-                if (defaultFailedReadTxAttemptCallback != null) {
-                    defaultFailedReadTxAttemptCallback.txFinished(null, new DbException(message + " \n" + diagnose, e));
+                if (failedReadTxAttemptCallback != null) {
+                    failedReadTxAttemptCallback.txFinished(null, new DbException(message + " \n" + diagnose, e));
                 }
                 try {
                     Thread.sleep(backoffInMs);
@@ -875,13 +875,13 @@ public boolean isDebugRelations() {
     }
 
     @Internal
-    public int internalDefaultQueryAttempts() {
-        return defaultQueryAttempts;
+    public int internalQueryAttempts() {
+        return queryAttempts;
     }
 
     @Internal
-    public TxCallback internalDefaultFailedReadTxAttemptCallback() {
-        return defaultFailedReadTxAttemptCallback;
+    public TxCallback internalFailedReadTxAttemptCallback() {
+        return failedReadTxAttemptCallback;
     }
 
     void setDebugFlags(int debugFlags) {

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

@@ -75,9 +75,9 @@ public class BoxStoreBuilder {
 
     int maxReaders;
 
-    int defaultQueryAttempts;
+    int queryAttempts;
 
-    TxCallback defaultFailedReadTxAttemptCallback;
+    TxCallback failedReadTxAttemptCallback;
 
     final List<EntityInfo> entityInfoList = new ArrayList<>();
 
@@ -269,15 +269,31 @@ public BoxStoreBuilder debugRelations() {
         return this;
     }
 
+    /**
+     * For massive concurrent setups (app is using a lot of threads), you can enable automatic retries for queries.
+     * This can resolve situations in which resources are getting sparse (e.g.
+     * {@link io.objectbox.exception.DbMaxReadersExceededException} or other variations of
+     * {@link io.objectbox.exception.DbException} are thrown during query execution).
+     *
+     * @param queryAttempts number of attempts a query find operation will be executed before failing.
+     *                      Recommended values are in the range of 2 to 5, e.g. a value of 3 as a starting point.
+     */
     @Experimental
-    public BoxStoreBuilder defaultQueryAttempts(int defaultQueryAttempts) {
-        this.defaultQueryAttempts = defaultQueryAttempts;
+    public BoxStoreBuilder queryAttempts(int queryAttempts) {
+        if (queryAttempts < 1) {
+            throw new IllegalArgumentException("Query attempts must >= 1");
+        }
+        this.queryAttempts = queryAttempts;
         return this;
     }
 
+    /**
+     * Define a callback for failed read transactions during retires (see also {@link #queryAttempts(int)}).
+     * Useful for e.g. logging.
+     */
     @Experimental
-    public BoxStoreBuilder defaultFailedReadTxAttemptCallback(TxCallback defaultFailedReadTxAttemptCallback) {
-        this.defaultFailedReadTxAttemptCallback = defaultFailedReadTxAttemptCallback;
+    public BoxStoreBuilder failedReadTxAttemptCallback(TxCallback failedReadTxAttemptCallback) {
+        this.failedReadTxAttemptCallback = failedReadTxAttemptCallback;
         return this;
     }
 

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

@@ -1,13 +1,15 @@
 package io.objectbox.exception;
 
 import io.objectbox.BoxStore;
+import io.objectbox.BoxStoreBuilder;
 
 /**
  * Thrown when the maximum of readers (read transactions) was exceeded.
  * Verify that you run a reasonable amount of threads only.
  * <p>
  * If you intend to work with a very high number of threads (>100), consider increasing the number of maximum readers
- * using {@link io.objectbox.BoxStoreBuilder#maxReaders(int)}.
+ * using {@link BoxStoreBuilder#maxReaders(int)} and enabling query retries using
+ * {@link BoxStoreBuilder#queryAttempts(int)}.
  * <p>
  * For debugging issues related to this exception, check {@link BoxStore#diagnose()}.
  */

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

@@ -88,7 +88,7 @@ native void nativeSetParameters(long handle, int propertyId, String parameterAli
           Comparator<T> comparator) {
         this.box = box;
         store = box.getStore();
-        queryAttempts = store.internalDefaultQueryAttempts();
+        queryAttempts = store.internalQueryAttempts();
         handle = queryHandle;
         this.hasOrder = hasOrder;
         publisher = new QueryPublisher<>(this, box);

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

@@ -168,7 +168,7 @@ public void testCallInReadTxWithRetry_callback() {
         final int[] countHolderCallback = {0};
 
         BoxStoreBuilder builder = new BoxStoreBuilder(createTestModel(false)).directory(boxStoreDir)
-                .defaultFailedReadTxAttemptCallback(new TxCallback() {
+                .failedReadTxAttemptCallback(new TxCallback() {
                     @Override
                     public void txFinished(@Nullable Object result, @Nullable Throwable error) {
                         assertNotNull(error);

tests/objectbox-java-test/src/main/java/io/objectbox/query/QueryTest.java

@@ -477,8 +477,8 @@ public int compare(TestEntity o1, TestEntity o2) {
     public void testQueryAttempts() {
         store.close();
         BoxStoreBuilder builder = new BoxStoreBuilder(createTestModel(false)).directory(boxStoreDir)
-                .defaultQueryAttempts(5)
-                .defaultFailedReadTxAttemptCallback(new TxCallback() {
+                .queryAttempts(5)
+                .failedReadTxAttemptCallback(new TxCallback() {
                     @Override
                     public void txFinished(@Nullable Object result, @Nullable Throwable error) {
                         error.printStackTrace();