qdbm
Class Villa

java.lang.Object
  |
  +--qdbm.Villa
All Implemented Interfaces:
ADBM

public class Villa
extends java.lang.Object
implements ADBM

The Java API of Villa, the advanced API of QDBM. This class depends on the native library `jqdbm'.


Field Summary
static int CMPDEC
          comparing mode: compare as decimal strings
static int CMPLEX
          comparing mode: compare by lexical order
static int CMPNUM
          comparing mode: compare as long integers
static int CMPOBJ
          comparing mode: compare as comparable objects
static int DDUP
          write mode: concatenate values
static int DKEEP
          write mode: keep the existing value
static int DOVER
          write mode: overwrite the existing value
static int EALLOC
          error code: memory allocation error
static int EBROKEN
          error code: broken database file
static int ECLOSE
          error code: close error
static int EFATAL
          error code: with fatal error
static int EKEEP
          error code: existing record
static int ELOCK
          error code: lock error
static int EMAP
          error code: memory mapping error
static int EMISC
          error code: miscellaneous error
static int EMKDIR
          error code: mkdir error
static int EMODE
          error code: invalid mode
static int ENOERR
          error code: no error
static int ENOITEM
          error code: no item found
static int EOPEN
          error code: open error
static int EREAD
          error code: read error
static int ERMDIR
          error code: rmdir error
static int ESEEK
          error code: seek error
static int ESTAT
          error code: stat error
static int ESYNC
          error code: sync error
static int ETRUNC
          error code: trunc error
static int EUNLINK
          error code: unlink error
static int EWRITE
          error code: write error
static int JBACKWARD
          jump mode: jump mode: step backward
static int JFORWARD
          jump mode: jump mode: step forward
static int OCREAT
          open mode: writer creating
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
Villa(java.lang.String name)
          Get the database handle as a reader.
Villa(java.lang.String name, int omode, int cmode)
          Get the database handle.
 
Method Summary
 void close()
          Close the database handle.
 void curfirst()
          Move the cursor to the first record.
 void curjump(byte[] key)
          Move the cursor to positon around a record for stepping forward.
 void curjump(byte[] key, int jmode)
          Move the cursor to positon around a record.
 void curjumpobj(java.lang.Object key, int jmode)
          Move the cursor to positon around a record composed of serializable objects.
 byte[] curkey()
          Get the key of the record where the cursor is.
 java.lang.Object curkeyobj()
          Get the key of the record composed of serializable objects, where the cursor is.
 void curlast()
          Move the cursor to the last record.
 void curnext()
          Move the cursor to the next record.
 void curprev()
          Move the cursor to the next record.
 byte[] curval()
          Get the value of the record where the cursor is.
 java.lang.Object curvalobj()
          Get the value of the record where the cursor is.
 void delete(byte[] key)
          Delete a record.
static java.lang.String errmsg(int ecode)
          Get an error message.
 boolean error()
          Check whether a fatal error occured or not.
 boolean fatalerror()
          Check whether the database has a fatal error or not.
 byte[] fetch(byte[] key)
          Fetch a record.
protected  void finalize()
          Release the resources.
 byte[] firstkey()
          Get the first key.
 int fsiz()
          Get the size of the database file.
 byte[] get(byte[] key)
          Retrieve a record.
 java.lang.Object getobj(java.lang.Object key)
          Retrieve a record composed of serializable objects.
 int lnum()
          Get the number of the leaf nodes of B+ tree.
 java.lang.String name()
          Get the name of the database.
 byte[] nextkey()
          Get the next key.
 int nnum()
          Get the number of the non-leaf nodes of B+ tree.
 void optimize()
          Optimize the database.
 void out(byte[] key)
          Delete a record.
 void outobj(java.lang.Object key)
          Delete a record composed of serializable objects.
 void put(byte[] key, byte[] val)
          Store a record with overwrite.
 void put(byte[] key, byte[] val, int dmode)
          Store a record.
 void putobj(java.lang.Object key, java.lang.Object val, int dmode)
          Store a record composed of serializable objects.
static void remove(java.lang.String name)
          Remove a database file.
 int rnum()
          Get the number of the records stored in a database.
 void settuning(int lrecmax, int nidxmax, int lcnum, int ncnum)
          Set the tuning parameters for performance.
 void store(byte[] key, byte[] val, boolean replace)
          Store a record.
 void sync()
          Synchronize updating contents with the file and the device.
 void tranabort()
          Abort the transaction.
 void tranbegin()
          Begin the transaction.
 void trancommit()
          Commit the transaction.
static java.lang.String version()
          Get the version information.
 int vnum(byte[] key)
          Get the number of records corresponding a key.
 int vnumobj(java.lang.Object key)
          Get the number of records corresponding a key, composed of serializable objects.
 boolean writable()
          Check whether the database handle is a writer or not.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CMPDEC

public static final int CMPDEC
comparing mode: compare as decimal strings

See Also:
Constant Field Values

CMPLEX

public static final int CMPLEX
comparing mode: compare by lexical order

See Also:
Constant Field Values

CMPNUM

public static final int CMPNUM
comparing mode: compare as long integers

See Also:
Constant Field Values

CMPOBJ

public static final int CMPOBJ
comparing mode: compare as comparable objects

See Also:
Constant Field Values

DDUP

public static final int DDUP
write mode: concatenate values

See Also:
Constant Field Values

DKEEP

public static final int DKEEP
write mode: keep the existing value

See Also:
Constant Field Values

DOVER

public static final int DOVER
write mode: overwrite the existing value

See Also:
Constant Field Values

EALLOC

public static final int EALLOC
error code: memory allocation error

See Also:
Constant Field Values

EBROKEN

public static final int EBROKEN
error code: broken database file

See Also:
Constant Field Values

ECLOSE

public static final int ECLOSE
error code: close error

See Also:
Constant Field Values

EFATAL

public static final int EFATAL
error code: with fatal error

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

EMAP

public static final int EMAP
error code: memory mapping error

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

EMODE

public static final int EMODE
error code: invalid mode

See Also:
Constant Field Values

ENOERR

public static final int ENOERR
error code: no error

See Also:
Constant Field Values

ENOITEM

public static final int ENOITEM
error code: no item 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

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

ESYNC

public static final int ESYNC
error code: sync 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

JBACKWARD

public static final int JBACKWARD
jump mode: jump mode: step backward

See Also:
Constant Field Values

JFORWARD

public static final int JFORWARD
jump mode: jump mode: step forward

See Also:
Constant Field Values

OCREAT

public static final int OCREAT
open mode: writer creating

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

Villa

public Villa(java.lang.String name)
      throws VillaException
Get the database handle as a reader. The same as `Villa(name, Villa.OREADER, Villa.CMPLEX)'.

