crischain / mdbxjni

A Java Native Interface to liblmdbx (https://github.com/leo-yuriev/libmdbx)

MDBX JNI

Description

MDBX JNI gives you a Java interface to the libmdbx library which is a fast key-value storage library written for ReOpenLDAP project that provides an ordered mapping from string keys to string values.

Using Prebuilt Jar

The prebuilt binary jars only work on 64 bit OS X or Linux machines.

License

This project is licensed under the Apache License, Version 2.0 but the binary jar it produces also includes the mdbx library which is licensed under the The OpenLDAP Public License.

Downloading the Jar

Just add the following jar to your java project: mdbxjni-all-99-master-SNAPSHOT.jar

Using as a Maven Dependency

You just need to add the following dependency and repository to your Maven pom.xml.

<dependencies>
  <dependency>
    <groupId>org.fusesource.lmdbjni</groupId>
    <artifactId>mdbxjni-all</artifactId>
    <version>99-master-SNAPSHOT</version>
  </dependency>
</dependencies>
...
<repositories>
    <repository>
      <id>fusesource.nexus.snapshot</id>
      <name>FuseSource Community Snapshot Repository</name>
      <url>http://repo.fusesource.com/nexus/content/groups/public-snapshots</url>
    </repository>
</repositories>

API Usage:

The Javadocs don't have too many details yet. Please send patches to improve them!

Recommended Package imports:

import com.castortech.mdbxjni.*;
import static com.castortech.mdbxjni.Constants.*;

Opening and closing the database.

Env env = new Env();
try {
  env.open("/tmp/mydb");
  Database db = env.openDatabase("foo");
  
  ... // use the db
  db.close();
} finally {
  // Make sure you close the env to avoid resource leaks.
  env.close();
}

Putting, Getting, and Deleting key/values.

db.put(bytes("Tampa"), bytes("rocks"));
String value = string(db.get(bytes("Tampa")));
db.delete(bytes("Tampa"));

Performing Atomic/Transacted Updates:

Transaction tx = env.createTransaction();
boolean ok = false;
try {
  db.delete(tx, bytes("Denver"));
  db.put(tx, bytes("Tampa"), bytes("green"));
  db.put(tx, bytes("London"), bytes("red"));
  ok = true;
} finally {
  // Make sure you either commit or rollback to avoid resource leaks.
  if( ok ) {
    tx.commit();
  } else {
    tx.abort();
  }
}

Working against a Snapshot view of the Database:

// create a read-only transaction...
Transaction tx = env.createTransaction(true);
try {
  
  // All read operations will now use the same 
  // consistent view of the data.
  ... = db.db.openCursor(tx);
  ... = db.get(tx, bytes("Tampa"));

} finally {
  // Make sure you commit the transaction to avoid resource leaks.
  tx.commit();
}

Iterating key/values:

Transaction tx = env.createTransaction(true);
try {
  Cursor cursor = db.openCursor(tx);
  try {
    for( Entry entry = cursor.get(FIRST); entry !=null; entry = cursor.get(NEXT) ) {
        String key = string(entry.getKey());
        String value = string(entry.getValue());
        System.out.println(key+" = "+value);
    }
  } finally {
    // Make sure you close the cursor to avoid leaking resources.
    cursor.close();
  }

} finally {
  // Make sure you commit the transaction to avoid resource leaks.
  tx.commit();
}

Using a memory pool to make native memory allocations more efficient:

Env.pushMemoryPool(1024 * 512);
try {
    // .. work with the DB in here, 
} finally {
    Env.popMemoryPool();
}