kyotocabinet
Class DB

Object
  extended by DB

public class DB
extends Object

Interface of database abstraction.


Field Summary
static int GEXCEPTIONAL
          generic mode: exceptional mode
static int MADD
          merge mode: keep the existing value
static int MAPPEND
          merge mode: append the new value
static int MREPLACE
          merge mode: modify the existing record only
static int MSET
          merge mode: overwrite the existing value
static int OAUTOSYNC
          open mode: auto synchronization
static int OAUTOTRAN
          open mode: auto transaction
static int OCREATE
          open mode: writer creating
static int ONOLOCK
          open mode: open without locking
static int ONOREPAIR
          open mode: open without auto repair
static int OREADER
          open mode: open as a reader
static int OTRUNCATE
          open mode: writer truncating
static int OTRYLOCK
          open mode: lock without blocking
static int OWRITER
          open mode: open as a writer
 
Constructor Summary
DB()
          Create an instance.
DB(int opts)
          Create an instance with options.
 
Method Summary
 boolean accept_bulk(byte[][] keys, Visitor visitor, boolean writable)
          Accept a visitor to multiple records at once.
 boolean accept(byte[] key, Visitor visitor, boolean writable)
          Accept a visitor to a record.
 boolean add(byte[] key, byte[] value)
          Add a record.
 boolean add(String key, String value)
          Add a record.
 boolean append(byte[] key, byte[] value)
          Append the value of a record.
 boolean append(String key, String value)
          Append the value of a record.
 boolean begin_transaction(boolean hard)
          Begin transaction.
 boolean cas(byte[] key, byte[] oval, byte[] nval)
          Perform compare-and-swap.
 boolean cas(String key, String oval, String nval)
          Perform compare-and-swap.
 boolean clear()
          Remove all records.
 boolean close()
          Close the database file.
 boolean copy(String dest)
          Create a copy of the database file.
 long count()
          Get the number of records.
 Cursor cursor()
          Create a cursor object.
 boolean dump_snapshot(String dest)
          Dump records into a snapshot file.
 boolean end_transaction(boolean commit)
          End transaction.
 Error error()
          Get the last happened error.
protected  void finalize()
          Release resources.
 byte[][] get_bulk(byte[][] keys, boolean atomic)
          Retrieve records at once.
 Map<String,String> get_bulk(List<String> keys, boolean atomic)
          Retrieve records at once.
 byte[] get(byte[] key)
          Retrieve the value of a record.
 String get(String key)
          Retrieve the value of a record.
 double increment_double(byte[] key, double num, double orig)
          Add a number to the numeric double value of a record.
 double increment_double(String key, double num, double orig)
          Add a number to the numeric double value of a record.
 long increment(byte[] key, long num, long orig)
          Add a number to the numeric integer value of a record.
 long increment(String key, long num, long orig)
          Add a number to the numeric integer value of a record.
 boolean iterate(Visitor visitor, boolean writable)
          Iterate to accept a visitor for each record.
 boolean load_snapshot(String src)
          Load records from a snapshot file.
 List<String> match_prefix(String prefix, long max)
          Get keys matching a prefix string.
 List<String> match_regex(String regex, long max)
          Get keys matching a regular expression string.
 List<String> match_similar(String origin, long range, boolean utf, long max)
          Get keys similar to a string in terms of the levenshtein distance.
 boolean merge(DB[] srcary, int mode)
          Merge records from other databases.
 boolean occupy(boolean writable, FileProcessor proc)
          Occupy database by locking and do something meanwhile.
 boolean open(String path, int mode)
          Open a database file.
 String path()
          Get the path of the database file.
 long remove_bulk(byte[][] keys, boolean atomic)
          Remove records at once.
 long remove_bulk(List<String> keys, boolean atomic)
          Remove records at once.
 boolean remove(byte[] key)
          Remove a record.
 boolean remove(String key)
           
 boolean replace(byte[] key, byte[] value)
          Replace the value of a record.
 boolean replace(String key, String value)
          Replace the value of a record.
 byte[] seize(byte[] key)
          Retrieve the value of a record and remove it atomically.
 String seize(String key)
          Retrieve the value of a record and remove it atomically.
 long set_bulk(byte[][] recs, boolean atomic)
          Store records at once.
 long set_bulk(Map<String,String> recs, boolean atomic)
          Store records at once.
 boolean set(byte[] key, byte[] value)
          Set the value of a record.
 boolean set(String key, String value)
          Set the value of a record.
 long size()
          Get the size of the database file.
 Map<String,String> status()
          Get the miscellaneous status information.
 boolean synchronize(boolean hard, FileProcessor proc)
          Synchronize updated contents with the file and the device.
 String toString()
          Get the string expression.
 boolean tune_encoding(String encname)
          Set the encoding of external strings.
 boolean tune_exception_rule(int[] codes)
          Set the rule about throwing exception.
 
