QDBM provides API for Java. This encapsulates the basic API and the extended API of QDBM, and make them thread-safe. This API is implemented with the APIs for C called with Java Native Interface.
The basic API for Java realizes a database with a file. Constructors of the class `Depot' open a database file. The method `close' is used in order to close the database. Although the finalizer also try to close the database, do not rely on it. The method `put' is used in order to store a record. The method `out' is used in order to delete a record. The method `get' is used in order to retrieve a record. Besides, most operations like ones of the basic API for C is available. Each methods throws an instance of the class `DepotException' if an error occures.
The extended API for Java realizes a database with a file. Constructors of the class `Curia' open a database file. The method `close' is used in order to close the database. Although the finalizer also try to close the database, do not rely on it. The method `put' is used in order to store a record. The method `out' is used in order to delete a record. The method `get' is used in order to retrieve a record. Operations for managing large objects are also privided. Besides, most operations like ones of the extended API for C is available. Each methods throws an instance of the class `CuriaException' if an error occures.
Both of the class `Depot' and the class `Curia' implement the interface `ADBM' which is abstraction of database managers compatible with DBM of UNIX standard. Each methods throws an instance of the class `DBMException'. In this framework, it is possible to store a serializable object in the database. This mechanism is useful for object persistence. When you choose the one of three API, `Depot' is suggested if performance is weighted, `Curia' is suggested if scalability is weighted, , `ADBM' is suggested if elegance and maintenance are weighted.
For more information about the APIs, read documents in the sub directory `japidoc' and each header file.
Make sure that JDK of 1.2 or later version is installed, the environment variable JAVA_HOME is set appropriately. And make sure that QDBM is installed under `/usr/local'.
Change the current working directory to the subdirectory named `java'.
cd java
Run the configuration script.
./configure
Build programs.
make
Perform self-diagnostic test.
make check
Install programs This operation must be carried out by the root user.
make install
When a series of work finishes, a Java archive `qdbm.jar' is installed under the `/usr/local/lib'. And, such native libraries as `libjqdbm.so' are installed under `/usr/local/lib'.
On Windows (Cygwin), you should follow the procedures below for installation.
Run the configuration script.
./configure
Build programs.
make win
Perform self-diagnostic test.
make check
Install programs. As well, perform `make uninstall-win' to uninstall them.
make install-win
On Windows, an import library `libjqdbm.dll.a' is created, and a dynamic linking library `jqdbm.dll' is created instead of such a shared libraries as `libjqdbm.so'. `jqdbm.dll' is installed into such a system directory as `C:\WINNT\SYSTEM32'.
To build and execute programs using QDBM, the following environment variable should be set.
Set the class path, which the environment variable CLASSPATH defines, to include the full path of `qdbm.jar'.
CLASSPATH=$CLASSPATH:/usr/local/lib/qdbm.jar export CLASSPATH
Set the library path, which the environment variable LD_LIBRARY_PATH defines, to include `/usr/local/lib'.
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib export LD_LIBRARY_PATH
The following example stores and retrieves a phone number, using the name as the key.
import qdbm.*; public class Sample { static String NAME = "mikio"; static String NUMBER = "000-1234-5678"; static String DBNAME = "book"; public static void main(String[] args){ Depot depot = null; try { // open the database depot = new Depot(DBNAME, Depot.OWRITER | Depot.OCREAT, -1); // store the record depot.put(NAME.getBytes(), NUMBER.getBytes()); // retrieve the record byte[] res = depot.get(NAME.getBytes()); System.out.println("Name: " + NAME); System.out.println("Number: " + new String(res)); } catch(DepotException e){ e.printStackTrace(); } finally { // close the database if(depot != null){ try { depot.close(); } catch(DepotException e){ e.printStackTrace(); } } } } }
The following example is a transcription of the one above, using the interface `ADBM'.
import qdbm.*; public class Sample { static String NAME = "mikio"; static String NUMBER = "000-1234-5678"; static String DBNAME = "book"; public static void main(String[] args){ ADBM dbm = null; try { // open the database dbm = new Depot(DBNAME, Depot.OWRITER | Depot.OCREAT, -1); // store the record dbm.storeobj(NAME, NUMBER, true); // retrieve the record Object res = dbm.fetchobj(NAME); System.out.println("Name: " + NAME); System.out.println("Number: " + res); } catch(DBMException e){ e.printStackTrace(); } finally { // close the database if(dbm != null){ try { dbm.close(); } catch(DBMException e){ e.printStackTrace(); } } } } }
For building a program using Java API of QDBM, set the environment variables and then perform `javac'. For example, the following command is executed to build `Sample.class' from `Sample.java'.
javac Sample.java
Depot and Curia have restrictions that two or more handles of the same database file should not be used by a process at the same time. So, when a database is used by two or more threads, open the database in the main thread and pass the handle to each thread.
Although methods to store a serialized object is useful, object serialization is inefficient in time and space. So, if there is a method to get a byte array from an object, you should use APIs with byte arrays.