## qdbm
Class Depot

    java.lang.Object
      |
      +--qdbm.Depot

All Implemented Interfaces:
  ADBM

public class Depot
extends java.lang.Object
implements ADBM

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

Field Summary
`static int` `DCAT` 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` `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
`Depot(java.lang.String name)` Get the database handle as a reader.
`Depot(java.lang.String name, int omode, int bnum)` Get the database handle.

Method Summary
`int` `bnum()` Get the number of the elements of the bucket array.
`int` `busenum()` Get the number of the used elements of the bucket array.
`void` `close()` Close the database handle.
`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 whole value of a record.
`byte[]` `get(byte[] key, int start, int max)` Retrieve a record.
`void` `iterinit()` Initialize the iterator of the database handle.
`byte[]` `iternext()` Get the next key of the iterator.
`java.lang.String` `name()` Get the name of the database.
`byte[]` `nextkey()` Get the next key.
`void` `optimize(int bnum)` Optimize the database.
`void` `out(byte[] key)` Delete a record.
`void` `put(byte[] key, byte[] val)` Store a record with overwrite.
`void` `put(byte[] key, byte[] val, int dmode)` Store a record.
`static void` `remove(java.lang.String name)` Remove a database file.
`int` `rnum()` Get the number of the records stored in the database.
`void` `setalign(int align)` Set alignment of the database handle.
`void` `store(byte[] key, byte[] val, boolean replace)` Store a record.
`void` `sync()` Synchronize updating contents with the file and the device.
`static java.lang.String` `version()` Get the version information.
`int` `vsiz(byte[] key)` Get the size of the value of a record.
`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

### DCAT

    public static final int DCAT

  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

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

### Depot

    public Depot(java.lang.String name)
          throws DepotException

  Get the database handle as a reader. The same as `Depot(name, Depot.OREADER, -1)'.

See Also:
  `Depot(java.lang.String, int, int)`

### Depot

    public Depot(java.lang.String name,
                 int omode,
                 int bnum)
          throws DepotException

  Get the database handle.

Parameters:
  `name` - the name of a database file.
  `omode` - the connection mode: `Depot.OWRITER' as a writer, `Depot.OREADER' as a reader. If the mode is `Depot.OWRITER', the following may be added by bitwise or: `Depot.OCREAT', which means it creates a new database if not exist, `Depot.OTRUNC', which means it creates a new database regardless if one exists. Both of `Depot.OREADER' and `Depot.OWRITER' can be added to by bitwise or: `Depot.ONOLCK', which means it opens a database file without file locking.
  `bnum` - the number of elements of the bucket array. If it is not more than 0, the default value is specified. The size of a bucket array is determined on creating, and can not be changed except for by optimization of the database. Suggested size of a bucket array is about from 0.5 to 4 times of the number of all records to store.
Throws:
  `DepotException` - if an error occures.
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 `Depot.ONOLCK' is used, the application is responsible for exclusion control.

Method Detail

### bnum

    public int bnum()
             throws DepotException

  Get the number of the elements of the bucket array.

  Returns:
    the number of the elements of the bucket array.
  Throws:
    `DepotException` - if an error occures.

### busenum

    public int busenum()
                throws DepotException

  Get the number of the used elements of the bucket array.

  Returns:
    the number of the used elements of the bucket array.
  Throws:
    `DepotException` - if an error occures.
  Note:
    This method is inefficient because it accesses all elements of the bucket array.

### close

    public void close()
               throws DepotException

  Close the database handle.

  Specified by:
    `close` in interface `ADBM`
  Throws:
    `DepotException` - 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.

### delete

    public void delete(byte[] key)
                throws DepotException

  Delete a record.

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

### econv

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

  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:
    `DepotException` - 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 DepotException

  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:
    `DepotException` - if an error occures.

### fatalerror

    public boolean fatalerror()
                       throws DepotException

  Check whether the database has a fatal error or not.

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

### fetch

    public byte[] fetch(byte[] key)
                 throws DepotException

  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:
    `DepotException` - 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 DepotException

  Get the first key.

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

### fsiz

    public int fsiz()
             throws DepotException

  Get the size of the database file.

  Returns:
    the size of the database file.
  Throws:
    `DepotException` - if an error occures.

### get

    public byte[] get(byte[] key)
               throws DepotException

  Retrieve whole value of a record. The same as `get(key, 0, -1)'.

    `DepotException`
  See Also:
    `get(byte[], int, int)`