See Also:
Villa(java.lang.String, int, int)

Villa

public Villa(java.lang.String name,
             int omode,
             int cmode)
      throws VillaException
Get the database handle.

Parameters:
name - the name of a database file.
omode - the connection mode: `Villa.OWRITER' as a writer, `Villa.OREADER' as a reader. If the mode is `Villa.OWRITER', the following may be added by bitwise or: `Villa.OCREAT', which means it creates a new database if not exist, `Villa.OTRUNC', which means it creates a new database regardless if one exists. Both of `Villa.OREADER' and `Villa.OWRITER' can be added to by bitwise or: `Villa.ONOLCK', which means it opens a database file without file locking.
cmode - the comparing function: `Villa.CMPLEX' comparing keys in lexical order, `Villa.CMPNUM' comparing keys as numbers of big endian, `Villa.CMPDEC' comparing keys as decimal strings, `Villa.CMPOBJ' comparing keys as serialized objects implementing `java.util.Comparable'. The comparing function should be kept same in the life of a database.
Note:
While connecting as a writer, an exclusive lock is invoked to the database file. While connecting as a reader, a shared lock is invoked to the database file. The thread blocks until the lock is achieved. If `Villa.ONOLCK' is used, the application is responsible for exclusion control.
Method Detail

close

public void close()
           throws VillaException
Close the database handle.

Specified by:
close in interface ADBM
Throws:
VillaException - if an error occures.
Note:
Updating a database is assured to be written when the handle is closed. If a writer opens a database but does not close it appropriately, the database will be broken. If the transaction is activated and not committed, it is aborted.

curfirst

public void curfirst()
              throws VillaException
Move the cursor to the first record.

Throws:
VillaException - if an error occures or there is no record in the database.

curjump

public void curjump(byte[] key)
             throws VillaException
Move the cursor to positon around a record for stepping forward. The same as `curjump(key, Villa.JFORFARD)'.

