tokyocabinet
Class HDB

java.lang.Object
  tokyocabinet.HDB

All Implemented Interfaces:

DBM

public class HDB
extends java.lang.Object
implements DBM

Hash database is a file containing a hash table and is handled with the hash database API. Before operations to store or retrieve records, it is necessary to open a database file and connect the hash database object to it. To avoid data missing or corruption, it is important to close every database file when it is no longer in use. It is forbidden for multible database objects in a process to open the same database at the same time.

Field Summary

static int	ECLOSE error code: close error
static int	EINVALID error code: invalid operation
static int	EKEEP error code: existing record
static int	ELOCK error code: lock error
static int	EMETA error code: invalid meta data
static int	EMISC error code: miscellaneous error
static int	EMKDIR error code: mkdir error
static int	EMMAP error code: mmap error
static int	ENOFILE error code: file not found
static int	ENOPERM error code: no permission
static int	ENOREC error code: no record found
static int	EOPEN error code: open error
static int	EREAD error code: read error
static int	ERENAME error code: rename error
static int	ERHEAD error code: invalid record header
static int	ERMDIR error code: rmdir error
static int	ESEEK error code: seek error
static int	ESTAT error code: stat error
static int	ESUCCESS error code: success
static int	ESYNC error code: sync error
static int	ETHREAD error code: threading error
static int	ETRUNC error code: trunc error
static int	EUNLINK error code: unlink error
static int	EWRITE error code: write error
static int	OCREAT open mode: writer creating
static int	OLCKNB open mode: lock without blocking
static int	ONOLCK open mode: open without locking
static int	OREADER open mode: open as a reader
static int	OTRUNC open mode: writer truncating
static int	OTSYNC open mode: synchronize every transaction
static int	OWRITER open mode: open as a writer
static int	TBZIP tuning option: compress each record with BZIP2
static int	TDEFLATE tuning option: compress each record with Deflate
static int	TLARGE tuning option: use 64-bit bucket array
static int	TTCBS tuning option: compress each record with TCBS

Constructor Summary

HDB()
Create a hash database object.

Method Summary

double	adddouble(byte[] key, double num) Add a real number to a record.
double	adddouble(java.lang.String key, double num) Add a real number to a record.
int	addint(byte[] key, int num) Add an integer to a record.
int	addint(java.lang.String key, int num) Add an integer to a record.
boolean	close() Close the database file.
boolean	copy(java.lang.String path) Copy the database file.
int	ecode() Get the last happened error code.
java.lang.String	errmsg() Get the message string corresponding to the last happened error code.
static java.lang.String	errmsg(int ecode) Get the message string corresponding to an error code.
protected void	finalize() Release resources.
long	fsiz() Get the size of the database file.
java.util.List	fwmkeys(byte[] prefix, int max) Get forward matching keys.
java.util.List	fwmkeys(java.lang.String prefix, int max) Get forward matching keys.
byte[]	get(byte[] key) Retrieve a record.
java.lang.String	get(java.lang.String key) Retrieve a record.
boolean	iterinit() Initialize the iterator.
byte[]	iternext() Get the next key of the iterator.
java.lang.String	iternext2() Get the next key of the iterator.
boolean	open(java.lang.String name) Open a database file.
boolean	open(java.lang.String path, int omode) Open a database file.
boolean	optimize() Optimize the database file.
boolean	optimize(long bnum, int apow, int fpow, int opts) Optimize the database file.
boolean	out(byte[] key) Remove a record.
boolean	out(java.lang.String key) Remove a record.
java.lang.String	path() Get the path of the database file.
boolean	put(byte[] key, byte[] value) Store a record.
boolean	put(java.lang.String key, java.lang.String value) Store a record.
boolean	putasync(byte[] key, byte[] value) Store a record in asynchronous fashion.
boolean	putasync(java.lang.String key, java.lang.String value) Store a record in asynchronous fashion.
boolean	putcat(byte[] key, byte[] value) Concatenate a value at the end of the existing record.
boolean	putcat(java.lang.String key, java.lang.String value) Concatenate a value at the end of the existing record.
boolean	putkeep(byte[] key, byte[] value) Store a new record.
boolean	putkeep(java.lang.String key, java.lang.String value) Store a new record.
long	rnum() Get the number of records.
boolean	setcache(int rcnum) Set the caching parameters.
boolean	setdfunit(int dfunit) Set the unit step number of auto defragmentation.
boolean	setxmsiz(long xmsiz) Set the size of the extra mapped memory.
boolean	sync() Synchronize updated contents with the file and the device.
boolean	tranabort() Abort the transaction.
boolean	tranbegin() Begin the transaction.
boolean	trancommit() Commit the transaction.
boolean	tune(long bnum, int apow, int fpow, int opts) Set the tuning parameters.
boolean	vanish() Remove all records.
int	vsiz(byte[] key) Get the size of the value of a record.
int	vsiz(java.lang.String key) Get the size of the value of a record.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ECLOSE

