All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class au.com.pharos.gdbm.GdbmFile

au.com.pharos.gdbm.GdbmFile

public class GdbmFile

implements Closeable

This database is a simple on-disk hash table.

Both the hash keys and values are binary strings of any length. They are converted to and from Java objects using customizable packing strategies.

The implementation of this class consists of two levels: a Java-level interface, and a set of private native functions implemented in C. As much functionality as possible is implemented in Java: the C functions generally just marshal the information for presentation to the native GDBM library.

The native library gdbmjava must be available for dynamic loading in a system-dependant manner.

See the GDBM documentation file, and the JavaGDBM home page for more information.

Version:

$Revision: 3.12 $

Author:

Martin Pool

See Also:

Packing, GdbmTest, GdbmDictionary

FAST

Flag indicating GDBM should write to the database without disc synchronization.

NEWDB

The caller wants exclusive read/write access, and the database should be replaced if it already exists.

READER

Indicates that the caller will just read the database.

WRCREAT

The caller wants exclusive read/write access, and the database should be created if it does not already exist.

WRITER

The caller wants read/write access to an existing database and requires exclusive access.

GdbmFile(String, int)

Creates a new GdbmFile object representing an disk database.

close()

Close the database file if it is still open.

delete(Object)

Remove a record from the database.

exists(Object)

Indicate whether the specified key is in the database, without returning the value.

fetch(Object)

Retrieve the value corresponding to a particular key.

finalize()

Close the database when the GdbmFile is garbage-collected.

getLibraryVersion()

Returns a string indicating the version of the underlying GDBM library.

getWrapperVersion()

Return a string indicating the version of the JavaGDBM library wrapper.

isEmpty()

Check whether the database is empty.

isOpen()

Indicate whether the database is open or not.

isWritable()

Indicate whether the database is writable.

keys()

Return an enumeration which will return all of the keys for the database of the file in (apparently) random order.

reorganize()

Compact the database file.

setKeyPacking(Packing)

Set the object to be used as the packing strategy for converting key objects to and from the byte arrays stored in the database.

setValuePacking(Packing)

Set the object to be used as the packing strategy for converting value objects to and from the byte arrays stored in the database.

size()

Count the records in the database.

store(Object, Object)

Store a value in the database, replacing any existing value with the same key.

storeNoReplace(Object, Object)

Store a value in the database, unless a record with the same key already exists.

sync()

Flush changes to disk.

 public static final int READER

Indicates that the caller will just read the database. Many readers may share a database.

 public static final int WRITER

The caller wants read/write access to an existing database and requires exclusive access.

 public static final int WRCREAT

The caller wants exclusive read/write access, and the database should be created if it does not already exist.

 public static final int NEWDB

The caller wants exclusive read/write access, and the database should be replaced if it already exists.

 public static final int FAST

Flag indicating GDBM should write to the database without disc synchronization. This allows faster writes, but may produce an inconsistent database in the event of abnormal termination of the writer.

 public GdbmFile(String fileName,
                 int flags) throws GdbmException

Creates a new GdbmFile object representing an disk database. The database is opened or created on disk.

Both key and value strategies default to RawPacking, meaning that the database will use raw byte arrays for both key and value.

TODO: Allow the caller to specify the block size and/or cache size.

Parameters:

fileName - the disk filename in which the data will be stored.

flags - any of READER, WRITER, WRCREAT, and NEWDB, optionally ORed with FAST

Throws: GdbmException

if the database cannot be opened or created.

See Also:

READER, WRITER, WRCREAT, NEWDB, FAST

 public synchronized void close() throws GdbmException

Close the database file if it is still open.

Note that the disk file is locked against access from other processes while it is open. To prevent contention, it may be useful to explicitly close the file rather than waiting for the garbage-collector.

See Also:

isOpen

 public void finalize() throws GdbmException

Close the database when the GdbmFile is garbage-collected.

See Also:

close

 public void setKeyPacking(Packing newPacking)

Set the object to be used as the packing strategy for converting key objects to and from the byte arrays stored in the database.

Depending on the class of Java object used as the key of your database, it may be appropriate to use a packing strategy from the au.com.pharos.packing package, or to define a new subclass of one of those strategies.

See Also:

Packing, setValuePacking

 public void setValuePacking(Packing newPacking)

Set the object to be used as the packing strategy for converting value objects to and from the byte arrays stored in the database.

Depending on the class of Java object used as the key of your database, it may be appropriate to use a packing strategy from the au.com.pharos.packing package, or to define a new subclass of one of those strategies.

See Also:

Packing, setKeyPacking

 public static String getLibraryVersion()

Returns a string indicating the version of the underlying GDBM library.

Returns:

the version of the native GDBM library.

 public static String getWrapperVersion()

Return a string indicating the version of the JavaGDBM library wrapper.

The most current release is available from the JavaGDBM home page.

Returns:

the release number of the JavaGDBM library

 public boolean isWritable()

Indicate whether the database is writable.

Databases are opened in either read-write or read-only mode, and remain in that mode until they are closed.

Returns:

true if the database may be written; otherwise false.

See Also:

GdbmFile

 public boolean isOpen()

Indicate whether the database is open or not.

A database is open from the point of creation until close() is called, if ever, after which it is closed.

Returns:

false if the database has been closed; otherwise true.

See Also:

close

 public void reorganize() throws GdbmException

Compact the database file.

If you have had a lot of deletions and would like to shrink the space used by the GDBM file, this function will reorganize the database. GDBM will not shorten the length of a GDBM file (deleted file space will be reused) except by using this reorganization, though it will reuse the vacant space.

The database must be writable.

 public void sync() throws GdbmException

Flush changes to disk.

This function is only required when the database is opened with the FAST flag set. By default, changes are flushed to disk after every update.

The database must be writable.

See Also:

FAST

 public Object fetch(Object key) throws GdbmException

Retrieve the value corresponding to a particular key.

Parameters:

key - the key of the record to be retrieved

Returns:

the value of the record with the specified key; or null if the key is not present in the database.

 public boolean exists(Object key) throws GdbmException

Indicate whether the specified key is in the database, without returning the value.

Parameters:

key - the key of the record to be retrieved

Returns:

true if a record with the specified key is present; otherwise false.

 public void store(Object key,
                   Object value) throws GdbmException

Store a value in the database, replacing any existing value with the same key.

Parameters:

key - key under which to store the value

value - value to be stored

Throws: GdbmException

if the object is a reader; or if an IO error occurs

 public void storeNoReplace(Object key,
                            Object value) throws GdbmException

Store a value in the database, unless a record with the same key already exists.

Parameters:

key - key under which to store the value.

value - value to be stored.

Throws: GdbmException

if a record with the specified key already exists; or if the object is a reader; or if an IO error occurs

 public void delete(Object key) throws GdbmException

Remove a record from the database.

Parameters:

key - key of the record to be removed

Throws: GdbmException

if there is no record with the specified key; or if the object is a reader; or if an IO error occurs.

 public Enumeration keys() throws GdbmException

Return an enumeration which will return all of the keys for the database of the file in (apparently) random order.

Caution: If the database is modified while an enumeration is in progress, then changes in the hash table may cause the enumeration to miss some records.

See Also:

Enumeration

 public boolean isEmpty() throws GdbmException

Check whether the database is empty.

Returns:

true if the database contains no records; otherwise false.

 public synchronized int size() throws GdbmException

Count the records in the database.

This is implemented by iterating over the database, and so is a fairly expensive operation.

This method locks the database to make sure the count is accurate.

Returns:

the number of records in the database

See Also:

isEmpty

All Packages  Class Hierarchy  This Package  Previous  Next  Index