Curia (qdbm)
Date: 2010-08-05

Overview | Package | Class | Tree | Index
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## qdbm
Class Curia

    java.lang.Object
      qdbm.Curia

All Implemented Interfaces:
  ADBM

    public class Curia

extends java.lang.Object
implements ADBM

The Java API of Curia, the extended 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` | `OLCKNB` open mode: lock without blocking
`static int` | `ONOLCK` open mode: open without locking
`static int` | `OREADER` open mode: open as a reader
`static int` | `OSPARSE` open mode: create as sparse files
`static int` | `OTRUNC` open mode: writer truncating
`static int` | `OWRITER` open mode: open as a writer
`boolean` | `silent` Whether to repress frequent exceptions.

Constructor Summary
`Curia(java.lang.String name)` Get the database handle as a reader.
`Curia(java.lang.String name, int omode, int bnum, int dnum)` Get the database handle.

Method Summary
`int` | `bnum()` Get the total number of the elements of each bucket array.
`int` | `busenum()` Get the total number of the used elements of each bucket array.
`void` | `close()` Close the database handle.
`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.
`long` | `fsiz()` Get the total size of the database files.
`byte[]` | `get(byte[] key)` Retrieve whole value of a record.
`byte[]` | `get(byte[] key, int start, int max)` Retrieve a record.
`byte[]` | `getlob(byte[] key)` Retrieve whole value of a large object.
`byte[]` | `getlob(byte[] key, int start, int max)` Retrieve a large object.
`int` | `inode()` Get the inode number of the database.
`void` | `iterinit()` Initialize the iterator of the database handle.
`byte[]` | `iternext()` Get the next key of the iterator.
`long` | `mtime()` Get the last modified time of the database.
`java.lang.String` | `name()` Get the name of the database.
`byte[]` | `nextkey()` Get the next key.
`void` | `optimize(int bnum)` Optimize the database.
`boolean` | `out(byte[] key)` Delete a record.
`boolean` | `outlob(byte[] key)` Delete a large object.
`boolean` | `put(byte[] key, byte[] val)` Store a record with overwrite.
`boolean` | `put(byte[] key, byte[] val, int dmode)` Store a record.
`boolean` | `putlob(byte[] key, byte[] val)` Store a large object with overwrite.
`boolean` | `putlob(byte[] key, byte[] val, int dmode)` Store a large object.
`static void` | `remove(java.lang.String name)` Remove a database directory.
`int` | `rnum()` Get the number of the records stored in the database.
`int` | `rnumlob()` Get the number of the large objects stored in the database.
`void` | `setalign(int align)` Set alignment of the database handle.
`void` | `setfbpsiz(int size)` Set the size of the free block pool.
`static byte[]` | `snaffle(java.lang.String name, byte[] key)` Retrieve a record directly from a database directory.
`void` | `store(byte[] key, byte[] val, boolean replace)` Store a record.
`void` | `sync()` Synchronize updating contents with the files and the devices.
`static java.lang.String` | `version()` Get the version information.
`int` | `vsiz(byte[] key)` Get the size of the value of a record.
`int` | `vsizlob(byte[] key)` Get the size of the value of a large object.
`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

### OLCKNB

    public static final int OLCKNB

  open mode: lock without blocking

  See Also:
    Constant Field Values

### ONOLCK

    public static final int ONOLCK

  open mode: open without locking

  See Also:
    Constant Field Values

### OREADER

    public static final int OREADER

  open mode: open as a reader

  See Also:
    Constant Field Values

### OSPARSE

    public static final int OSPARSE

  open mode: create as sparse files

  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

### silent

    public boolean silent

  Whether to repress frequent exceptions.

Constructor Detail

### Curia

    public Curia(java.lang.String name)
          throws CuriaException

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

  Throws:
    `CuriaException`
  See Also:
    `Curia(java.lang.String, int, int, int)`

### Curia

    public Curia(java.lang.String name,
                 int omode,
                 int bnum,
                 int dnum)
          throws CuriaException

  Get the database handle.

  Parameters:
    `name` - the name of a database directory.
    `omode` - the connection mode: `Curia.OWRITER' as a writer, `Curia.OREADER' as a reader. If the mode is `Curia.OWRITER', the following may be added by bitwise or: `Curia.OCREAT', which means it creates a new database if not exist, `Curia.OTRUNC', which means it creates a new database regardless if one exists. Both of `Curia.OREADER' and `Curia.OWRITER' can be added to by bitwise or: `Curia.ONOLCK', which means it opens a database directory without file locking, or `Curia.OLCKNB', which means locking is performed without blocking. `Curia.OCREAT' can be added to by bitwise or: `Curia.OSPARSE', which means it creates database files as sparse files.
    `bnum` - the number of elements of the each bucket array. If it is not more than 0, the default value is specified. The size of each bucket array is determined on creating, and can not be changed except for by optimization of the database. Suggested size of each bucket array is about from 0.5 to 4 times of the number of all records to store.
    `dnum` - the number of division of the database. If it is not more than 0, the default value is specified. The number of division can not be changed from the initial value. The max number of division is 512.
  Throws:
    `CuriaException` - if an error occurs.
  Note:
    While connecting as a writer, an exclusive lock is invoked to the database directory. While connecting as a reader, a shared lock is invoked to the database directory. The thread blocks until the lock is achieved. If `Curia.ONOLCK' is used, the application is responsible for exclusion control.

Method Detail

### bnum

    public int bnum()
             throws CuriaException

  Get the total number of the elements of each bucket array.

  Returns:
    the total number of the elements of each bucket array.
  Throws:
    `CuriaException` - if an error occurs.

### busenum

    public int busenum()
                throws CuriaException

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

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

### close

    public void close()
               throws CuriaException

  Close the database handle.

  Specified by:
    `close` in interface `ADBM`
  Throws:
    `CuriaException` - if an error occurs.
  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 CuriaException

  Delete a record.

  Specified by:
    `delete` in interface `ADBM`
  Parameters:
    `key` - a byte array of a key.
  Throws:
    `CuriaException` - if an error occurs 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 CuriaException

  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:
    `CuriaException` - if an error occurs.

### fatalerror

    public boolean fatalerror()
                       throws CuriaException

  Check whether the database has a fatal error or not.

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

### fetch

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

  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:
    `CuriaException` - if an error occurs or no record corresponds.

### finalize

    protected void finalize()
                     throws java.lang.Throwable

  Release the resources.

  Overrides:
    `finalize` in class `java.lang.Object`
  Throws:
    `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 CuriaException

  Get the first key.

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

