tokyocabinet
Class TDB

java.lang.Object
  extended by tokyocabinet.TDB

public class TDB
extends java.lang.Object

Table database is a file containing records composed of the primary keys and arbitrary columns and is handled with the table database API. Before operations to store or retrieve records, it is necessary to open a database file and connect the table 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 ITDECIMAL
          index type: decimal string
static int ITKEEP
          index type: keep existing index
static int ITLEXICAL
          index type: lexical string
static int ITOPT
          index type: optimize
static int ITQGRAM
          index type: q-gram inverted index
static int ITTOKEN
          index type: token inverted index
static int ITVOID
          index type: void
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
TDB()
          Create a hash database object.
 
Method Summary
 double adddouble(byte[] pkey, double num)
          Add a real number to a record.
 double adddouble(java.lang.String pkey, double num)
          Add a real number to a record.
 int addint(byte[] pkey, int num)
          Add an integer to a record.
 int addint(java.lang.String pkey, 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 primary keys.
 java.util.List fwmkeys(java.lang.String prefix, int max)
          Get forward matching primary keys.
 long genuid()
          Generate a unique ID number.
 java.util.Map get(byte[] pkey)
          Retrieve a record.
 java.util.Map get(java.lang.String pkey)
          Retrieve a record.
 boolean iterinit()
          Initialize the iterator.
 byte[] iternext()
          Get the next primary key of the iterator.
 java.lang.String iternext2()
          Get the next primary 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[] pkey)
          Remove a record.
 boolean out(java.lang.String pkey)
          Remove a record.
 java.lang.String path()
          Get the path of the database file.
 boolean put(byte[] pkey, java.util.Map cols)
          Store a record.
 boolean put(java.lang.String pkey, java.util.Map cols)
          Store a record.
 boolean putcat(byte[] pkey, java.util.Map cols)
          Concatenate columns of the existing record.
 boolean putcat(java.lang.String pkey, java.util.Map cols)
          Concatenate columns of the existing record.
 boolean putkeep(byte[] pkey, java.util.Map cols)
          Store a new record.
 boolean putkeep(java.lang.String pkey, java.util.Map cols)
          Store a new record.
 long rnum()
          Get the number of records.
 boolean setcache(int rcnum, int lcnum, int ncnum)
          Set the caching parameters.
 boolean setdfunit(int dfunit)
          Set the unit step number of auto defragmentation.
 boolean setindex(java.lang.String name, int type)
          Set a column index.
 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[] pkey)
          Get the size of the value of a record.
 int vsiz(java.lang.String pkey)
          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

ITDECIMAL

public static final int ITDECIMAL
index type: decimal string

See Also:
Constant Field Values

ITKEEP

public static final int ITKEEP
index type: keep existing index

See Also:
Constant Field Values

ITLEXICAL

public static final int ITLEXICAL
index type: lexical string

See Also:
Constant Field Values

ITOPT

public static final int ITOPT
index type: optimize

See Also:
Constant Field Values

ITQGRAM

public static final int ITQGRAM
index type: q-gram inverted index

See Also:
Constant Field Values

ITTOKEN

public static final int ITTOKEN
index type: token inverted index

See Also:
Constant Field Values

ITVOID

public static final int ITVOID
index type: void

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

TDB

public TDB()
Create a hash database object.

Method Detail

adddouble

public double adddouble(byte[] pkey,
                        double num)
Add a real number to a record.

Parameters:
pkey - the primary key.
num - the additional value.
Returns:
If successful, it is the summation value, else, it is `Double.NaN'.
Note:
The additional value is stored as a decimal string value of a column whose name is "_num". If no record corresponds, a new record with the additional value is stored.

adddouble

public double adddouble(java.lang.String pkey,
                        double num)
Add a real number to a record. The same as `adddouble(pkey.getBytes(), num)'.

See Also:
adddouble(byte[], double)

addint

public int addint(byte[] pkey,
                  int num)
Add an integer to a record.

Parameters:
pkey - the primary key.
num - the additional value.
Returns:
If successful, it is the summation value, else, it is `Integer.MIN_VALUE'.
Note:
The additional value is stored as a decimal string value of a column whose name is "_num". If no record corresponds, a new record with the additional value is stored.

addint

public int addint(java.lang.String pkey,
                  int num)
Add an integer to a record. The same as `addint(pkey.getBytes(), num)'.

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.

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 primary keys.

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 primary keys. The same as `fwmkeys(prefix.getBytes(), max)'. However, type of each element is `String'.

See Also:
fwmkeys(byte[], int)

genuid

public long genuid()
Generate a unique ID number.

Returns:
the new unique ID number or -1 on failure.

