From b08c39e14f1119ecb462e6264ad0ccf390d1d712 Mon Sep 17 00:00:00 2001
From: fyrz <fyrgoss@gmail.com>
Date: Mon, 27 Oct 2014 23:53:27 +0100
Subject: [PATCH] [RocksJava] RocksIterator: Assert for valid RocksDB instance
 & documentation

---
 java/org/rocksdb/RocksIterator.java | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/java/org/rocksdb/RocksIterator.java b/java/org/rocksdb/RocksIterator.java
index ddaddbf95..98b7f6efb 100644
--- a/java/org/rocksdb/RocksIterator.java
+++ b/java/org/rocksdb/RocksIterator.java
@@ -22,6 +22,11 @@ public class RocksIterator extends RocksObject {
   public RocksIterator(RocksDB rocksDB, long nativeHandle) {
     super();
     nativeHandle_ = nativeHandle;
+    // rocksDB must point to a valid RocksDB instance.
+    assert(rocksDB);
+    // RocksIterator must hold a reference to the related RocksDB instance
+    // to guarantee that while a GC cycle starts RocksDBIterator instances
+    // are freed prior to RocksDB instances.
     rocksDB_ = rocksDB;
   }
 
@@ -126,7 +131,12 @@ public class RocksIterator extends RocksObject {
   }
 
   /**
-   * Deletes underlying C++ iterator pointer.
+   * <p>Deletes underlying C++ iterator pointer.</p>
+   *
+   * <p>Note: the underlying handle can only be safely deleted if the RocksDB
+   * instance related to a certain RocksIterator is still valid and initialized.
+   * Therefore {@code disposeInternal()} checks if the RocksDB is initialized
+   * before freeing the native handle.</p>
    */
   @Override protected void disposeInternal() {
     assert(isInitialized());