Java Binding of Tkrzw

Introduction

DBM (Database Manager) is a concept to store an associative array on a permanent storage. In other words, DBM allows an application program to store key-value pairs in a file and reuse them later. Each of keys and values is a string or a sequence of bytes. A key must be unique within the database and a value is associated to it. You can retrieve a stored record with its key very quickly. Thanks to simple structure of DBM, its performance can be extremely high.

Tkrzw is a library implementing DBM with various algorithms. It features high degrees of performance, concurrency, scalability and durability. The following data structures are provided.

Whereas Tkrzw is C++ library, this package provides its Java interface. All above data structures are available via one adapter class "DBM". Read the homepage for details.

DBM stores key-value pairs of strings. Each string is represented as a byte array in Java. Although you can also use methods with string arguments and return values, their internal representations are byte arrays.

All classes are defined under the package "tkrzw", which can be imported in source files of application programs.

import tkrzw.Status;
import tkrzw.StatusException;
import tkrzw.DBM;
import tkrzw.Iterator;
import tkrzw.Utility;

An instance of the class "DBM" is used in order to handle a database. You can store, delete, and retrieve records with the instance. The result status of each operation is represented by an object of the class "Status". Iterator to access each record is implemented by the class "Iterator".

Installation

Install the latest version of Tkrzw beforehand and get the package of the Python binding of Tkrzw. JDK 9.0 or later is required to use this package.

Enter the directory of the extracted package then perform installation. The environment variable JAVA_HOME must be set properly.

./configure
make
make check
sudo make install

When a series of work finishes, the JAR file "tkrzw.jar" and the shared object files "libjtkrzw.so" and so on are installed under "/usr/local/lib".

Let the class search path include "/usr/local/lib/tkrzw.jar" and let the library search path include "/usr/local/lib".

CLASSPATH="$CLASSPATH:/usr/local/lib/tkrzw.jar"
LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/usr/local/lib"
export CLASSPATH LD_LIBRARY_PATH

The above settings can be specified by options of the runtime command.

java -cp .:tkrzw.jar -Djava.library.path=.:/usr/local/lib FooBarBaz ...

Example

The following code is a simple example to use a database, without checking errors. Many methods accept both byte arrays and strings. If strings are given, they are converted implicitly into byte arrays.

import tkrzw.*;

public class Example1 {
  public static void main(String[] args) {
    // Prepares the database.
    DBM dbm = new DBM();
    dbm.open("casket.tkh", true);
    
    // Sets records.
    // Keys and values are implicitly converted into byte arrays.
    dbm.set("first", "hop");
    dbm.set("second", "step");
    dbm.set("third", "jump");

    // Retrieves record values.
    // If the operation fails, null is returned.
    // If the class of the key is String, the value is converted into String.
    System.out.println(dbm.get("first"));
    System.out.println(dbm.get("second"));
    System.out.println(dbm.get("third"));
    System.out.println(dbm.get("fourth"));

    // Traverses records.
    // After using the iterator, it should be destructed explicitly.
    Iterator iter = dbm.makeIterator();
    iter.first();
    while (true) {
      String[] record = iter.getString();
      if (record == null) {
        break;
      }
      System.out.println(record[0] + ": " + record[1]);
      iter.next();
    }
    iter.destruct();

    // Closes the database.
    // After using the database, it should be destructed explicitly.
    dbm.close();
    dbm.destruct();
  }
}

The following code is a typical example to use a database, checking errors. Usually, objects of DBM and Iterator should be destructed in "finally" blocks to avoid memory leak. Even if the database is not closed, the destructor closes it implicitly. The method "orDie" throws an exception on failure so it is useful for checking errors.

import tkrzw.*;

public class Example2 {
  public static void main(String[] args) {
    DBM dbm = new DBM();
    try {
      // Prepares the database, giving tuning parameters.
      Status status = dbm.open(
          "casket.tkh", true, "truncate=True,num_buckets=100");
      // Checks the status explicitly.
      if (!status.isOK()) {
        throw new StatusException(status);
      }
    
      // Sets records.
      // Throws an exception on failure.
      dbm.set("first", "hop").orDie();
      dbm.set("second", "step").orDie();
      dbm.set("third", "jump").orDie();

      // Retrieves record values.
      String[] keys = {"first", "second", "third", "fourth"};
      for (String key : keys) {
        // Gives a status object to check.
        String value = dbm.get(key, status);
        if (status.isOK()) {
          System.out.println(value);
        } else {
          System.err.println(status);
          if (!status.equals(Status.NOT_FOUND_ERROR)) {
            throw new StatusException(status);
          }
        }
      }

      // Traverses records.
      Iterator iter = dbm.makeIterator();
      try {
        iter.first();
        while (true) {
          String[] record = iter.getString(status);
          if (!status.isOK()) {
            if (!status.equals(Status.NOT_FOUND_ERROR)) {
              throw new StatusException(status);
            }
            break;
          }
          System.out.println(record[0] + ": " + record[1]);
          iter.next();
        }
      } finally {
        // Releases the resources.
        iter.destruct();
      }

      // Closes the database.
      dbm.close().orDie();
    } finally {
      // Releases the resources.
      dbm.destruct();
    }
  }
}