Methods inherited from class Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

GEXCEPTIONAL

public static final int GEXCEPTIONAL
generic mode: exceptional mode

See Also:
Constant Field Values

MADD

public static final int MADD
merge mode: keep the existing value

See Also:
Constant Field Values

MAPPEND

public static final int MAPPEND
merge mode: append the new value

See Also:
Constant Field Values

MREPLACE

public static final int MREPLACE
merge mode: modify the existing record only

See Also:
Constant Field Values

MSET

public static final int MSET
merge mode: overwrite the existing value

See Also:
Constant Field Values

OAUTOSYNC

public static final int OAUTOSYNC
open mode: auto synchronization

See Also:
Constant Field Values

OAUTOTRAN

public static final int OAUTOTRAN
open mode: auto transaction

See Also:
Constant Field Values

OCREATE

public static final int OCREATE
open mode: writer creating

See Also:
Constant Field Values

ONOLOCK

public static final int ONOLOCK
open mode: open without locking

See Also:
Constant Field Values

ONOREPAIR

public static final int ONOREPAIR
open mode: open without auto repair

See Also:
Constant Field Values

OREADER

public static final int OREADER
open mode: open as a reader

See Also:
Constant Field Values

OTRUNCATE

public static final int OTRUNCATE
open mode: writer truncating

See Also:
Constant Field Values

OTRYLOCK

public static final int OTRYLOCK
open mode: lock without blocking

See Also:
Constant Field Values

OWRITER

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

See Also:
Constant Field Values
Constructor Detail

DB

public DB()
Create an instance.


DB

public DB(int opts)
Create an instance with options.

Parameters:
opts - the optional features by bitwise-or: DB.GEXCEPTIONAL for the exceptional mode.
Note:
The exceptional mode means that fatal errors caused by methods are reported by exceptions thrown.
Method Detail

accept_bulk

public boolean accept_bulk(byte[][] keys,
                           Visitor visitor,
                           boolean writable)
Accept a visitor to multiple records at once.

Parameters:
keys - specifies an array of the keys.
visitor - a visitor object.
writable - true for writable operation, or false for read-only operation.
Returns:
true on success, or false on failure.
Note:
The operations for specified records are performed atomically and other threads accessing the same records are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

accept

public boolean accept(byte[] key,
                      Visitor visitor,
                      boolean writable)
Accept a visitor to a record.

Parameters:
key - the key.
visitor - a visitor object which implements the Visitor interface.
writable - true for writable operation, or false for read-only operation.
Returns:
true on success, or false on failure.
Note:
The operation for each record is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

add

public boolean add(byte[] key,
                   byte[] value)
Add a record.

Parameters:
key - the key.
value - the value.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, a new record is created. If the corresponding record exists, the record is not modified and false is returned.

add

public boolean add(String key,
                   String value)
Add a record.

See Also:
add(byte[], byte[])
Note:
Equal to the original DB.add method except that the parameters are String.

append

public boolean append(byte[] key,
                      byte[] value)
Append the value of a record.

Parameters:
key - the key.
value - the value.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, a new record is created. If the corresponding record exists, the given value is appended at the end of the existing value.

append

public boolean append(String key,
                      String value)
Append the value of a record.

See Also:
append(byte[], byte[])
Note:
Equal to the original DB.append method except that the parameters are String.

begin_transaction

public boolean begin_transaction(boolean hard)
Begin transaction.

Parameters:
hard - true for physical synchronization with the device, or false for logical synchronization with the file system.
Returns:
true on success, or false on failure.

cas

public boolean cas(byte[] key,
                   byte[] oval,
                   byte[] nval)
Perform compare-and-swap.

Parameters:
key - the key.
oval - the old value. null means that no record corresponds.
nval - the new value. null means that the record is removed.
Returns:
true on success, or false on failure.

cas

public boolean cas(String key,
                   String oval,
                   String nval)
Perform compare-and-swap.

