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.