## 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 void` `econv(java.lang.String name, boolean big)` Convert a database file for another platform with different byte order.
`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.

### econv

    public static void econv(java.lang.String name,
                             boolean big)
                      throws VillaException

  Convert a database file for another platform with different byte order.

  Parameters:
    `name` - the name of a database file.
    `big` - whether the result is for big endian or not.
  Throws:
    `VillaException` - if an error occures.

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