[Java] Add Java binding and Java test for ReadOptions.

Summary: Add Java binding and test for rocksdb::ReadOptions.

Test Plan:
make rocksdbjava
make jtest

Reviewers: haobo, dhruba, sdong, ankgup87, rsumbaly, swapnilghike, zzbennett

Reviewed By: haobo

CC: leveldb

Differential Revision: https://reviews.facebook.net/D18129

java/org/rocksdb/ReadOptions.java

@@ -0,0 +1,165 @@
+// Copyright (c) 2014, Facebook, Inc.  All rights reserved.
+// This source code is licensed under the BSD-style license found in the
+// LICENSE file in the root directory of this source tree. An additional grant
+// of patent rights can be found in the PATENTS file in the same directory.
+
+package org.rocksdb;
+
+/**
+ * The class that controls the get behavior.
+ *
+ * Note that dispose() must be called before an Options instance
+ * become out-of-scope to release the allocated memory in c++.
+ */
+public class ReadOptions {
+  public ReadOptions() {
+    nativeHandle_ = 0;
+    newReadOptions();
+  }
+  private native void newReadOptions();
+
+  /**
+   * Release the memory allocated for the current instance
+   * in the c++ side.
+   *
+   * Calling other methods after dispose() leads to undefined behavior.
+   */
+  public synchronized void dispose() {
+    if (isInitialized()) {
+      dispose(nativeHandle_);
+    }
+  }
+  private native void dispose(long handle);
+
+  /**
+   * If true, all data read from underlying storage will be
+   * verified against corresponding checksums.
+   * Default: true
+   *
+   * @return true if checksum verification is on.
+   */
+  public boolean verifyChecksums() {
+    assert(isInitialized());
+    return verifyChecksums(nativeHandle_);
+  }
+  private native boolean verifyChecksums(long handle);
+
+  /**
+   * If true, all data read from underlying storage will be
+   * verified against corresponding checksums.
+   * Default: true
+   *
+   * @param verifyChecksums if true, then checksum verification
+   *     will be performed on every read.
+   * @return the reference to the current ReadOptions.
+   */
+  public ReadOptions setVerifyChecksums(boolean verifyChecksums) {
+    assert(isInitialized());
+    setVerifyChecksums(nativeHandle_, verifyChecksums);
+    return this;
+  }
+  private native void setVerifyChecksums(
+      long handle, boolean verifyChecksums);
+
+  // TODO(yhchiang): this option seems to be block-based table only.
+  //                 move this to a better place?
+  /**
+   * Fill the cache when loading the block-based sst formated db.
+   * Callers may wish to set this field to false for bulk scans.
+   * Default: true
+   *
+   * @return true if the fill-cache behavior is on.
+   */
+  public boolean fillCache() {
+    assert(isInitialized());
+    return fillCache(nativeHandle_);
+  }
+  private native boolean fillCache(long handle);
+
+  /**
+   * Fill the cache when loading the block-based sst formated db.
+   * Callers may wish to set this field to false for bulk scans.
+   * Default: true
+   *
+   * @param fillCache if true, then fill-cache behavior will be
+   *     performed.
+   * @return the reference to the current ReadOptions.
+   */
+  public ReadOptions setFillCache(boolean fillCache) {
+    assert(isInitialized());
+    setFillCache(nativeHandle_, fillCache);
+    return this;
+  }
+  private native void setFillCache(
+      long handle, boolean fillCache);
+
+  /**
+   * If this option is set and memtable implementation allows, Seek
+   * might only return keys with the same prefix as the seek-key
+   * Default: false
+   *
+   * @return true if prefix-seek is enabled.
+   */
+  public boolean prefixSeek() {
+    assert(isInitialized());
+    return prefixSeek(nativeHandle_);
+  }
+  private native boolean prefixSeek(long handle);
+
+  /**
+   * If this option is set and memtable implementation allows, Seek
+   * might only return keys with the same prefix as the seek-key
+   *
+   * @param prefixSeek if true, then prefix-seek will be enabled.
+   * @return the reference to the current ReadOptions.
+   */
+  public ReadOptions setPrefixSeek(boolean prefixSeek) {
+    assert(isInitialized());
+    setPrefixSeek(nativeHandle_, prefixSeek);
+    return this;
+  }
+  private native void setPrefixSeek(
+      long handle, boolean prefixSeek);
+
+  /**
+   * Specify to create a tailing iterator -- a special iterator that has a
+   * view of the complete database (i.e. it can also be used to read newly
+   * added data) and is optimized for sequential reads. It will return records
+   * that were inserted into the database after the creation of the iterator.
+   * Default: false
+   * Not supported in ROCKSDB_LITE mode!
+   *
+   * @return true if tailing iterator is enabled.
+   */
+  public boolean tailing() {
+    assert(isInitialized());
+    return tailing(nativeHandle_);
+  }
+  private native boolean tailing(long handle);
+
+  /**
+   * Specify to create a tailing iterator -- a special iterator that has a
+   * view of the complete database (i.e. it can also be used to read newly
+   * added data) and is optimized for sequential reads. It will return records
+   * that were inserted into the database after the creation of the iterator.
+   * Default: false
+   * Not supported in ROCKSDB_LITE mode!
+   *
+   * @param tailing if true, then tailing iterator will be enabled.
+   * @return the reference to the current ReadOptions.
+   */
+  public ReadOptions setTailing(boolean tailing) {
+    assert(isInitialized());
+    setTailing(nativeHandle_, tailing);
+    return this;
+  }
+  private native void setTailing(
+      long handle, boolean tailing);
+
+  protected long nativeHandle_;
+
+  private boolean isInitialized() {
+    return nativeHandle_ != 0;
+  }
+}
+

