tokyocabinet
Class ADB

java.lang.Object
  tokyocabinet.ADB

All Implemented Interfaces:

DBM

public class ADB
extends java.lang.Object
implements DBM

Abstract database is a set of interfaces to use on-memory hash database, on-memory tree database, hash database, B+ tree database, fixed-length database, and table database with the same API. Before operations to store or retrieve records, it is necessary to connect the abstract database object to the concrete one. The method `open' is used to open a concrete database and the method `close' is used to close the database. To avoid data missing or corruption, it is important to close every database instance 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.

Constructor Summary

ADB()
Create an abstract 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.
boolean	copy(java.lang.String path) Copy the database file.
protected void	finalize() Release resources.
long	fsiz() Get the size of the database.
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.
java.util.List	misc(java.lang.String name, java.util.List args) Call a versatile function for miscellaneous operations.
boolean	open(java.lang.String name) Open a database.
boolean	optimize() Optimize the storage.
boolean	optimize(java.lang.String params) Optimize the storage.
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	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.
long	size() Get the size of the database.
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	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

Constructor Detail

ADB

public ADB()

Create an abstract 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.

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.

finalize

protected void finalize()

Release resources.

Overrides:

finalize in class java.lang.Object

fsiz

public long fsiz()

Get the size of the database. The same as `size()'.

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.

See Also:

size()

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()

misc

public java.util.List misc(java.lang.String name,
                           java.util.List args)

Call a versatile function for miscellaneous operations.

Parameters:

name - the name of the function.

args - a list object of arguments. If it is `null', no argument is specified.

Returns:

If successful, it is an array of the result. `null' is returned on failure.

open

public boolean open(java.lang.String name)

Open a database.

Parameters:

name - the name of the database. If it is "*", the database will be an on-memory hash database. If it is "+", the database will be an on-memory tree database. If its suffix is ".tch", the database will be a hash database. If its suffix is ".tcb", the database will be a B+ tree database. If its suffix is ".tcf", the database will be a fixed-length database. If its suffix is ".tct", the database will be a table database. Otherwise, this method fails. Tuning parameters can trail the name, separated by "#". Each parameter is composed of the name and the value, separated by "=". On-memory hash database supports "bnum", "capnum", and "capsiz". On-memory tree database supports "capnum" and "capsiz". Hash database supports "mode", "bnum", "apow", "fpow", "opts", "rcnum", and "xmsiz". B+ tree database supports "mode", "lmemb", "nmemb", "bnum", "apow", "fpow", "opts", "lcnum", "ncnum", and "xmsiz". Fixed-length database supports "mode", "width", and "limsiz". Table database supports "mode", "bnum", "apow", "fpow", "opts", "rcnum", "lcnum", "ncnum", "xmsiz", and "idx".

Returns:

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

Note:

The tuning parameter "capnum" specifies the capacity number of records. "capsiz" specifies the capacity size of using memory. Records spilled the capacity are removed by the storing order. "mode" can contain "w" of writer, "r" of reader, "c" of creating, "t" of truncating, "e" of no locking, and "f" of non-blocking lock. The default mode is relevant to "wc". "opts" can contains "l" of large option, "d" of Deflate option, "b" of BZIP2 option, and "t" of TCBS option. "idx" specifies the column name of an index and its type separated by ":". For example, "casket.tch#bnum=1000000#opts=ld" means that the name of the database file is "casket.tch", and the bucket number is 1000000, and the options are large and Deflate.

optimize

public boolean optimize()

Optimize the storage. The same as `optimize(null)'.

See Also:

optimize(String)

optimize

public boolean optimize(java.lang.String params)

Optimize the storage.

Parameters:

params - specifies the string of the tuning parameters, which works as with the tuning of parameters the method `open'. If it is `null', it is not used.

Returns:

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

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. "*" stands for on-memory hash database. "+" stands for on-memory tree database.

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[])

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 instance.

size

public long size()

Get the size of the database.

Returns:

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

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.

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[])