net.handle.jdb

Class DBHash

java.lang.Object

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

Fields

Modifier and Type	Field and Description
boolean	DEBUG
long	numQueries
long	stepCount
static java.lang.String	V1_FILE_ID

Constructor Summary

Constructors

Constructor and Description
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

Methods

Modifier and Type	Method and Description
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