get

public java.util.Map get(byte[] pkey)
Retrieve a record.

Parameters:
pkey - the primary key.
Returns:
If successful, it is a map object of the columns of the corresponding record. `null' is returned if no record corresponds. Type of each key is `String'. Type of each value is `byte[]'.

get

public java.util.Map get(java.lang.String pkey)
Retrieve a record. The same as `get(pkey.getBytes())'. However, type of each key and value is `String'.

See Also:
get(byte[])

iterinit

public boolean iterinit()
Initialize the iterator.

Returns:
If successful, it is true, else, it is false.
Note:
The iterator is used in order to access the primary key of every record stored in a database.

iternext

public byte[] iternext()
Get the next primary key of the iterator.

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 primary key of the iterator. The same as `new String(iternext(), "UTF-8")'.

See Also:
iternext()

open

public boolean open(java.lang.String name)
Open a database file. The same as `open(name, TDB.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: `TDB.OWRITER' as a writer, `TDB.OREADER' as a reader. If the mode is `TDB.OWRITER', the following may be added by bitwise-or: `TDB.OCREAT', which means it creates a new database if not exist, `TDB.OTRUNC', which means it creates a new database regardless if one exists, `TDB.OTSYNC', which means every transaction synchronizes updated contents with the device. Both of `TDB.OREADER' and `TDB.OWRITER' can be added to by bitwise-or: `TDB.ONOLCK', which means it opens the database file without file locking, or `TDB.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: `TDB.TLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `TDB.TDEFLATE' specifies that each record is compressed with Deflate encoding, `TDB.TBZIP' specifies that each record is compressed with BZIP2 encoding, `TDB.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[] pkey)
Remove a record.

Parameters:
pkey - the primary key.
Returns:
If successful, it is true, else, it is false.

out

public boolean out(java.lang.String pkey)
Remove a record. The same as `out(pkey.getBytes())'.

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[] pkey,
                   java.util.Map cols)
Store a record.

Parameters:
pkey - the primary key.
cols - a map object containing columns. Type of each key is `String'. Type of each value is `byte[]'.
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 pkey,
                   java.util.Map cols)
Store a record. The same as `put(pkey.getBytes(), cols)'. However, type of each key and value is `String'.

See Also:
put(byte[], Map)

putcat

public boolean putcat(byte[] pkey,
                      java.util.Map cols)
Concatenate columns of the existing record.

Parameters:
pkey - the primary key.
cols - a map object containing columns. Type of each key is `String'. Type of each value is `byte[]'.
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 pkey,
                      java.util.Map cols)
Concatenate columns of the existing record. The same as `putkeep(pkey.getBytes(), cols)'. However, type of each key and value is `String'.

See Also:
putcat(byte[], Map)

putkeep

public boolean putkeep(byte[] pkey,
                       java.util.Map cols)
Store a new record.

Parameters:
pkey - the primary key.
cols - a map object containing columns. Type of each key is `String'. Type of each value is `byte[]'.
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 pkey,
                       java.util.Map cols)
Store a new record. The same as `putkeep(pkey.getBytes(), cols)'. However, type of each key and value is `String'.

See Also:
putkeep(byte[], Map)

rnum

public long rnum()
Get the number of records.

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

setcache

public boolean setcache(int rcnum,
                        int lcnum,
                        int ncnum)
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.
lcnum - the maximum number of leaf nodes to be cached. If it is not more than 0, the default value is specified. The default value is 1024.
ncnum - the maximum number of non-leaf nodes to be cached. If it is not more than 0, the default value is specified. The default value is 512.
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.

setindex

public boolean setindex(java.lang.String name,
                        int type)
Set a column index.

Parameters:
name - the name of a column. If the name of an existing index is specified, the index is rebuilt. An empty string means the primary key.
type - the index type: `TDB.ITLEXICAL' for lexical string, `TDB.ITDECIMAL' for decimal string, `TDB.ITTOKEN' for token inverted index, `TDB.ITQGRAM' for q-gram inverted index. If it is `TDB.ITOPT', the index is optimized. If it is `TDB.ITVOID', the index is removed. If `TDB.ITKEEP' is added by bitwise-or and the index exists, this method merely returns failure.
Returns:
If successful, it is true, else, it is false.

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: `TDB.TLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `TDB.TDEFLATE' specifies that each record is compressed with Deflate encoding, `TDB.TBZIP' specifies that each record is compressed with BZIP2 encoding, `TDB.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[] pkey)
Get the size of the value of a record.

Parameters:
pkey - the primary 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 pkey)
Get the size of the value of a record. The same as `vsiz(pkey.getBytes())'.

See Also:
vsiz(byte[])