About

A better Java wrapper around the Kyoto Cabinet library. It's great to be able to easily access kyoto-cabinet from Java, however the default Java bindings are missing some features we've come to expect in a modern Java developement environment. lastcommons-kyoto addresses this by wrapping the default bindings in an API that should be more familiar to most Java developers.

Dependencies

This wrapper uses kyotocabinet-java version 1.24 which in turn requires kyotocabinet version 1.2.65 or greater. At this time you may need to build both the native libraries yourself. The kyotocabinet-java JNI bindings are in Maven Central.

Start using

You can download a JAR file or obtain lastcommons-kyoto from Maven Central using the following identifier:

• fm.last.commons:lastcommons-kyoto:1.24.0

Features

• Cleaner, more Java-like API.
• Error conditions represented with exceptions instead of magic return values.
• Implicit file suffix handling for the different Kyoto database types.
• Descriptive builder pattern for creating and validating Kyoto database configurations.

Usage

Note: We have taken the liberty of statically importing some enum constants for readability.

Create a new file hash database:

File dbFile = FILE_HASH.createFile("my-new-db");
KyotoDb db = new KyotoDbBuilder(dbFile)
  .modes(READ_WRITE)
  .buckets(42000)
  .memoryMapSize(2, MEBIBYTES)
  .compressor(LZO)
  .build();
db.open();

Create a new cache tree database:

KyotoDb db = new KyotoDbBuilder(CACHE_TREE).build();

Open an existing file tree database:

KyotoDb db = new KyotoDbBuilder("another-db.kct")
  .modes(READ_ONLY)
  .memoryMapSizeFromFile()
  .build();

Resources implement java.io.Closeable

With Java 7:

try (KyotoCursor cursor = db.cursor()) {
  ...
} catch (IOException e) {
  ...
}

or with Apache Commons IO:

IOUtils.closeQuietly(db); // from Apache Commons IO

Work with exceptions - not error codes

try {
  db.append(key, value); // returns void
} catch (KyotoException e) {
  // You decide what happens next!
}

Return values represent outcomes, not errors

boolean recordAlreadyExists = db.putIfAbsent("myKey", "myValue");
long removed = db.remove(keys, ATOMIC);
long records = db.recordCount() // Never Long.MIN_VALUE, never < 0

Conversion from kyoto's 16 byte decimal representation

db.set("doubleValue", 463.94738d);
db.increment("doubleValue", 0.00123d);
double value = db.getDouble("doubleValue"); // value == 463.94861000000003d

Clearer transaction management

try {
  db.begin(Synchronization.PHYSICAL);
  // Do stuff
  db.commit();
} catch (KyotoException e) {
  db.rollback();
}

Validation of Kyoto database configuration

File dbFile = FILE_HASH.newFile(parent, "an-existing-db");          
KyotoDb db = new KyotoDbBuilder(dbFile)
  .modes(READ_ONLY)
  .pageComparator(LEXICAL)
  .build();

// The call to pageComparator() will fail with an
// IllegalArgumentException as file-hash does not
// support the 'pcom' option.

Hadoop-like MapReduce wrapper

// A classic word count across the values 
new MapReduceJob(new Mapper() {
  public void map(byte[] key, byte[] value, Context context) {
    String[] words = new String(value).split(" ");
    for (String word : words) {
      context.write(word.getBytes(), new byte[] { 1 });
    }
  }
}, new Reducer() {
  public void reduce(byte[] key, Iterable<byte[]> values) {
    int count = 0;
    for (byte[] value : values) {
      count += value[0];
    }
    // output key and count
  }
}).executeWith(db);

Building

This project uses the Maven build system. See notes in the 'Dependencies' section on building the dependencies.

Further work

Implement a Spring PlatformTransactionManager for simple integration with Spring's transaction management framework.

Contributing

All contributions are welcome. Please use the Last.fm codeformatting profile found in the lastfm-oss-config project for formatting your changes.

Legal

Copyright 2012 Last.fm

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.