VillaException
See Also:
curjump(byte[], int)

curjump

public void curjump(byte[] key,
                    int jmode)
             throws VillaException
Move the cursor to positon around a record.

Parameters:
key - a byte array of a key.
jmode - detail adjustment: `Villa.JFORWARD', which means that the cursor is set to the first record of the same key and that the cursor is set to the next substitute if completely matching record does not exist, `Villa.JBACKWARD', which means that the cursor is set to the last record of the same key and that the cursor is set to the previous substitute if completely matching record does not exist.
Throws:
VillaException - if an error occures or there is no record corresponding the condition.

curjumpobj

public void curjumpobj(java.lang.Object key,
                       int jmode)
                throws VillaException
Move the cursor to positon around a record composed of serializable objects. The same as `curjump(qdbm.Util.serialize(key), jmode)'.

VillaException
See Also:
curjump(byte[], int)
Note:
If serialization is failed, an instance of `VillaException' is thrown.

curkey

public byte[] curkey()
              throws VillaException
Get the key of the record where the cursor is.

Throws:
VillaException - if an error occures or no record corresponds to the cursor.

curkeyobj

public java.lang.Object curkeyobj()
                           throws VillaException
Get the key of the record composed of serializable objects, where the cursor is. The same as `qdbm.Util.deserialize(curkey())'.

VillaException
See Also:
curkey()
Note:
If serialization is failed, an instance of `VillaException' is thrown.

curlast

public void curlast()
             throws VillaException
Move the cursor to the last record.

Throws:
VillaException - if an error occures or there is no record in the database.

curnext

public void curnext()
             throws VillaException
Move the cursor to the next record.

Throws:
VillaException - if an error occures or there is no next record.

curprev

public void curprev()
             throws VillaException
Move the cursor to the next record.

Throws:
VillaException - if an error occures or there is no previous record.

curval

public byte[] curval()
              throws VillaException
Get the value of the record where the cursor is.

Throws:
VillaException - if an error occures or no record corresponds to the cursor.

curvalobj

public java.lang.Object curvalobj()
                           throws VillaException
Get the value of the record where the cursor is. The same as `qdbm.Util.deserialize(curval())'.

VillaException
See Also:
curval()
Note:
If serialization is failed, an instance of `VillaException' is thrown.

delete

public void delete(byte[] key)
            throws VillaException
Delete a record.

Specified by:
delete in interface ADBM
Parameters:
key - a byte array of a key.
Throws:
VillaException - if an error occures or no record corresponds.

errmsg

public static java.lang.String errmsg(int ecode)
Get an error message.

Parameters:
ecode - an error code.
Returns:
the message string of the error code.

error

public boolean error()
              throws VillaException
Check whether a fatal error occured or not.

Specified by:
error in interface ADBM
Returns:
true if the database has a fatal error, false if not.
Throws:
VillaException - if an error occures.

fatalerror

public boolean fatalerror()
                   throws VillaException
