HeliDB programmer's guide

// Create a new SimpleDatabase that uses a HeapBackend.
// The database will store String keys and values.
//  - f is a File where the database data will be stored.

// A LogAdapter that logs to stdout and stderr.
LogAdapterHolder lah = 
  new LogAdapterHolder(
    new StdOutLogAdapter());

Database<String, String> db = 
  new SimpleDatabase<String, String, Long>(
    // Use a HeapBackendBuilder object to build the HeapBackend.
    // Objects in HeliDB with many configurable parameters often have builder 
    // objects to make it easier to construct them.
    new HeapBackendBuilder<String, String>().
      setKeySerializer(StringSerializer.INSTANCE).
      setValueSerializer(StringSerializer.INSTANCE).
      // Adapt the File to a ReadWritableFile.
      create(new ReadWritableFileAdapter(f)),
    lah);

// Insert a couple of values
db.insert("key 1", "value 1");
db.insert("key 2", "value 2");

// Run a read/write transaction over two 
// TransactionalDatabase<String, String>:s, db1 and db2.
boolean successful = false;
Transaction txn = Transaction.startTransaction(false);
try
{
  // db1 automatically joins txn in read/write mode since we're doing an
  // updating operation on it.
  db1.insertOrUpdate("lastUpdate", "" + System.currentTimeMillis());
  
  // We have to manually join db2 in the transaction in read/write mode. 
  // Otherwise the get operation would have joined db2 in read only mode.
  db2.joinTransaction(false);
  
  String s = db2.get("years");
  db2.update("years", s + ", 2008"); 
  
  txn.commit();
  successful = true;
}
finally
{
  if (!successful)
  {
    // The transaction failed somehow. Roll back the changes.
    txn.rollback();
  }
}

// Create a LoggingTransactionalDatabase using a 
// LoggingTransactionalDatabaseBuilder object.
// Keep the database data in the File f and the rollback log in the File lf.
//
// If the rollback log file is not empty, the rollback log there is replayed to
// restore the database contents.
TransactionalDatabase<String, String> db =
  new LoggingTransactionalDatabaseBuilder<String, String>().
    // The logging transactional database needs serializers for writing data to
    // the rollback log.
    setKeySerializer(StringSerializer.INSTANCE).
    setValueSerializer(StringSerializer.INSTANCE).
    create(
      new HeapBackendBuilder<String, String>().
        setKeySerializer(StringSerializer.INSTANCE).
        setValueSerializer(StringSerializer.INSTANCE).
        // Adapt the File database file to a ReadWritableFile.
        create(new ReadWritableFileAdapter(f)),
      // Adapt the File log file to a ReadWritableFile.
      new ReadWritableFileAdapter(lf));

// Create a ShadowCopyTransactionalDatabase on the database EFile f
// and that keeps its shadow copy files in the Directory tmpDir.
//
// f or tmpDir must not be in a locking FileSystem. 
//
// The ShadowCopyTxnDatabaseFileManager is an interface that lets the
// database manipulate the backend's files without knowing exactly how many they
// are or how they are structured.

// A LogAdapter that logs to stdout and stderr.
LogAdapterHolder lah = 
  new LogAdapterHolder(
    new StdOutLogAdapter());

ShadowCopyTxnDatabaseFileManager fm =
  // There is an implementation tailored for the HeapBackend.
  new HeapBackendFileManager(f, tmpDir);

// The shadow copy transactional database uses a backend factory instead of a
// single DatabaseBackend object since it must be able to create new
// backend objects for its shadow copy files.
DatabaseBackendFactory<String, String, Long> dbf=
  new HeapBackendFactory<String, String>(
    // Key and value Serializer:s.
    StringSerializer.INSTANCE,
    StringSerializer.INSTANCE,
    lah);
    
TransactionalDatabase<String, String> db =
  new ShadowCopyTransactionalDatabase<String, String, Long>(fm, dbf, false, lah); 

// Create a SimpleDatabase that uses a ConstantRecordSizeHeapBackend on the
// database File f. The database contains Integer keys and Long values.

// A LogAdapter that logs to stdout and stderr.
LogAdapterHolder lah = 
  new LogAdapterHolder(
    new StdOutLogAdapter());

Database<Integer, Long> db = 
  new SimpleDatabase<Integer, Long, Long>(
    // Use a ConstantRecordSizeHeapBackendBuilder object to build the backend.
    new ConstantRecordSizeHeapBackendBuilder<Integer, Long>().
      setKeySerializer(IntegerSerializer.INSTANCE).
      setValueSerializer(LongSerializer.INSTANCE).
      setLogAdapterHolder(lah).
      // Adapt the File to a ReadWritableFile.
      create(new ReadWritableFileAdapter(f)),
    lah);
  
