From 06b590dd7c9befb8172144c7fab884c6639deda5 Mon Sep 17 00:00:00 2001
From: Ankit Gupta <aigupta@linkedin.com>
Date: Sat, 19 Apr 2014 13:13:01 -0700
Subject: [PATCH] Add doc

---
 java/RocksDBSample.java        |  2 +-
 java/org/rocksdb/Iterator.java | 65 ++++++++++++++++++++++++++++++++--
 java/org/rocksdb/RocksDB.java  | 10 +++++-
 3 files changed, 73 insertions(+), 4 deletions(-)

diff --git a/java/RocksDBSample.java b/java/RocksDBSample.java
index aa05b7887..d33428a50 100644
--- a/java/RocksDBSample.java
+++ b/java/RocksDBSample.java
@@ -142,7 +142,7 @@ public class RocksDBSample {
         assert(false); //Should never reach here.
       }
 
-      Iterator iterator = db.iterator();
+      Iterator iterator = db.newIterator();
 
       boolean seekToFirstPassed = false;
       for (iterator.seekToFirst(); iterator.isValid(); iterator.next()) {
diff --git a/java/org/rocksdb/Iterator.java b/java/org/rocksdb/Iterator.java
index 6069f27b0..eddf8cc49 100644
--- a/java/org/rocksdb/Iterator.java
+++ b/java/org/rocksdb/Iterator.java
@@ -5,6 +5,17 @@
 
 package org.rocksdb;
 
+/**
+ * An iterator yields a sequence of key/value pairs from a source.
+ * The following class defines the interface.  Multiple implementations
+ * are provided by this library.  In particular, iterators are provided 
+ * to access the contents of a Table or a DB.
+ * 
+ * Multiple threads can invoke const methods on an Iterator without 
+ * external synchronization, but if any of the threads may call a
+ * non-const method, all threads accessing the same Iterator must use 
+ * external synchronization.
+ */
 public class Iterator {
   private long nativeHandle_;
 
@@ -12,51 +23,101 @@ public class Iterator {
     nativeHandle_ = nativeHandle;
   }
 
+  /**
+   * An iterator is either positioned at a key/value pair, or
+   * not valid.  This method returns true iff the iterator is valid.
+   * @return true if iterator is valid.
+   */
   public boolean isValid() {
     assert(isInitialized());
     return isValid0(nativeHandle_);
   }
 
+  /**
+   * Position at the first key in the source.  The iterator is Valid()
+   * after this call iff the source is not empty.
+   */
   public void seekToFirst() {
     assert(isInitialized());
     seekToFirst0(nativeHandle_);
   }
 
+  /**
+   * Position at the last key in the source.  The iterator is
+   * Valid() after this call iff the source is not empty.
+   */
   public void seekToLast() {
     assert(isInitialized());
     seekToLast0(nativeHandle_);
   }
-
+  
+  /**
+   * Moves to the next entry in the source.  After this call, Valid() is
+   * true iff the iterator was not positioned at the last entry in the source.
+   * REQUIRES: Valid()
+   */
   public void next() {
     assert(isInitialized());
     next0(nativeHandle_);
   }
-
+  
+  /**
+   * Moves to the previous entry in the source.  After this call, Valid() is
+   * true iff the iterator was not positioned at the first entry in source.
+   * REQUIRES: Valid()
+   */
   public void prev() {
     assert(isInitialized());
     prev0(nativeHandle_);
   }
 
+  /**
+   * Return the key for the current entry.  The underlying storage for
+   * the returned slice is valid only until the next modification of 
+   * the iterator.
+   * REQUIRES: Valid()
+   * @return key for the current entry.
+   */
   public byte[] key() {
     assert(isInitialized());
     return key0(nativeHandle_);
   }
 
+  /**
+   * Return the value for the current entry.  The underlying storage for 
+   * the returned slice is valid only until the next modification of 
+   * the iterator. 
+   * REQUIRES: !AtEnd() && !AtStart()
+   * @return value for the current entry.
+   */
   public byte[] value() {
     assert(isInitialized());
     return value0(nativeHandle_);
   }
 
+  /**
+   * Position at the first key in the source that at or past target
+   * The iterator is Valid() after this call iff the source contains
+   * an entry that comes at or past target.
+   */
   public void seek(byte[] target) {
     assert(isInitialized());
     seek0(nativeHandle_, target, target.length);
   }
 
+  /**
+   * If an error has occurred, return it.  Else return an ok status. 
+   * If non-blocking IO is requested and this operation cannot be 
+   * satisfied without doing some IO, then this returns Status::Incomplete().
+   */
   public void status(){
     assert(isInitialized());
     status0(nativeHandle_);
   }
 
+  /**
+   * Deletes underlying C++ iterator pointer.
+   */
   public synchronized void close() {
     if(nativeHandle_ != 0) {
       close0(nativeHandle_);
diff --git a/java/org/rocksdb/RocksDB.java b/java/org/rocksdb/RocksDB.java
index bbfc18f4c..b43764f8f 100644
--- a/java/org/rocksdb/RocksDB.java
+++ b/java/org/rocksdb/RocksDB.java
@@ -136,7 +136,15 @@ public class RocksDB {
     remove(nativeHandle_, writeOpt.nativeHandle_, key, key.length);
   }
 
-  public Iterator iterator() {
+  /**
+   * Return a heap-allocated iterator over the contents of the database.
+   * The result of newIterator() is initially invalid (caller must
+   * call one of the Seek methods on the iterator before using it).
+   * 
+   * Caller should close the iterator when it is no longer needed.
+   * The returned iterator should be closed before this db is closed.
+   */
+  public Iterator newIterator() {
     return new Iterator(iterator0(nativeHandle_));
   }