See Also:
cas(byte[], byte[], byte[])
Note:
Equal to the original DB.cas method except that the parameters are String.

clear

public boolean clear()
Remove all records.

Returns:
true on success, or false on failure.

close

public boolean close()
Close the database file.

Returns:
true on success, or false on failure.

copy

public boolean copy(String dest)
Create a copy of the database file.

Parameters:
dest - the path of the destination file.
Returns:
true on success, or false on failure.

count

public long count()
Get the number of records.

Returns:
the number of records, or -1 on failure.

cursor

public Cursor cursor()
Create a cursor object.

Returns:
the return value is the created cursor object. Each cursor should be disabled with the Cursor#disable method when it is no longer in use.

dump_snapshot

public boolean dump_snapshot(String dest)
Dump records into a snapshot file.

Parameters:
dest - the name of the destination file.
Returns:
true on success, or false on failure.

end_transaction

public boolean end_transaction(boolean commit)
End transaction.

Parameters:
commit - true to commit the transaction, or false to abort the transaction.
Returns:
true on success, or false on failure.

error

public Error error()
Get the last happened error.

Returns:
the last happened error.

finalize

protected void finalize()
Release resources.

Overrides:
finalize in class Object

get_bulk

public byte[][] get_bulk(byte[][] keys,
                         boolean atomic)
Retrieve records at once.

Parameters:
keys - the keys of the records to retrieve.
atomic - true to perform all operations atomically, or false for non-atomic operations.
Returns:
an array of retrieved records, or null on failure. Each key and each value is placed alternately.

get_bulk

public Map<String,String> get_bulk(List<String> keys,
                                   boolean atomic)
Retrieve records at once.

See Also:
get_bulk(byte[][], boolean)
Note:
Equal to the original DB.get_bulk method except that the parameter is List and the return value is Map.

get

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

Parameters:
key - the key.
Returns:
the value of the corresponding record, or null on failure.

get

public String get(String key)
Retrieve the value of a record.

See Also:
get(byte[])
Note:
Equal to the original DB.get method except that the parameter and the return value are String.

increment_double

public double increment_double(byte[] key,
                               double num,
                               double orig)
Add a number to the numeric double value of a record.

Parameters:
key - the key.
num - the additional number.
orig - the origin number if no record corresponds to the key. If it is negative infinity and no record corresponds, this method fails. If it is positive infinity, the value is set as the additional number regardless of the current value.
Returns:
the result value, or Not-a-number on failure.

increment_double

public double increment_double(String key,
                               double num,
                               double orig)
Add a number to the numeric double value of a record.

See Also:
increment_double(byte[], double, double)
Note:
Equal to the original DB.increment method except that the parameter is String.

increment

public long increment(byte[] key,
                      long num,
                      long orig)
Add a number to the numeric integer value of a record.

Parameters:
key - the key.
num - the additional number.
orig - the origin number if no record corresponds to the key. If it is Long.MIN_VALUE and no record corresponds, this method fails. If it is Long.MAX_VALUE, the value is set as the additional number regardless of the current value.
Returns:
the result value, or Long.MIN_VALUE on failure.
Note:
The value is serialized as an 8-byte binary integer in big-endian order, not a decimal string. If existing value is not 8-byte, this method fails.

increment

public long increment(String key,
                      long num,
                      long orig)
Add a number to the numeric integer value of a record.

See Also:
increment(byte[], long, long)
Note:
Equal to the original DB.increment method except that the parameter is String.

iterate

public boolean iterate(Visitor visitor,
                       boolean writable)
Iterate to accept a visitor for each record.

Parameters:
visitor - a visitor object which implements the Visitor interface.
writable - true for writable operation, or false for read-only operation.
Returns:
true on success, or false on failure.
Note:
The whole iteration is performed atomically and other threads are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

load_snapshot

public boolean load_snapshot(String src)
Load records from a snapshot file.

Parameters:
src - the name of the source file.
Returns:
true on success, or false on failure.

match_prefix

public List<String> match_prefix(String prefix,
                                 long max)
Get keys matching a prefix string.

Parameters:
prefix - the prefix string.
max - the maximum number to retrieve. If it is negative, no limit is specified.
Returns:
a list object of matching keys, or null on failure.

match_regex

public List<String> match_regex(String regex,
                                long max)
Get keys matching a regular expression string.