// Insert a few values
db.insert(1, 1L);
db.insert(2, 1L);
db.insert(3, 2L);
db.insert(4, 3L);
db.insert(5, 5L);
db.insert(6, 8L);
db.insert(7, 13L);

// Create a SimpleDatabase that uses a ConstantRecordSizeBPlusTreeBackend on the
// database File f. The database contains Integer keys and String values. The
// strings may be up to nine characters long. Longer strings are truncated to
// nine characters.

// A LogAdapter that logs to stdout and stderr.
LogAdapterHolder lah = 
  new LogAdapterHolder(
    new StdOutLogAdapter());

// A SimpleDatabase that have Integer keys and String values.
Database<Integer, String> db = 
  new SimpleDatabase<Integer, String, KeyAndValue<Integer, String>>(
    new ConstantRecordSizeBPlusTreeBackend<Integer, String>(
      // The NodeRepository is used by the BPlusTree
      // Use a caching node repository.
      new LruCacheNodeRepository<Integer, String>(
        // Use a FileBackedNodeRepositoryBuilder to build the file-backed
        // node repository.
        // The Integer keys are Comparable, so we don't have to use a Comparator.
        new FileBackedNodeRepositoryBuilder<Integer, String>().
          // Use a node size of 4096 bytes for the B+ Tree. For optimal 
          // performance, this should be the same as the allocation size of the
          // underlying file system.
          setNodeSizeStrategy(new FixedSizeNodeSizeStrategy(4096)).
          // Have to use a null-aware serializer for the B+ Tree keys.
          setKeySerializer(IntegerNullSerializer.INSTANCE).
          // This value serializer will truncate text longer than 9 characters.
          setValueSerializer(
            new ConstantSizeStringSerializer(
              Charset.forName("ISO-8859-1"), 9, true)).
          // This pointer size sets the maximum size of the B+ Tree to
          // 2^(2*8) = 65536 bytes.
          setInternalPointerSize(2).
          setLogAdapterHolder(lah).
          // Adapt the File to a ReadWritableFile.
          create(new ReadWritableFileAdapter(f), false),
        // Set the maximum LRU cache size to 16 nodes.
        16),
      false, lah),
    lah);
  
// Insert a few values
db.insert(1, "apple");
db.insert(2, "banana");
// This value will be truncated to grapefrui when written to disk. As long as 
// its node remains in the LRU cache, it will be grapefruit, though. Be careful.
db.insert(3, "grapefruit");
db.insert(4, "orange");
db.insert(5, "tangerine");
db.insert(6, "pear");

// Create a new SimpleDatabase that uses a HeapBackend
// with a BPlusTreeIndexBackend to speed up searches in the database.
// The database will store String keys and values.
//  - f is a File where the database data will be stored.
//  - indf is a File where the B+ Tree index data will be stored.

// A LogAdapter that logs to stdout and stderr.
LogAdapterHolder lah = 
  new LogAdapterHolder(
    new StdOutLogAdapter());

Database<String, String> db = 
  new SimpleDatabase<String, String, Long>(
    // Use a BPlusTreeIndexBackendBuilder object to build the 
    // BPlusTreeIndexBackend.
    new BPlusTreeIndexBackendBuilder<String, Long>().
      // Hash the keys to a long value (eight bytes).
      // Beware of the birthday paradox! Use sufficiently large hash values.
      setKeyHasher(StringToLongHasher.INSTANCE).
      create(
        // Use a HeapBackendBuilder.
        new HeapBackendBuilder<String, String>().
          setKeySerializer(StringSerializer.INSTANCE).
          setValueSerializer(StringSerializer.INSTANCE).
          // Adapt f to a ReadWritableFile.
          create(new ReadWritableFileAdapter(f)),
        // The BPlusTree is <Long, Long> since it has Long keys (the key
        // hashes) and Long values (the positions in the HeapBackend).
        new BPlusTree<Long,Long>(
          // Use a LRU caching NodeRepository.
          new LruCacheNodeRepository<Long, Long>(
            // Use a FileBackedNodeRepositoryBuilder to build the
            // node repository.
            new FileBackedNodeRepositoryBuilder<Long, Long>().
              // Use a fixed node size of 4096 bytes. This is a common file
              // system allocation size.
              setNodeSizeStrategy(new FixedSizeNodeSizeStrategy(4096)).
              // Have to use a null-aware serializer for the keys.
              // This particular serializer uses Long.MIN_VALUE to represent
              // null, which means that that key value cannot be used at all in
              // the database.
              setKeySerializer(LongNullSerializer.INSTANCE).
              setValueSerializer(LongSerializer.INSTANCE).
              // An internal pointer size of 3 bytes sets the maximum size of
              // the B+ Tree to 2^(3*8) = 16777216 bytes.
              setInternalPointerSize(3).
              setLogAdapterHolder(lah).
              create(new ReadWritableFileAdapter(indf), false),
            // Use a cache size of 16 tree nodes.
            16),
          // We don't have to use a key Comparator (null) since the tree's keys
          // are Comparable themselves (Long:s). 
          null, lah)),
    lah);

// Insert a record.
db.insert("apples", "oranges");

// Create a new SimpleDatabase that uses a HeapBackend
// with a BPlusTreeIndexBackend and a LruCacheBackend
// to speed up searches in the database.
// The database will store String keys and values.
//  - f is a File where the database data will be stored.
//  - indf is a File where the B+ Tree index data will be stored.

// A LogAdapter that logs to stdout and stderr.
LogAdapterHolder lah = 
  new LogAdapterHolder(
    new StdOutLogAdapter());

Database<String, String> db = 
  new SimpleDatabase<String, String, Long>(
    new LruCacheBackend<String, String, Long>(
      // Use a BPlusTreeIndexBackendBuilder object to build the 
      // BPlusTreeIndexBackend.
      new BPlusTreeIndexBackendBuilder<String, BigInteger>().
        // Hash the strings to a twelve-byte value, with the most significant 
        // bit in the most significant byte removed. The most significant bit is
        // used to represent a null value by the FixedSizeBigIntegerNullSerializer
        // used below instead.
        setKeyHasher(new StringToBigIntegerHasher(12, 7)).
        create(
          // Use a HeapBackendBuilder.
          new HeapBackendBuilder<String, String>().
            setKeySerializer(StringSerializer.INSTANCE).
            setValueSerializer(StringSerializer.INSTANCE).
            // Adapt f to a ReadWritableFile.
            create(new ReadWritableFileAdapter(f)),
          // The BPlusTree is <Long, BigInteger> since it has BigInteger keys
          // (the key hashes) and Long values (the records' positions in the
          // HeapBackend).
          new BPlusTree<BigInteger, Long>(
            // Use a LRU caching NodeRepository.
            new LruCacheNodeRepository<BigInteger, Long>(
              // Use a FileBackedNodeRepositoryBuilder to build the
              // node repository.
              new FileBackedNodeRepositoryBuilder<BigInteger, Long>().
                // Use a fixed node size of 4096 bytes.
                setNodeSizeStrategy(new FixedSizeNodeSizeStrategy(4096)).
                // Have to use a null-aware serializer for the keys.
                //
                // This serializer uses a null value that has the most 
                // significant bit in the most significant byte set. We chose to
                // not use that particular bit for our hashes when we created
                // the StringToBigIntegerHasher above. By doing that we
                // have made sure that null won't collide with any real value.
                //
                // Set the total data size of the serializer to 13 bytes. The
                // first byte of the serialized data is the length of the
                // BigInteger data.
                setKeySerializer(new FixedSizeBigIntegerNullSerializer(13)).
                setValueSerializer(LongSerializer.INSTANCE).
                // An internal pointer size of 3 bytes sets the maximum size of
                // the B+ Tree to 2^(3*8) = 16777216 bytes.
                setInternalPointerSize(3).
                setLogAdapterHolder(lah).
                create(new ReadWritableFileAdapter(indf), false),
              // Use a cache size of 16 tree nodes.
              16),
            // We don't have to use a key Comparator (null) since the tree's keys
            // are Comparable themselves (BigInteger:s). 
            null, lah)),
      // The cache size and the negative cache size
      false, 256, 32),
    lah);

// Insert a record.
db.insert("Fiat", "Ritmo");

// db is a Database<Integer, String>
//
// Find the record with the key that has the closest larger value than 40
Cursor<Integer,String> c = db.find(40, SearchMode.CLOSEST_ABOVE);

// Maybe there is no such key in the database
if (c == null)
{
  System.out.println("Nothing found");
  return;
}

while(c.getKey() < 50)
{
  // Print the record
  System.out.println(c.getKey() + ": " + c.getValue());

  // Move to the next record
  c.next();
}