### fsiz

    public long fsiz()
              throws CuriaException

  Get the total size of the database files.

  Returns:
    the total size of the database files.
  Throws:
    `CuriaException` - if an error occurs.

### get

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

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

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

### get

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

  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. If the silent flag is true and no record corresponds, `null' is returned instead of exception.
  Throws:
    `CuriaException` - if an error occurs, no record corresponds, or the size of the value of the corresponding record is less than the index specified by the parameter `start'.

### getlob

    public byte[] getlob(byte[] key)
                  throws CuriaException

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

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

### getlob

    public byte[] getlob(byte[] key,
                         int start,
                         int max)
                  throws CuriaException

  Retrieve a large object.

  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 be read. If it is negative, the size to read is unlimited.
  Returns:
    a byte array of the value of the corresponding large object. If the silent flag is true and no record corresponds, `null' is returned instead of exception.
  Throws:
    `CuriaException` - if an error occurs, no large object corresponds or the size of the value of the corresponding is less than the index specified by the parameter `start'.

### inode

    public int inode()
              throws CuriaException

  Get the inode number of the database.

  Returns:
    the inode number of the database directory.
  Throws:
    `CuriaException` - if an error occurs.

### iterinit

    public void iterinit()
                  throws CuriaException

  Initialize the iterator of the database handle.

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