public static final int ECLOSE

error code: close error

See Also:

Constant Field Values

EINVALID

public static final int EINVALID

error code: invalid operation

See Also:

Constant Field Values

EKEEP

public static final int EKEEP

error code: existing record

See Also:

Constant Field Values

ELOCK

public static final int ELOCK

error code: lock error

See Also:

Constant Field Values

EMETA

public static final int EMETA

error code: invalid meta data

See Also:

Constant Field Values

EMISC

public static final int EMISC

error code: miscellaneous error

See Also:

Constant Field Values

EMKDIR

public static final int EMKDIR

error code: mkdir error

See Also:

Constant Field Values

EMMAP

public static final int EMMAP

error code: mmap error

See Also:

Constant Field Values

ENOFILE

public static final int ENOFILE

error code: file not found

See Also:

Constant Field Values

ENOPERM

public static final int ENOPERM

error code: no permission

See Also:

Constant Field Values

ENOREC

public static final int ENOREC

error code: no record found

See Also:

Constant Field Values

EOPEN

public static final int EOPEN

error code: open error

See Also:

Constant Field Values

EREAD

public static final int EREAD

error code: read error

See Also:

Constant Field Values

ERENAME

public static final int ERENAME

error code: rename error

See Also:

Constant Field Values

ERHEAD

public static final int ERHEAD

error code: invalid record header

See Also:

Constant Field Values

ERMDIR

public static final int ERMDIR

error code: rmdir error

See Also:

Constant Field Values

ESEEK

public static final int ESEEK

error code: seek error

See Also:

Constant Field Values

ESTAT

public static final int ESTAT

error code: stat error

See Also:

Constant Field Values

ESUCCESS

public static final int ESUCCESS

error code: success

See Also:

Constant Field Values

ESYNC

public static final int ESYNC

error code: sync error

See Also:

Constant Field Values

ETHREAD

public static final int ETHREAD

error code: threading error

See Also:

Constant Field Values

ETRUNC

public static final int ETRUNC

error code: trunc error

See Also:

Constant Field Values

EUNLINK

public static final int EUNLINK

error code: unlink error

See Also:

Constant Field Values

EWRITE

public static final int EWRITE

error code: write error

See Also:

Constant Field Values

OCREAT

public static final int OCREAT

open mode: writer creating

See Also:

Constant Field Values

OLCKNB

public static final int OLCKNB

open mode: lock without blocking

See Also:

Constant Field Values

ONOLCK

public static final int ONOLCK

open mode: open without locking

See Also:

Constant Field Values

OREADER

public static final int OREADER

open mode: open as a reader

See Also:

Constant Field Values

OTRUNC

public static final int OTRUNC

open mode: writer truncating

See Also:

Constant Field Values

OTSYNC

public static final int OTSYNC

open mode: synchronize every transaction

See Also:

Constant Field Values

OWRITER

public static final int OWRITER

open mode: open as a writer

See Also:

Constant Field Values

TBZIP

public static final int TBZIP

tuning option: compress each record with BZIP2

See Also:

Constant Field Values

TDEFLATE

public static final int TDEFLATE

tuning option: compress each record with Deflate

See Also:

Constant Field Values

TLARGE

public static final int TLARGE

tuning option: use 64-bit bucket array

See Also:

Constant Field Values

TTCBS

public static final int TTCBS

tuning option: compress each record with TCBS

See Also:

Constant Field Values

Constructor Detail

HDB

public HDB()

Create a hash database object.

Method Detail

adddouble

public double adddouble(byte[] key,
                        double num)

Add a real number to a record.

Specified by:

adddouble in interface DBM

Parameters:

key - the key.

num - the additional value.

Returns:

If successful, it is the summation value, else, it is `Double.NaN'.

Note:

If the corresponding record exists, the value is treated as a real number and is added to. If no record corresponds, a new record of the additional value is stored.

adddouble

public double adddouble(java.lang.String key,
                        double num)

Add a real number to a record. The same as `adddouble(key.getBytes(), num)'.

Specified by:

adddouble in interface DBM

See Also:

adddouble(byte[], double)

addint

public int addint(byte[] key,
                  int num)

Add an integer to a record.

Specified by:

addint in interface DBM

Parameters:

key - the key.

num - the additional value.

Returns:

If successful, it is the summation value, else, it is `Integer.MIN_VALUE'.

Note:

If the corresponding record exists, the value is treated as an integer and is added to. If no record corresponds, a new record of the additional value is stored.

addint

public int addint(java.lang.String key,
                  int num)

Add an integer to a record. The same as `addint(key.getBytes(), num)'.

Specified by:

addint in interface DBM

See Also:

addint(byte[], int)

close

public boolean close()

Close the database file.

Returns:

If successful, it is true, else, it is false.

Note:

Update of a database is assured to be written when the database is closed. If a writer opens a database but does not close it appropriately, the database will be broken.

copy

public boolean copy(java.lang.String path)

Copy the database file.

Parameters:

path - the path of the destination file. If it begins with `@', the trailing substring is executed as a command line.

Returns:

If successful, it is true, else, it is false. False is returned if the executed command returns non-zero code.

Note:

The database file is assured to be kept synchronized and not modified while the copying or executing operation is in progress. So, this method is useful to create a backup file of the database file.

ecode

public int ecode()

Get the last happened error code.

Returns:

the last happened error code.

errmsg

public java.lang.String errmsg()

Get the message string corresponding to the last happened error code.

Returns:

the message string of the error code.

errmsg

public static java.lang.String errmsg(int ecode)

Get the message string corresponding to an error code.

Parameters:

ecode - the error code.

Returns:

the message string of the error code.

finalize

protected void finalize()

Release resources.

Overrides:

finalize in class java.lang.Object

fsiz

public long fsiz()

Get the size of the database file.

Specified by:

fsiz in interface DBM

Returns:

the size of the database file or 0 if the object does not connect to any database file.

fwmkeys

public java.util.List fwmkeys(byte[] prefix,
                              int max)

Get forward matching keys.

Specified by:

fwmkeys in interface DBM

Parameters:

prefix - the prefix of the corresponding keys.

max - the maximum number of keys to be fetched. If it is negative, no limit is specified.

Returns:

a list object of the keys of the corresponding records. This method does never fail. It returns an empty list even if no record corresponds.

Note:

This function may be very slow because every key in the database is scanned.

fwmkeys

public java.util.List fwmkeys(java.lang.String prefix,
                              int max)

Get forward matching keys. The same as `fwmkeys(prefix.getBytes(), max)'. However, type of each element is `String'.

Specified by:

fwmkeys in interface DBM

See Also:

fwmkeys(byte[], int)

get

public byte[] get(byte[] key)

Retrieve a record.

Specified by:

get in interface DBM

Parameters:

key - the key.

Returns:

If successful, it is the value of the corresponding record. `null' is returned if no record corresponds.

get

public java.lang.String get(java.lang.String key)

Retrieve a record. The same as `new String(get(key.getBytes()), "UTF-8")'.

Specified by:

get in interface DBM

See Also:

get(byte[])

iterinit

public boolean iterinit()

Initialize the iterator.

Specified by:

iterinit in interface DBM

Returns:

If successful, it is true, else, it is false.

Note:

The iterator is used in order to access the key of every record stored in a database.

iternext

public byte[] iternext()

Get the next key of the iterator.

Specified by:

iternext in interface DBM

Returns:

If successful, it is the next key, else, it is `null'. `null' is returned when no record is to be get out of the iterator.

Note:

It is possible to access every record by iteration of calling this method. It is allowed to update or remove records whose keys are fetched while the iteration. However, it is not assured if updating the database is occurred while the iteration. Besides, the order of this traversal access method is arbitrary, so it is not assured that the order of storing matches the one of the traversal access.

iternext2

public java.lang.String iternext2()

Get the next key of the iterator. The same as `new String(iternext(), "UTF-8")'.

Specified by:

iternext2 in interface DBM

See Also:

iternext()

open

public boolean open(java.lang.String name)

Open a database file. The same as `open(name, HDB.OREADER)'.

See Also:

open(String, int)

open

public boolean open(java.lang.String path,
                    int omode)

Open a database file.

Parameters:

path - the path of the database file.

omode - the connection mode: `HDB.OWRITER' as a writer, `HDB.OREADER' as a reader. If the mode is `HDB.OWRITER', the following may be added by bitwise-or: `HDB.OCREAT', which means it creates a new database if not exist, `HDB.OTRUNC', which means it creates a new database regardless if one exists, `HDB.OTSYNC', which means every transaction synchronizes updated contents with the device. Both of `HDB.OREADER' and `HDB.OWRITER' can be added to by bitwise-or: `HDB.ONOLCK', which means it opens the database file without file locking, or `HDB.OLCKNB', which means locking is performed without blocking.

Returns:

If successful, it is true, else, it is false.

optimize

public boolean optimize()

Optimize the database file. The same as `optimize(-1, -1, -1, 0xff)'.

See Also:

optimize(long, int, int, int)

optimize

public boolean optimize(long bnum,
                        int apow,
                        int fpow,
                        int opts)

Optimize the database file.

Parameters:

bnum - the number of elements of the bucket array. If it is not more than 0, the default value is specified. The default value is two times of the number of records.

apow - the size of record alignment by power of 2. If it is negative, the current setting is not changed.

fpow - the maximum number of elements of the free block pool by power of 2. If it is negative, the current setting is not changed.

opts - options by bitwise-or: `HDB.TLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `HDB.TDEFLATE' specifies that each record is compressed with Deflate encoding, `HDB.TBZIP' specifies that each record is compressed with BZIP2 encoding, `HDB.TTCBS' specifies that each record is compressed with TCBS encoding. If it is 0xff, the current setting is not changed.

Returns:

If successful, it is true, else, it is false.

Note:

This method is useful to reduce the size of the database file with data fragmentation by successive updating.

out

public boolean out(byte[] key)

Remove a record.

Specified by:

out in interface DBM

Parameters:

key - the key.

Returns:

If successful, it is true, else, it is false.

out

public boolean out(java.lang.String key)

Remove a record. The same as `out(key.getBytes())'.

Specified by:

out in interface DBM

See Also:

out(byte[])

path

public java.lang.String path()

Get the path of the database file.

Returns:

the path of the database file or `null' if the object does not connect to any database file.

put

public boolean put(byte[] key,
                   byte[] value)

Store a record.

Specified by:

put in interface DBM

Parameters:

key - the key.

value - the value.

Returns:

If successful, it is true, else, it is false.

Note:

If a record with the same key exists in the database, it is overwritten.

put

public boolean put(java.lang.String key,
                   java.lang.String value)

Store a record. The same as `put(key.getBytes(), value.getBytes())'.

Specified by:

put in interface DBM

See Also:

put(byte[], byte[])

putasync

public boolean putasync(byte[] key,
                        byte[] value)

Store a record in asynchronous fashion.

Parameters:

key - the key.

value - the value.

Returns:

If successful, it is true, else, it is false.

Note:

If a record with the same key exists in the database, it is overwritten. Records passed to this method are accumulated into the inner buffer and wrote into the file at a blast.

putasync

public boolean putasync(java.lang.String key,
                        java.lang.String value)

Store a record in asynchronous fashion. The same as `putasync(key.getBytes(), value.getBytes())'.

See Also:

putasync(byte[], byte[])

putcat

public boolean putcat(byte[] key,
                      byte[] value)

Concatenate a value at the end of the existing record.

Parameters:

key - the key.

value - the value.

Returns:

If successful, it is true, else, it is false.

Note:

If there is no corresponding record, a new record is created.

putcat

public boolean putcat(java.lang.String key,
                      java.lang.String value)

Concatenate a value at the end of the existing record. The same as `putcat(key.getBytes(), value.getBytes())'.