Check whether the database has a fatal error or not.

Returns:
true if the database has a fatal error, false if not.
Throws:
VillaException - if an error occures.

fetch

public byte[] fetch(byte[] key)
             throws VillaException
Fetch a record.

Specified by:
fetch in interface ADBM
Parameters:
key - a byte array of a key.
Returns:
a byte array of the value of the corresponding record.
Throws:
VillaException - if an error occures or no record corresponds.

finalize

protected void finalize()
                 throws java.lang.Throwable
Release the resources.

Overrides:
finalize in class java.lang.Object
java.lang.Throwable
Note:
If the database handle is not closed yet, it is closed. Every database should be closed explicitly. Do not cast the duty on the gerbage collection.

firstkey

public byte[] firstkey()
                throws VillaException
Get the first key.

Specified by:
firstkey in interface ADBM
Returns:
a byte array of the key of the first record.
Throws:
VillaException - if an error occures or no record corresponds.

fsiz

public int fsiz()
         throws VillaException
Get the size of the database file.

Returns:
the size of the database file.
Throws:
VillaException - if an error occures.
Note:
Because of the I/O buffer, the return value may be less than the real size.

get

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

Parameters:
key - a byte array of a key.
Returns:
a byte array of the value of the corresponding record.
Throws:
VillaException - if an error occures, no record corresponds.
Note:
When the key of duplicated records is specified, the value of the first record of the same key is selected.

getobj

public java.lang.Object getobj(java.lang.Object key)
                        throws VillaException
Retrieve a record composed of serializable objects. The same as `qdbm.Util.deserialize(get(qdbm.Util.serialize(key)))'.

VillaException
See Also:
get(byte[])
Note:
If serialization is failed, an instance of `VillaException' is thrown.

lnum

public int lnum()
         throws VillaException
Get the number of the leaf nodes of B+ tree.

Returns:
the number of the leaf nodes.
Throws:
VillaException - if an error occures.

name

public java.lang.String name()
                      throws VillaException
Get the name of the database.

Returns:
the string of the name of the database.
Throws:
VillaException - if an error occures.

nextkey

public byte[] nextkey()
               throws VillaException
Get the next key.

Specified by:
nextkey in interface ADBM
Returns:
a byte array of the key of the next record.
Throws:
VillaException - if an error occures or no record corresponds.

nnum

public int nnum()
         throws VillaException
Get the number of the non-leaf nodes of B+ tree.

Returns:
the number of the non-leaf nodes.
Throws:
VillaException - if an error occures.

optimize

public void optimize()
              throws VillaException
Optimize the database.

Throws:
VillaException - if an error occures.
Note:
In an alternating succession of deleting and storing with overwrite or concatenate, dispensable regions accumulate. This method is useful to do away with them. This method shuold not be used while the transaction is activated.

out

public void out(byte[] key)
         throws VillaException
Delete a record.

Parameters:
key - a byte array of a key.
Throws:
VillaException - if an error occures or no record corresponds.
Note:
When the key of duplicated records is specified, the first record of the same key is deleted. The cursor becomes unavailable due to updating database.

outobj

public void outobj(java.lang.Object key)
            throws VillaException
Delete a record composed of serializable objects. The same as `out(qdbm.Util.serialize(key))'.

VillaException
See Also:
out(byte[])
Note:
If serialization is failed, an instance of `VillaException' is thrown.

put

public void put(byte[] key,
                byte[] val)
         throws VillaException