java/org/rocksdb/RocksDB.java

@@ -75,7 +75,8 @@ public class RocksDB {
    */
   public void put(WriteOptions writeOpts, byte[] key, byte[] value)
       throws RocksDBException {
-    put(nativeHandle_, writeOpts.nativeHandle_, key, key.length, value, value.length);
+    put(nativeHandle_, writeOpts.nativeHandle_,
+        key, key.length, value, value.length);
   }
 
   /**
@@ -102,6 +103,24 @@ public class RocksDB {
     return get(nativeHandle_, key, key.length, value, value.length);
   }
 
+  /**
+   * Get the value associated with the specified key.
+   *
+   * @param key the key to retrieve the value.
+   * @param value the out-value to receive the retrieved value.
+   * @return The size of the actual value that matches the specified
+   *     {@code key} in byte.  If the return value is greater than the
+   *     length of {@code value}, then it indicates that the size of the
+   *     input buffer {@code value} is insufficient and partial result will
+   *     be returned.  RocksDB.NOT_FOUND will be returned if the value not
+   *     found.
+   */
+  public int get(ReadOptions opt, byte[] key, byte[] value)
+      throws RocksDBException {
+    return get(nativeHandle_, opt.nativeHandle_,
+               key, key.length, value, value.length);
+  }
+
   /**
    * The simplified version of get which returns a new byte array storing
    * the value associated with the specified input key if any.  null will be
@@ -117,6 +136,21 @@ public class RocksDB {
     return get(nativeHandle_, key, key.length);
   }
 
+  /**
+   * The simplified version of get which returns a new byte array storing
+   * the value associated with the specified input key if any.  null will be
+   * returned if the specified key is not found.
+   *
+   * @param key the key retrieve the value.
+   * @return a byte array storing the value associated with the input key if
+   *     any.  null if it does not find the specified key.
+   *
+   * @see RocksDBException
+   */
+  public byte[] get(ReadOptions opt, byte[] key) throws RocksDBException {
+    return get(nativeHandle_, opt.nativeHandle_, key, key.length);
+  }
+
   /**
    * Remove the database entry (if any) for "key".  Returns OK on
    * success, and a non-OK status on error.  It is not an error if "key"
@@ -176,8 +210,14 @@ public class RocksDB {
   protected native int get(
       long handle, byte[] key, int keyLen,
       byte[] value, int valueLen) throws RocksDBException;
+  protected native int get(
+      long handle, long readOptHandle, byte[] key, int keyLen,
+      byte[] value, int valueLen) throws RocksDBException;
   protected native byte[] get(
       long handle, byte[] key, int keyLen) throws RocksDBException;
+  protected native byte[] get(
+      long handle, long readOptHandle,
+      byte[] key, int keyLen) throws RocksDBException;
   protected native void remove(
       long handle, byte[] key, int keyLen) throws RocksDBException;
   protected native void remove(

java/org/rocksdb/test/ReadOptionsTest.java

@@ -0,0 +1,45 @@
+// Copyright (c) 2014, Facebook, Inc.  All rights reserved.
+// This source code is licensed under the BSD-style license found in the
+// LICENSE file in the root directory of this source tree. An additional grant
+// of patent rights can be found in the PATENTS file in the same directory.
+
+package org.rocksdb.test;
+
+import java.util.Random;
+import org.rocksdb.*;
+
+public class ReadOptionsTest {
+  static {
+    System.loadLibrary("rocksdbjni");
+  }
+  public static void main(String[] args) {
+    ReadOptions opt = new ReadOptions();
+    Random rand = new Random();
+    { // VerifyChecksums test
+      boolean boolValue = rand.nextBoolean();
+      opt.setVerifyChecksums(boolValue);
+      assert(opt.verifyChecksums() == boolValue);
+    }
+
+    { // FillCache test
+      boolean boolValue = rand.nextBoolean();
+      opt.setFillCache(boolValue);
+      assert(opt.fillCache() == boolValue);
+    }
+
+    { // PrefixSeek test
+      boolean boolValue = rand.nextBoolean();
+      opt.setPrefixSeek(boolValue);
+      assert(opt.prefixSeek() == boolValue);
+    }
+
+    { // Tailing test
+      boolean boolValue = rand.nextBoolean();
+      opt.setTailing(boolValue);
+      assert(opt.tailing() == boolValue);
+    }
+
+    opt.dispose();
+    System.out.println("Passed ReadOptionsTest");
+  }
+}