Java APIs for put, merge and delete in file ingestion

java/rocksjni/sst_file_writerjni.cc

@@ -72,24 +72,6 @@ void Java_org_rocksdb_SstFileWriter_open(JNIEnv *env, jobject jobj,
   }
 }
 
-/*
- * Class:     org_rocksdb_SstFileWriter
- * Method:    add
- * Signature: (JJJ)V
- */
-void Java_org_rocksdb_SstFileWriter_add(JNIEnv *env, jobject jobj,
-                                        jlong jhandle, jlong jkey_handle,
-                                        jlong jvalue_handle) {
-  auto *key_slice = reinterpret_cast<rocksdb::Slice *>(jkey_handle);
-  auto *value_slice = reinterpret_cast<rocksdb::Slice *>(jvalue_handle);
-  rocksdb::Status s =
-      reinterpret_cast<rocksdb::SstFileWriter *>(jhandle)->Put(*key_slice,
-          *value_slice);
-  if (!s.ok()) {
-    rocksdb::RocksDBExceptionJni::ThrowNew(env, s);
-  }
-}
-
 /*
  * Class:     org_rocksdb_SstFileWriter
  * Method:    put

java/src/main/java/org/rocksdb/SstFileWriter.java

@@ -5,47 +5,199 @@
 
 package org.rocksdb;
 
+/**
+ * SstFileWriter is used to create sst files that can be added to the
+ * database later. All keys in files generated by SstFileWriter will have
+ * sequence number = 0.
+ */
 public class SstFileWriter extends RocksObject {
   static {
     RocksDB.loadLibrary();
   }
 
+  /**
+   * SstFileWriter Constructor.
+   *
+   * @param envOptions {@link org.rocksdb.EnvOptions} instance.
+   * @param options {@link org.rocksdb.Options} instance.
+   * @param comparator the comparator to specify the ordering of keys.
+   *
+   * @deprecated Use {@link #SstFileWriter(EnvOptions, Options)}.
+   * Passing an explicit comparator is deprecated in lieu of passing the
+   * comparator as part of options. Use the other constructor instead.
+   */
+  @Deprecated
   public SstFileWriter(final EnvOptions envOptions, final Options options,
       final AbstractComparator<? extends AbstractSlice<?>> comparator) {
     super(newSstFileWriter(
         envOptions.nativeHandle_, options.nativeHandle_, comparator.getNativeHandle()));
   }
 
+  /**
+   * SstFileWriter Constructor.
+   *
+   * @param envOptions {@link org.rocksdb.EnvOptions} instance.
+   * @param options {@link org.rocksdb.Options} instance.
+   */
   public SstFileWriter(final EnvOptions envOptions, final Options options) {
     super(newSstFileWriter(
         envOptions.nativeHandle_, options.nativeHandle_));
   }
 
+  /**
+   * Prepare SstFileWriter to write to a file.
+   *
+   * @param filePath the location of file
+   *
+   * @throws RocksDBException thrown if error happens in underlying
+   *    native library.
+   */
   public void open(final String filePath) throws RocksDBException {
     open(nativeHandle_, filePath);
   }
 
-  public void add(final Slice key, final Slice value) throws RocksDBException {
-    add(nativeHandle_, key.getNativeHandle(), value.getNativeHandle());
+  /**
+   * Add a Put key with value to currently opened file.
+   *
+   * @param key the specified key to be inserted.
+   * @param value the value associated with the specified key.
+   *
+   * @throws RocksDBException thrown if error happens in underlying
+   *    native library.
+   *
+   * @deprecated Use {@link #put(Slice, Slice)}
+   */
+  @Deprecated
+  public void add(final Slice key, final Slice value)
+      throws RocksDBException {
+    put(nativeHandle_, key.getNativeHandle(), value.getNativeHandle());
   }
 
-  public void add(final DirectSlice key, final DirectSlice value) throws RocksDBException {
-    add(nativeHandle_, key.getNativeHandle(), value.getNativeHandle());
+  /**
+   * Add a Put key with value to currently opened file.
+   *
+   * @param key the specified key to be inserted.
+   * @param value the value associated with the specified key.
+   *
+   * @throws RocksDBException thrown if error happens in underlying
+   *    native library.
+   *
+   * @deprecated Use {@link #put(DirectSlice, DirectSlice)}
+   */
+  @Deprecated
+  public void add(final DirectSlice key, final DirectSlice value)
+      throws RocksDBException {
+    put(nativeHandle_, key.getNativeHandle(), value.getNativeHandle());
   }
 
+  /**
+   * Add a Put key with value to currently opened file.
+   *
+   * @param key the specified key to be inserted.
+   * @param value the value associated with the specified key.
+   *
+   * @throws RocksDBException thrown if error happens in underlying
+   *    native library.
+   */
+  public void put(final Slice key, final Slice value) throws RocksDBException {
+    put(nativeHandle_, key.getNativeHandle(), value.getNativeHandle());
+  }
+
+  /**
+   * Add a Put key with value to currently opened file.
+   *
+   * @param key the specified key to be inserted.
+   * @param value the value associated with the specified key.
+   *
+   * @throws RocksDBException thrown if error happens in underlying
+   *    native library.
+   */
+  public void put(final DirectSlice key, final DirectSlice value)
+      throws RocksDBException {
+    put(nativeHandle_, key.getNativeHandle(), value.getNativeHandle());
+  }
+
+  /**
+   * Add a Merge key with value to currently opened file.
+   *
+   * @param key the specified key to be merged.
+   * @param value the value to be merged with the current value for
+   * the specified key.
+   *
+   * @throws RocksDBException thrown if error happens in underlying
+   *    native library.
+   */
+  public void merge(final Slice key, final Slice value)
+      throws RocksDBException {
+    merge(nativeHandle_, key.getNativeHandle(), value.getNativeHandle());
+  }
+
+  /**
+   * Add a Merge key with value to currently opened file.
+   *
+   * @param key the specified key to be merged.
+   * @param value the value to be merged with the current value for
+   * the specified key.
+   *
+   * @throws RocksDBException thrown if error happens in underlying
+   *    native library.
+   */
+  public void merge(final DirectSlice key, final DirectSlice value)
+      throws RocksDBException {
+    merge(nativeHandle_, key.getNativeHandle(), value.getNativeHandle());
+  }
+
+  /**
+   * Add a deletion key to currently opened file.
+   *
+   * @param key the specified key to be deleted.
+   *
+   * @throws RocksDBException thrown if error happens in underlying
+   *    native library.
+   */
+  public void delete(final Slice key) throws RocksDBException {
+    delete(nativeHandle_, key.getNativeHandle());
+  }
+
+  /**
+   * Add a deletion key to currently opened file.
+   *
+   * @param key the specified key to be deleted.
+   *
+   * @throws RocksDBException thrown if error happens in underlying
+   *    native library.
+   */
+  public void delete(final DirectSlice key) throws RocksDBException {
+    delete(nativeHandle_, key.getNativeHandle());
+  }
+
+  /**
+   * Finish the process and close the sst file.
+   *
+   * @throws RocksDBException thrown if error happens in underlying
+   *    native library.
+   */
   public void finish() throws RocksDBException {
     finish(nativeHandle_);
   }
 
   private native static long newSstFileWriter(
-      final long envOptionsHandle, final long optionsHandle, final long userComparatorHandle);
+      final long envOptionsHandle, final long optionsHandle,
+      final long userComparatorHandle);
 
   private native static long newSstFileWriter(final long envOptionsHandle,
       final long optionsHandle);
 
-  private native void open(final long handle, final String filePath) throws RocksDBException;
+  private native void open(final long handle, final String filePath)
+      throws RocksDBException;
+
+  private native void put(final long handle, final long keyHandle,
+      final long valueHandle) throws RocksDBException;
+
+  private native void merge(final long handle, final long keyHandle,
+      final long valueHandle) throws RocksDBException;
 
-  private native void add(final long handle, final long keyHandle, final long valueHandle)
+  private native void delete(final long handle, final long keyHandle)
       throws RocksDBException;
 
   private native void finish(final long handle) throws RocksDBException;