Store a record with overwrite. The same as `put(key, val, Villa.DOVER)'.

VillaException
See Also:
put(byte[], byte[], int)

put

public void put(byte[] key,
                byte[] val,
                int dmode)
         throws VillaException
Store a record.

Parameters:
key - a byte array of a key.
val - a byte array of a value.
dmode - behavior when the key overlaps, by the following values: `Villa.DOVER', which means the specified value overwrites the existing one, `Villa.DKEEP', which means the existing value is kept, `Villa.DDUP', which means duplication of keys is allowed.
Throws:
VillaException - if an error occures or replace is cancelled.
Note:
A duplicated record is stored at the tail of the records of the same key. The cursor becomes unavailable due to updating database.

putobj

public void putobj(java.lang.Object key,
                   java.lang.Object val,
                   int dmode)
            throws VillaException
Store a record composed of serializable objects. The same as `put(qdbm.Util.serialize(key), qdbm.Util.serialize(val), dmode)'.

VillaException
See Also:
put(byte[], byte[], int)
Note:
If serialization is failed, an instance of `VillaException' is thrown.

remove

public static void remove(java.lang.String name)
                   throws VillaException
Remove a database file.

Parameters:
name - the name of a database file.
Throws:
VillaException - if an error occures.

rnum

public int rnum()
         throws VillaException
Get the number of the records stored in a database.

Returns:
the number of the records stored in the database.
Throws:
VillaException - if an error occures.

settuning

public void settuning(int lrecmax,
                      int nidxmax,
                      int lcnum,
                      int ncnum)
               throws VillaException
Set the tuning parameters for performance.

Parameters:
lrecmax - the max number of records in a leaf node of B+ tree. If it is not more than 0, the default value is specified.
nidxmax - the max number of indexes in a non-leaf node of B+ tree. If it is not more than 0, the default value is specified.
lcnum - the max number of caching leaf nodes. If it is not more than 0, the default value is specified.
ncnum - the max number of caching non-leaf nodes. If it is not more than 0, the default value is specified.
Throws:
VillaException - if an error occures.
Note:
The default setting is equivalent to `settuning(49, 192, 1024, 512)'. Because tuning paremeters are not saved in a database, you should specify them every opening a database.

store

public void store(byte[] key,
                  byte[] val,
                  boolean replace)
           throws VillaException
Store a record.

Specified by:
store in interface ADBM
Parameters:
key - a byte array of a key.
val - a byte array of a value.
replace - whether the existing value is to be overwritten or not.
Throws:
VillaException - if an error occures or replace is cancelled.

sync

public void sync()
          throws VillaException
Synchronize updating contents with the file and the device.

Throws:
VillaException - if an error occures.
Note:
This method is useful when another process uses the connected database file. This method shuold not be used while the transaction is activated.

tranabort

public void tranabort()
               throws VillaException
Abort the transaction.

Throws:
VillaException - if an error occures.
Note:
Updating a database in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction. Any other thread except for the one which began the transaction should not call this method.

tranbegin

public void tranbegin()
               throws VillaException
Begin the transaction.

Throws:
VillaException - if an error occures.
Note:
If a thread is already in the transaction, the other threads block until the prius is out of the transaction. Only one transaction can be activated with a database handle at the same time.

trancommit

public void trancommit()
                throws VillaException
Commit the transaction.

Throws:
VillaException - if an error occures.
Note:
Updating a database in the transaction is fixed when it is committed successfully. Any other thread except for the one which began the transaction should not call this method.

version

public static java.lang.String version()
Get the version information.

Returns:
the string of the version information.

vnum

public int vnum(byte[] key)
         throws VillaException
Get the number of records corresponding a key.

Parameters:
key - a byte array of a key.
Returns:
the number of corresponding records. If no record corresponds, 0 is returned.
Throws:
VillaException - if an error occures.

vnumobj

public int vnumobj(java.lang.Object key)
            throws VillaException
Get the number of records corresponding a key, composed of serializable objects. The same as `vnum(qdbm.Util.serialize(key))'.

VillaException
See Also:
vnum(byte[])
Note:
If serialization is failed, an instance of `VillaException' is thrown.

writable

public boolean writable()
                 throws VillaException
Check whether the database handle is a writer or not.

Returns:
true if the handle is a writer, false if not.
Throws:
VillaException - if an error occures.