Transaction: document some important state methods #282

Author: greenrobot-team

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

@@ -1409,9 +1409,11 @@ public long getNativeStore() {
     /**
      * For internal use only. This API might change or be removed with a future release.
      * <p>
-     * Returns if the native Store was closed.
+     * Returns {@code true} once the native Store is about to be destroyed.
      * <p>
      * This is {@code true} shortly after {@link #close()} was called and {@link #isClosed()} returns {@code true}.
+     *
+     * @see #isNativeStoreDestroyed()
      */
     @Internal
     public boolean isNativeStoreClosed() {
@@ -1421,9 +1423,11 @@ public boolean isNativeStoreClosed() {
     /**
      * For internal use only. This API might change or be removed with a future release.
      * <p>
-     * Returns if the native Store was completely destroyed.
+     * Returns {@code true} once the native Store was destroyed.
      * <p>
-     * This is {@code true} shortly after {@link #close()} was called and {@link #isClosed()} returns {@code true}.
+     * This is {@code true} shortly after {@link #isNativeStoreClosed()} returns {@code true}.
+     *
+     * @see #isNativeStoreClosed()
      */
     @Internal
     public boolean isNativeStoreDestroyed() {

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

@@ -131,7 +131,8 @@ public synchronized void close() {
                 String threadType = isOwnerThread ? "owner thread" : "non-owner thread";
                 if (readOnly) {
                     // Minor leak, but still print it so we can check logs: it should only happen occasionally.
-                    // We cannot rely on the store waiting for read transactions; it only waits for a limited time.
+                    // Note that BoxStore.close() won't (briefly) wait on this transaction as isActive() already returns
+                    // false (and unregisterTransaction(this) was called) at this point.
                     System.out.println("Info: closing read transaction after store was closed (should be avoided) in " +
                             threadType);
                     System.out.flush();
@@ -143,15 +144,19 @@ public synchronized void close() {
                         // This is an internal validation: if this is a write-TX,
                         // the (native) store will always wait for it, so it must not be destroyed yet.
                         // If this ever happens, the above assumption is wrong, and it probably prevents a SIGSEGV.
-                        throw new IllegalStateException(
-                                "Cannot destroy write transaction for an already destroyed store");
+                        // Note that BoxStore.close() won't (briefly) wait on this transaction as isActive() already
+                        // returns false (and unregisterTransaction(this) was called).
+                        throw new IllegalStateException("Cannot close write transaction for an already closed store");
                     }
                     nativeDestroy(transaction);
                 }
             }
         }
     }
 
+    /**
+     * For a write transaction commits the changes. For a read transaction throws.
+     */
     public void commit() {
         checkOpen();
         int[] entityTypeIdsAffected = nativeCommit(transaction);
@@ -163,6 +168,9 @@ public void commitAndClose() {
         close();
     }
 
+    /**
+     * For a read or write transaction, aborts it.
+     */
     public void abort() {
         checkOpen();
         nativeAbort(transaction);
@@ -214,6 +222,12 @@ public BoxStore getStore() {
         return store;
     }
 
+    /**
+     * A transaction is active after it was created until {@link #close()} or {@link #abort()} or for a write
+     * transaction also until {@link #commit()} is called.
+     *
+     * @return If this transaction is active.
+     */
     public boolean isActive() {
         return !closed && nativeIsActive(transaction);
     }