RocksJava Basics

RocksJava is a project to build high performance but easy-to-use Java driver for RocksDB. In this page you will learn the basics of RocksDB Java API.

Getting Started

To build RocksJava, the first thing is to specify the environment variable JAVA_HOME to where you install Java SDK. Once JAVA_HOME is properly set, simply running make rocksdbjava will build the Java bindings for RocksDB:

$ make rocksdbjava

This will generate rocksdbjni.jar and librocksdbjni.so (or librocksdbjni.jnilib in Mac) in java/target directory under the rocksdb's root directory. Specifically, rocksdbjni.jar contains the Java classes that defines the Java API for RocksDB, while librocksdbjni.so includes the C++ rocksdb library and the native implementation of the Java classes defined in rocksdbjni.jar.

To run unit tests:

$ make jtest

To clean:

$ make jclean

Opening a Database

A rocksdb database has a name which corresponds to a file system directory. All of the contents of database are stored in this directory. The following example shows how to open a database, creating it if necessary:

import org.rocksdb.RocksDB;
import org.rocksdb.Options;
...
  // a static method that loads the RocksDB C++ library.
  RocksDB.loadLibrary();
  // the Options class contains a set of configurable DB options
  // that determines the behavior of a database.
  Options options = new Options().setCreateIfMissing(true);
  RocksDB db = null;
  try {
    // a factory method that returns a RocksDB instance
    db = RocksDB.open(options, "path/to/db");
    // do something
  } catch (RocksDBException e) {
    // do some error handling
    ...
  }
...

TIP: You may notice the RocksDBException class above. This exception class extends java.lang.Exception and encapsulates the Status class in the C++ rocksdb, which describes any internal errors of RocksDB.

Closing a Database

When you are done with a database, it is suggested to call RocksDB.close() (or its equivalent method dispose()) and options.dispose() to release their C++ resource manually, although these associated C++ resources will also be released in their finalizer:

  if (db != null) db.close();
  options.dispose();

TIP: When you see a class extends RocksObject, it means any instance of this class has a native handle which stores a C++ pointer pointing to some rocksdb related resource. It is suggested to invoke RocksObject.dispose() manually once all its associated databases have been closed. Note that calling a non-static method of an already-disposed RocksObject instance is an undefined behavior.

Reads and Writes

The database provides put, remove, and get methods to modify/query the database. For example, the following code moves the value stored under key1 to key2.

byte[] key1;
byte[] key2;
// some initialization for key1 and key2
try {
  byte[] value = db.get(key1);
  if (value != null) {  // value == null if key1 does not exist in db.
    db.put(key2, value);
  }
  db.remove(key1);
} catch (RocksDBException e) {
  // error handling
}

TIP: You can also control the put and get behavior using WriteOptions and ReadOptions by calling their polymorphic methods RocksDB.put(WriteOptions opt, byte[] key, byte[] value) and RocksDB.get(ReadOptions opt, byte[] key).

TIP: To avoid creating a byte-array in RocksDB.get(), you can also use its parametric method int RocksDB.get(byte[] key, byte[] value) or int RocksDB.get(ReadOptions opt, byte[] key, byte[] value), where the output value will be filled into the pre-allocated output buffer value, and its int returned value will indicate the actual length of the value associated with the input key. When the returned value is greater than value.length, this indicates the size of the output buffer is insufficient.

Further Documentation

TBD