A better Java wrapper around the Kyoto Cabinet library.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


#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:


  • 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.


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


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.