Parameters:
regex - the regular expression string.
max - the maximum number to retrieve. If it is negative, no limit is specified.
Returns:
a list object of matching keys, or null on failure.

match_similar

public List<String> match_similar(String origin,
                                  long range,
                                  boolean utf,
                                  long max)
Get keys similar to a string in terms of the levenshtein distance.

Parameters:
origin - the origin string.
range - the maximum distance of keys to adopt.
utf - flag to treat keys as UTF-8 strings.
max - the maximum number to retrieve. If it is negative, no limit is specified.
Returns:
a list object of matching keys, or null on failure.

merge

public boolean merge(DB[] srcary,
                     int mode)
Merge records from other databases.

Parameters:
srcary - an array of the source detabase objects.
mode - the merge mode. DB.MSET to overwrite the existing value, DB.MADD to keep the existing value, DB.MAPPEND to append the new value.
Returns:
true on success, or false on failure.

occupy

public boolean occupy(boolean writable,
                      FileProcessor proc)
Occupy database by locking and do something meanwhile.

Parameters:
writable - true to use writer lock, or false to use reader lock.
proc - a processor object which implements the FileProcessor interface. If it is null, no processing is performed.
Returns:
true on success, or false on failure.
Note:
The operation of the processor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

open

public boolean open(String path,
                    int mode)
Open a database file.

Parameters:
path - the path of a database file. If it is "-", the database will be a prototype hash database. If it is "+", the database will be a prototype tree database. If it is ":", the database will be a stash database. If it is "*", the database will be a cache hash database. If it is "%", the database will be a cache tree database. If its suffix is ".kch", the database will be a file hash database. If its suffix is ".kct", the database will be a file tree database. If its suffix is ".kcd", the database will be a directory hash database. If its suffix is ".kcf", the database will be a directory tree database. If its suffix is ".kcx", the database will be a plain text database. Otherwise, this function fails. Tuning parameters can trail the name, separated by "#". Each parameter is composed of the name and the value, separated by "=". If the "type" parameter is specified, the database type is determined by the value in "-", "+", ":", "*", "%", "kch", "kct", "kcd", kcf", and "kcx". All database types support the logging parameters of "log", "logkinds", and "logpx". The prototype hash database and the prototype tree database do not support any other tuning parameter. The stash database supports "bnum". The cache hash database supports "opts", "bnum", "zcomp", "capcnt", "capsiz", and "zkey". The cache tree database supports all parameters of the cache hash database except for capacity limitation, and supports "psiz", "rcomp", "pccap" in addition. The file hash database supports "apow", "fpow", "opts", "bnum", "msiz", "dfunit", "zcomp", and "zkey". The file tree database supports all parameters of the file hash database and "psiz", "rcomp", "pccap" in addition. The directory hash database supports "opts", "zcomp", and "zkey". The directory tree database supports all parameters of the directory hash database and "psiz", "rcomp", "pccap" in addition. The plain text database does not support any other tuning parameter.
mode - the connection mode. DB.OWRITER as a writer, DB.OREADER as a reader. The following may be added to the writer mode by bitwise-or: DB.OCREATE, which means it creates a new database if the file does not exist, DB.OTRUNCATE, which means it creates a new database regardless if the file exists, DB.OAUTOTRAN, which means each updating operation is performed in implicit transaction, DB.OAUTOSYNC, which means each updating operation is followed by implicit synchronization with the file system. The following may be added to both of the reader mode and the writer mode by bitwise-or: DB.ONOLOCK, which means it opens the database file without file locking, DB.OTRYLOCK, which means locking is performed without blocking, DB.ONOREPAIR, which means the database file is not repaired implicitly even if file destruction is detected.
Returns:
true on success, or false on failure.
Note:
The tuning parameter "log" is for the original "tune_logger" and the value specifies the path of the log file, or "-" for the standard output, or "+" for the standard error. "logkinds" specifies kinds of logged messages and the value can be "debug", "info", "warn", or "error". "logpx" specifies the prefix of each log message. "opts" is for "tune_options" and the value can contain "s" for the small option, "l" for the linear option, and "c" for the compress option. "bnum" corresponds to "tune_bucket". "zcomp" is for "tune_compressor" and the value can be "zlib" for the ZLIB raw compressor, "def" for the ZLIB deflate compressor, "gz" for the ZLIB gzip compressor, "lzo" for the LZO compressor, "lzma" for the LZMA compressor, or "arc" for the Arcfour cipher. "zkey" specifies the cipher key of the compressor. "capcnt" is for "cap_count". "capsiz" is for "cap_size". "psiz" is for "tune_page". "rcomp" is for "tune_comparator" and the value can be "lex" for the lexical comparator, "dec" for the decimal comparator, "lexdesc" for the lexical descending comparator, or "decdesc" for the decimal descending comparator. "pccap" is for "tune_page_cache". "apow" is for "tune_alignment". "fpow" is for "tune_fbp". "msiz" is for "tune_map". "dfunit" is for "tune_defrag". Every opened database must be closed by the DB.close method when it is no longer in use. It is not allowed for two or more database objects in the same process to keep their connections to the same database file at the same time.

