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.