See Also:

putcat(byte[], byte[])

putkeep

public boolean putkeep(byte[] key,
                       byte[] value)

Store a new record.

Specified by:

putkeep in interface DBM

Parameters:

key - the key.

value - the value.

Returns:

If successful, it is true, else, it is false.

Note:

If a record with the same key exists in the database, this method has no effect.

putkeep

public boolean putkeep(java.lang.String key,
                       java.lang.String value)

Store a new record. The same as `putkeep(key.getBytes(), value.getBytes())'.

Specified by:

putkeep in interface DBM

See Also:

putkeep(byte[], byte[])

rnum

public long rnum()

Get the number of records.

Specified by:

rnum in interface DBM

Returns:

the number of records or 0 if the object does not connect to any database file.

setcache

public boolean setcache(int rcnum)

Set the caching parameters.

Parameters:

rcnum - the maximum number of records to be cached. If it is not more than 0, the record cache is disabled. It is disabled by default.

Returns:

If successful, it is true, else, it is false.

Note:

The caching parameters of the database should be set before the database is opened.

setdfunit

public boolean setdfunit(int dfunit)

Set the unit step number of auto defragmentation.

Parameters:

dfunit - the unit step number. If it is not more than 0, the auto defragmentation is disabled. It is disabled by default.

Returns:

If successful, it is true, else, it is false.

Note:

The defragmentation parameters should be set before the database is opened.

setxmsiz

public boolean setxmsiz(long xmsiz)

Set the size of the extra mapped memory.

Parameters:

xmsiz - the size of the extra mapped memory. If it is not more than 0, the extra mapped memory is disabled. The default size is 67108864.

Returns:

If successful, it is true, else, it is false.

Note:

The mapping parameters should be set before the database is opened.

sync

public boolean sync()

Synchronize updated contents with the file and the device.

Returns:

If successful, it is true, else, it is false.

Note:

This method is useful when another process connects the same database file.

tranabort

public boolean tranabort()

Abort the transaction.

Returns:

If successful, it is true, else, it is false.

Note:

Update in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction.

tranbegin

public boolean tranbegin()

Begin the transaction.

Returns:

If successful, it is true, else, it is false.

Note:

The database is locked by the thread while the transaction so that only one transaction can be activated with a database object at the same time. Thus, the serializable isolation level is assumed if every database operation is performed in the transaction. All updated regions are kept track of by write ahead logging while the transaction. If the database is closed during transaction, the transaction is aborted implicitly.

trancommit

public boolean trancommit()

Commit the transaction.

Returns:

If successful, it is true, else, it is false.

Note:

Update in the transaction is fixed when it is committed successfully.

tune

public boolean tune(long bnum,
                    int apow,
                    int fpow,
                    int opts)

Set the tuning parameters.

Parameters:

bnum - the number of elements of the bucket array. If it is not more than 0, the default value is specified. The default value is 131071. Suggested size of the bucket array is about from 0.5 to 4 times of the number of all records to be stored.

apow - the size of record alignment by power of 2. If it is negative, the default value is specified. The default value is 4 standing for 2^4=16.

fpow - the maximum number of elements of the free block pool by power of 2. If it is negative, the default value is specified. The default value is 10 standing for 2^10=1024.

opts - options by bitwise-or: `HDB.TLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `HDB.TDEFLATE' specifies that each record is compressed with Deflate encoding, `HDB.TBZIP' specifies that each record is compressed with BZIP2 encoding, `HDB.TTCBS' specifies that each record is compressed with TCBS encoding.

Returns:

If successful, it is true, else, it is false.

Note:

The tuning parameters of the database should be set before the database is opened.

vanish

public boolean vanish()

Remove all records.

Returns:

If successful, it is true, else, it is false.

vsiz

public int vsiz(byte[] key)

Get the size of the value of a record.

Parameters:

key - the key.

Returns:

If successful, it is the size of the value of the corresponding record, else, it is -1.

vsiz

public int vsiz(java.lang.String key)

Get the size of the value of a record. The same as `vsiz(key.getBytes())'.

See Also:

vsiz(byte[])