path

public String path()
Get the path of the database file.

Returns:
the path of the database file, or null on failure.

remove_bulk

public long remove_bulk(byte[][] keys,
                        boolean atomic)
Remove records at once.

Parameters:
keys - the keys of the records to remove.
atomic - true to perform all operations atomically, or false for non-atomic operations.
Returns:
the number of removed records, or -1 on failure.

remove_bulk

public long remove_bulk(List<String> keys,
                        boolean atomic)
Remove records at once.

See Also:
remove_bulk(byte[][], boolean)
Note:
Equal to the original DB.remove_bulk method except that the parameter is List.

remove

public boolean remove(byte[] key)
Remove a record.

Parameters:
key - the key.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, false is returned.

remove

public boolean remove(String key)
See Also:
remove(byte[])
Note:
Equal to the original DB.remove method except that the parameter is String.

replace

public boolean replace(byte[] key,
                       byte[] value)
Replace the value of a record.

Parameters:
key - the key.
value - the value.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, no new record is created and false is returned. If the corresponding record exists, the value is modified.

replace

public boolean replace(String key,
                       String value)
Replace the value of a record.

See Also:
add(byte[], byte[])
Note:
Equal to the original DB.replace method except that the parameters are String.

seize

public byte[] seize(byte[] key)
Retrieve the value of a record and remove it atomically.

Parameters:
key - the key.
Returns:
the value of the corresponding record, or null on failure.

seize

public String seize(String key)
Retrieve the value of a record and remove it atomically.

See Also:
seize(byte[])
Note:
Equal to the original DB.seize method except that the parameter and the return value are String.

set_bulk

public long set_bulk(byte[][] recs,
                     boolean atomic)
Store records at once.

Parameters:
recs - the records to store. Each key and each value must be placed alternately.
atomic - true to perform all operations atomically, or false for non-atomic operations.
Returns:
the number of stored records, or -1 on failure.

set_bulk

public long set_bulk(Map<String,String> recs,
                     boolean atomic)
Store records at once.

See Also:
set_bulk(byte[][], boolean)
Note:
Equal to the original DB.set_bulk method except that the parameter is Map.

set

public boolean set(byte[] key,
                   byte[] value)
Set the value of a record.

Parameters:
key - the key.
value - the value.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, a new record is created. If the corresponding record exists, the value is overwritten.

set

public boolean set(String key,
                   String value)
Set the value of a record.

See Also:
set(byte[], byte[])
Note:
Equal to the original DB.set method except that the parameters are String.

size

public long size()
Get the size of the database file.

Returns:
the size of the database file in bytes, or -1 on failure.

status

public Map<String,String> status()
Get the miscellaneous status information.

Returns:
a map object of the status information, or null on failure.

synchronize

public boolean synchronize(boolean hard,
                           FileProcessor proc)
Synchronize updated contents with the file and the device.

Parameters:
hard - true for physical synchronization with the device, or false for logical synchronization with the file system.
proc - a postprocessor object which implements the FileProcessor interface. If it is null, no postprocessing is performed.
Returns:
true on success, or false on failure.
Note:
The operation of the postprocessor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

toString

public String toString()
Get the string expression.

Overrides:
toString in class Object
Returns:
the string expression.

tune_encoding

public boolean tune_encoding(String encname)
Set the encoding of external strings.

Parameters:
encname - the name of the encoding.
Returns:
true on success, or false on failure.
Note:
The default encoding of external strings is UTF-8.

tune_exception_rule

public boolean tune_exception_rule(int[] codes)
Set the rule about throwing exception.

Parameters:
codes - an array of error codes. If each method occurs an error corresponding to one of the specified codes, the error is thrown as an exception.
Returns:
true on success, or false on failure.