tokyocabinet
Class FDB

java.lang.Object
  extended by tokyocabinet.FDB
All Implemented Interfaces:
DBM

public class FDB
extends java.lang.Object
implements DBM

Fixed-length database is a file containing an array of fixed-length elements and is handled with the fixed-length database API. Before operations to store or retrieve records, it is necessary to open a database file and connect the fixed-length 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 OWRITER
          open mode: open as a writer
 
Constructor Summary
FDB()
          Create a fixed-length 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(int width, long limsiz)
          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 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.
 java.util.List range(byte[] interval, int max)
          Get keys with an interval notation.
 java.util.List range(java.lang.String interval, int max)
          Get keys with an interval notation.
 long rnum()
          Get the number of records.
 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(int width, long limsiz)
          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

OWRITER

public static final int OWRITER
open mode: open as a writer

See Also:
Constant Field Values
Constructor Detail

FDB

public FDB()
Create a fixed-length 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. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "prev", the number less by one than the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified. If it is "next", the number greater by one than the maximum ID number of existing records is specified.
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. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "prev", the number less by one than the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified. If it is "next", the number greater by one than the maximum ID number of existing records is specified.
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. The same as `range(prefix, max)'. It is for compatibility only.

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.
See Also:
range(byte[], int)

fwmkeys

public java.util.List fwmkeys(java.lang.String prefix,
                              int max)
Get forward matching keys. The same as `range(prefix.getBytes(), max)'. It is for compatibility only.

Specified by:
fwmkeys in interface DBM
See Also:
range(String, int)

get

public byte[] get(byte[] key)
Retrieve a record.

Specified by:
get in interface DBM
Parameters:
key - the key. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified.
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 function. It is allowed to update or remove records whose keys are fetched while the iteration. The order of this traversal access method is ascending of the ID number.

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, FDB.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: `FDB.OWRITER' as a writer, `FDB.OREADER' as a reader. If the mode is `FDB.OWRITER', the following may be added by bitwise-or: `FDB.OCREAT', which means it creates a new database if not exist, `FDB.OTRUNC', which means it creates a new database regardless if one exists. Both of `FDB.OREADER' and `FDB.OWRITER' can be added to by bitwise-or: `FDB.ONOLCK', which means it opens the database file without file locking, or `FDB.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)'.

See Also:
optimize(int, long)

optimize

public boolean optimize(int width,
                        long limsiz)
Optimize the database file.

Parameters:
width - the width of the value of each record. If it is not more than 0, the current setting is not changed.
limsiz - the limit size of the database file. If it is not more than 0, the current setting is not changed.
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. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified.
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. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "prev", the number less by one than the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified. If it is "next", the number greater by one than the maximum ID number of existing records is specified.
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. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "prev", the number less by one than the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified. If it is "next", the number greater by one than the maximum ID number of existing records is specified.
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. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "prev", the number less by one than the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified. If it is "next", the number greater by one than the maximum ID number of existing records is specified.
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[])

range

public java.util.List range(byte[] interval,
                            int max)
Get keys with an interval notation.

Parameters:
interval - the interval notation.
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.

range

public java.util.List range(java.lang.String interval,
                            int max)
Get keys with an interval notation. The same as `range(prefix, max)'. However, type of each element is `String'.

See Also:
range(byte[], int)

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.

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(int width,
                    long limsiz)
Set the tuning parameters.

Parameters:
width - the width of the value of each record. If it is not more than 0, the default value is specified. The default value is 255.
limsiz - the limit size of the database file. If it is not more than 0, the default value is specified. The default value is 268435456.
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. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified.
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[])