### get

    public byte[] get(byte[] key,
                      int start,
                      int max)
               throws DepotException

  Retrieve a record.

  Parameters:
    `key` - a byte array of a key.
    `start` - the array index of the beginning of the value to be read.
    `max` - the max size to read with. If it is negative, the size is unlimited.
  Returns:
    a byte array of the value of the corresponding record.
  Throws:
    `DepotException` - if an error occures, no record corresponds, or the size of the value of the corresponding record is less than the index specified by the parameter `start'.

### iterinit

    public void iterinit()
                  throws DepotException

  Initialize the iterator of the database handle.

  Throws:
    `DepotException` - if an error occures.
  Note:
    The iterator is used in order to access the key of every record stored in a database.

### iternext

    public byte[] iternext()
                    throws DepotException

  Get the next key of the iterator.

  Returns:
    a byte array of the key of the next record.
  Throws:
    `DepotException` - if an error occures or no record corresponds.
  Note:
    It is possible to access every record by iteration of calling this method. However, it is not assured if updating the database is occurred while the iteration. Besides, the order of this traversal access method is arbitrary, so it is not assured that the order of storing matches the one of the traversal access.

### name

    public java.lang.String name()
                          throws DepotException

  Get the name of the database.

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

### nextkey

    public byte[] nextkey()
                   throws DepotException

  Get the next key.

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

### optimize

    public void optimize(int bnum)
                  throws DepotException

  Optimize the database.

  Parameters:
    `bnum` - the number of the elements of the bucket array. If it is not more than 0, the default value is specified.
  Throws:
    `DepotException` - 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.

### out

    public void out(byte[] key)
             throws DepotException

  Delete a record.

  Parameters:
    `key` - a byte array of a key.
  Throws:
    `DepotException` - if an error occures or no record corresponds.

### put

    public void put(byte[] key,
                    byte[] val)
             throws DepotException

  Store a record with overwrite. The same as `put(key, val, Depot.DOVER)'.

    `DepotException`
  See Also:
    `put(byte[], byte[], int)`

### put

    public void put(byte[] key,
                    byte[] val,
                    int dmode)
             throws DepotException

  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: `Depot.DOVER', which means the specified value overwrites the existing one, `Depot.DKEEP', which means the existing value is kept, `Depot.DCAT', which means the specified value is concatenated at the end of the existing value.
  Throws:
    `DepotException` - if an error occures or replace is cancelled.

### remove

    public static void remove(java.lang.String name)
                       throws DepotException

  Remove a database file.

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

### rnum

    public int rnum()
             throws DepotException

  Get the number of the records stored in the database.

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

### setalign

    public void setalign(int align)
                  throws DepotException

  Set alignment of the database handle.

  Parameters:
    `align` - the basic size of alignment.
  Throws:
    `DepotException` - if an error occures.
  Note:
    If alignment is set to a database, the efficiency of overwriting values are improved. The size of alignment is suggested to be average size of the values of the records to be stored. If alignment is positive, padding whose size is multiple number of the alignment is placed. If alignment is negative, as `vsiz' is the size of a value, the size of padding is calculated with `(vsiz / pow(2, abs(align) - 1))'. Because alignment setting is not saved in a database, you should specify alignment every opening a database.

### store

    public void store(byte[] key,
                      byte[] val,
                      boolean replace)
               throws DepotException

  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:
    `DepotException` - if an error occures or replace is cancelled.

### sync

    public void sync()
              throws DepotException

  Synchronize updating contents with the file and the device.

  Throws:
    `DepotException` - if an error occures.
  Note:
    This method is useful when another process uses the connected database file.

### version

    public static java.lang.String version()

  Get the version information.

  Returns:
    the string of the version information.

### vsiz

    public int vsiz(byte[] key)
             throws DepotException

  Get the size of the value of a record.

  Parameters:
    `key` - a byte array of a key.
  Returns:
    the size of the value of the corresponding record.
  Throws:
    `DepotException` - if an error occures or no record corresponds.
  Note:
    Because this method does not read the entity of a record, it is faster than `get'.

### writable

    public boolean writable()
                     throws DepotException

  Check whether the database handle is a writer or not.

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