### iternext

    public byte[] iternext()
                    throws CuriaException

  Get the next key of the iterator.

  Returns:
    a byte array of the key of the next record. If the silent flag is true and no record corresponds, `null' is returned instead of exception.
  Throws:
    `CuriaException` - if an error occurs 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.

### mtime

    public long mtime()
               throws CuriaException

  Get the last modified time of the database.

  Returns:
    the last modified time of the database.
  Throws:
    `CuriaException` - if an error occurs.

### name

    public java.lang.String name()
                          throws CuriaException

  Get the name of the database.

  Returns:
    the string of the name of the database.
  Throws:
    `CuriaException` - if an error occurs.

### nextkey

    public byte[] nextkey()
                   throws CuriaException

  Get the next key.

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

### optimize

    public void optimize(int bnum)
                  throws CuriaException

  Optimize the database.

  Parameters:
    `bnum` - the number of the elements of each bucket array. If it is not more than 0, the default value is specified.
  Throws:
    `CuriaException` - if an error occurs.
  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 boolean out(byte[] key)
                throws CuriaException

  Delete a record.

  Parameters:
    `key` - a byte array of a key.
  Returns:
    always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception.
  Throws:
    `CuriaException` - if an error occurs or no record corresponds.

### outlob

    public boolean outlob(byte[] key)
                   throws CuriaException

  Delete a large object.

  Parameters:
    `key` - a byte array of a key.
  Returns:
    always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception.
  Throws:
    `CuriaException` - if an error occurs or no large object corresponds.

### put

    public boolean put(byte[] key,
                       byte[] val)
                throws CuriaException

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

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

### put

    public boolean put(byte[] key,
                       byte[] val,
                       int dmode)
                throws CuriaException

  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: `Curia.DOVER', which means the specified value overwrites the existing one, `Curia.DKEEP', which means the existing value is kept, `Curia.DCAT', which means the specified value is concatenated at the end of the existing value.
  Returns:
    always true. However, if the silent flag is true and replace is cancelled, false is returned instead of exception.
  Throws:
    `CuriaException` - if an error occurs or replace is cancelled.

### putlob

    public boolean putlob(byte[] key,
                          byte[] val)
                   throws CuriaException

  Store a large object with overwrite. The same as `putlob(key, val, Curia.DOVER)'.

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

### putlob

    public boolean putlob(byte[] key,
                          byte[] val,
                          int dmode)
                   throws CuriaException

  Store a large object.

  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: `Curia.DOVER', which means the specified value overwrites the existing one, `Curia.DKEEP', which means the existing value is kept, `Curia.DCAT', which means the specified value is concatenated at the end of the existing value.
  Returns:
    always true. However, if the silent flag is true and replace is cancelled, false is returned instead of exception.
  Throws:
    `CuriaException` - if an error occurs or replace is cancelled.

### remove

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

  Remove a database directory.

  Parameters:
    `name` - the name of a database directory.
  Throws:
    `CuriaException` - if an error occurs.

### rnum

    public int rnum()
             throws CuriaException

  Get the number of the records stored in the database.

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

### rnumlob

    public int rnumlob()
                throws CuriaException

  Get the number of the large objects stored in the database.

  Returns:
    the number of the large objects stored in the database.
  Throws:
    `CuriaException` - if an error occurs.

### setalign

    public void setalign(int align)
                  throws CuriaException

  Set alignment of the database handle.

  Parameters:
    `align` - the basic size of alignment.
  Throws:
    `CuriaException` - if an error occurs.
  Note:
    If alignment is set to a database, the efficiency of overwriting values is 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.

### setfbpsiz

    public void setfbpsiz(int size)
                   throws CuriaException

  Set the size of the free block pool.

  Parameters:
    `size` - the size of the free block pool of a database.
  Throws:
    `CuriaException` - if an error occurs.
  Note:
    The default size of the free block pool is 16. If the size is greater, the space efficiency of overwriting values is improved with the time efficiency sacrificed.

### snaffle

    public static byte[] snaffle(java.lang.String name,
                                 byte[] key)
                          throws CuriaException

  Retrieve a record directly from a database directory.

  Parameters:
    `name` - the name of a database directory.
    `key` - a byte array of a key.
  Throws:
    `CuriaException` - if an error occurs or no record corresponds.
  Note:
    Although this method can be used even while the database directory is locked by another process, it is not assured that recent updated is reflected.

### store

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

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

### sync

    public void sync()
              throws CuriaException

  Synchronize updating contents with the files and the devices.

  Throws:
    `CuriaException` - if an error occurs.
  Note:
    This method is useful when another process uses the connected database directory.

### version

    public static java.lang.String version()

  Get the version information.

  Returns:
    a string of the version information.

### vsiz

    public int vsiz(byte[] key)
             throws CuriaException

  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. If the silent flag is true and no record corresponds, -1 is returned instead of exception.
  Throws:
    `CuriaException` - if an error occurs or no record corresponds.
  Note:
    Because this method does not read the entity of a record, it is faster than `get'.

### vsizlob

    public int vsizlob(byte[] key)
                throws CuriaException

  Get the size of the value of a large object.

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

### writable

    public boolean writable()
                     throws CuriaException

  Check whether the database handle is a writer or not.

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

Overview | Package | Class | Tree | Index
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD