net.handle.jdb
Class DBHash

java.lang.Object
  extended by net.handle.jdb.DBHash

public class DBHash
extends java.lang.Object

Object used to store key/value pairs in a fast, persistent index. Uses a hashing algorithm (with configurable hash size) to locate records in the file quickly, and a memory cache (also with configurable size) to speed up access to heavily used records. Potential improvement: Currently the memory cache for is rather crude. If the cache gets over the configured size, *all* items are removed. It would probably be better if there were some sort of least-recently used algorithm or something. It may also be good to purge the cache asynchronously.


  BC_REC_START Block Format:
  -----------------------------------------------------
  | Block Code == BC_REC_START (1 byte)               |
  | Key Length (4 bytes)                              |
  | Data Length (4 bytes)                             |
  | Next Record Ptr (8 bytes)                         |
  | [ Cont. Block Ptr (8 bytes)                       |
  |     if ((KeyLen+DataLen) > (BlockSz-HeaderSz)) ]  |
  | Data (BlockSz-HeaderSz bytes)                     |
  | ...                                               |
  -----------------------------------------------------

  BC_REC_CONT Block Format:
  -----------------------------------------------------
  | Block Code == BC_REC_CONT (1 byte)                |
  | Remainder Length (4 bytes)                        |
  | [ Cont. Block Ptr (8 bytes)                       |
  |     if this is not the last continuation block ]  |
  | Data                                              |
  | ...                                               |
  -----------------------------------------------------

  BC_REC_UNUSED Block Format:
  -----------------------------------------------------
  | Block Code == BC_REC_UNUSED (1 byte)              |
  | Anything.  (BlockSz-1 bytes)                      |
  -----------------------------------------------------

 TODO:
  Create pack() method to compress file
 


Field Summary
 boolean DEBUG
           
 long numQueries
           
 long stepCount
           
static java.lang.String V1_FILE_ID
           
 
Constructor Summary
DBHash(java.io.File hashFile, int hashLength, int cacheSize)
          Create/open a hashed index file with a hashtable of hashLength entries and a cache with a maximum of cacheSize records.
DBHash(java.io.File hashFile, int hashLength, int cacheSize, boolean readOnly)
          Create/open a hashed index file with a hashtable of hashLength entries and a cache with a maximum of cacheSize records.
 
Method Summary
 void close()
          Close the random-access file.
 void copyTo(java.io.File newJDBFile)
          Method to backup the DBHash file to given named file.
 void deleteAllRecords()
          Delete every record in the file.
 boolean deleteValue(byte[] key)
          Delete the specified key and it's associated value from the database.
 void dumpDataStructure(java.io.PrintStream out)
          Dump a human-readable display of all of the records in the table and cache.
 void dumpDepthGraph()
          Display a crude text-based graph of the hash distribution.
 void dumpRecords(java.io.PrintStream out)
          Dump all of the records in the table in hexadecimal format with the keys separated from the values by a colon.
 void finalize()
           
 java.util.Enumeration getEnumerator()
          Return an enumeration used to iterate over all of the records in the table.
 byte[] getValue(byte[] key)
          Get the data value associated with the specified key.
static void main(java.lang.String[] argv)
           
 void setValue(byte[] key, byte[] data)
          Set the data value associated with the specified key.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

V1_FILE_ID

public static final java.lang.String V1_FILE_ID
See Also:
Constant Field Values

stepCount

public long stepCount

numQueries

public long numQueries

DEBUG

public boolean DEBUG
Constructor Detail

DBHash

public DBHash(java.io.File hashFile,
              int hashLength,
              int cacheSize)
       throws java.lang.Exception
Create/open a hashed index file with a hashtable of hashLength entries and a cache with a maximum of cacheSize records.

Throws:
java.lang.Exception

DBHash

public DBHash(java.io.File hashFile,
              int hashLength,
              int cacheSize,
              boolean readOnly)
       throws java.lang.Exception
Create/open a hashed index file with a hashtable of hashLength entries and a cache with a maximum of cacheSize records.

Throws:
java.lang.Exception
Method Detail

deleteAllRecords

public void deleteAllRecords()
                      throws java.lang.Exception
Delete every record in the file.

Throws:
java.lang.Exception

close

public void close()
           throws java.lang.Exception
Close the random-access file.

Throws:
java.lang.Exception

finalize

public void finalize()
Overrides:
finalize in class java.lang.Object

getValue

public final byte[] getValue(byte[] key)
                      throws java.lang.Exception
Get the data value associated with the specified key.

Returns:
null if the specified key does not exist.
Throws:
java.lang.Exception

setValue

public final void setValue(byte[] key,
                           byte[] data)
                    throws java.lang.Exception
Set the data value associated with the specified key. If a data value is already associated with this key, it will be replaced. If not, it will be created.

Throws:
java.lang.Exception

deleteValue

public final boolean deleteValue(byte[] key)
                          throws java.lang.Exception
Delete the specified key and it's associated value from the database. Returns true if the key actually existed in the database, otherwise false.

Throws:
java.lang.Exception

dumpDepthGraph

public void dumpDepthGraph()
                    throws java.lang.Exception
Display a crude text-based graph of the hash distribution.

Throws:
java.lang.Exception

dumpRecords

public void dumpRecords(java.io.PrintStream out)
Dump all of the records in the table in hexadecimal format with the keys separated from the values by a colon.


getEnumerator

public java.util.Enumeration getEnumerator()
Return an enumeration used to iterate over all of the records in the table.


dumpDataStructure

public void dumpDataStructure(java.io.PrintStream out)
Dump a human-readable display of all of the records in the table and cache.


copyTo

public void copyTo(java.io.File newJDBFile)
            throws java.lang.Exception
Method to backup the DBHash file to given named file. Outside code MUST make sure that no write operations are performed on the database while this method is executing.

Parameters:
newJDBFile - File to copy this database to
Throws:
java.lang.Exception

main

public static void main(java.lang.String[] argv)
                 throws java.lang.Exception
Throws:
java.lang.Exception