Berkeley DB: Configuring and Building the Java API

Java Compatibility
Java Installation
Building Java
Building a shared library version of Berkeley DB
Building libdb_java
General Usage Notes

Java Compatibility

Java DB has been tested with the Sun Microsystems JDK 1.1 on Windows/NT and SunOS 5.5, and it should work with any JDK 1.1 compatible environment. The most important thing to understand is whether the target Java environment supports the JNI (Java Native Interface) which we use, rather than some other way for DLLs to interface to java. The JNI is new to JDK 1.1, but more likely to be implementable across many platforms.

Java Installation

We expect that you've already installed the Java JDK or equivalent on your system. Since you are reading this, you also already have a copy of the Berkeley DB package. For the sake of discussion, we'll assume it's in a directory called db-VERSION, e.g., you extracted Berkeley DB version 2.3.12 and you did not change the top-level directory name. The files related to Java are in two subdirectories of db-VERSION: java, the java source files, and libdb_java, the C++ files that provide the "glue" between java and Berkeley DB. The directory tree looks like this:

                        db-VERSION
                       /          \
                    java        libdb_java
                     |              |
                    src            ...
                     |
                    com
                     |
                 sleepycat
                /         \
               db       examples
               |           |
              ...         ...

This naming conforms to the emerging standard for naming java packages. When the java code is built, it is placed into a classes subdirectory that is parallel to the src subdirectory.

Building Java

Both db-VERSION/java and db-VERSION/libdb_java have Makefiles:

Makefile.win32
Makefile.unix

The java directory can be built using your make command and the appropriate Makefile. If you've never built java code before, there are two things you will need to do before issuing the make command.

First, make sure the java compiler (usually javac) is in your path. If you installed the sun JDK distribution in /usr/java , then the java tools are in the directory /usr/java/bin.

Make sure your classpath is set correctly. Set your environment variable CLASSPATH to contain at least the standard class library (perhaps in /usr/java/lib/classes.zip) and add the Berkeley DB classes in as well. Using the UNIX csh, this might be:

setenv CLASSPATH "/usr/java/lib/classes.zip:/db-VERSION/java/classes"

On Windows/95, your autoexec.bat would need to have something like:

set CLASSPATH="c:/java/lib/classes.zip;c:/db-VERSION/java/classes"

Note the use of semicolons on Windows. On Windows/NT, you'll set this variable in the control panel.

Now you can run make to build the java directory, e.g.:

cd db-VERSION/java
make -f Makefile.unix

Building a shared library version of Berkeley DB

See Building a Shared Library Version of Berkeley DB for more information.

You MUST build Berkeley DB as a shared library before you proceed beyond this step.

Building libdb_java

Before building libdb_java, make sure you have a shared library version of Berkeley DB (see above).

On UNIX:

NB: The libdb_java/Makefile.unix Makefile is written to expect that the system compiler is named "gcc" and is the GNU C compiler. In addition, it uses compiler-specific options when building. If you are using a different compiler than gcc, you'll need to modify Makefile.unix to work with it.

First, edit the line at the beginning of libdb_java/Makefile.unix:

JAVAINSDIR=	/usr/java1.1/

Change JAVAINSDIR to be the top level directory of your java JDK tree. This is the level above the bin and include directories. Then issue a make command in the libdb_java directory:

% cd db-VERSION/libdb_java
% make -f Makefile.unix

On Win/:

Issue the nmake command in the libdb_java directory:

C:\db_distribution\libdb_java> nmake /f Makefile.win32

General Usage Notes

For your application to use Db successfully, you must set your CLASSPATH environment variable to include db-VERSION/java/classes as well as the classes in your java distribution. See the section above on "BUILDING JAVA" for further information.

On Windows, you will want to set your PATH variable to include:

db-VERSION/libdb_java;db-VERSION/build_win32/debug

On UNIX, you will want to set LD_LIBRARY_PATH to include:

db-VERSION/libdb_java;db-VERSION/build_unix

These are the locations of your shared libraries. If you get a:

java.lang.UnsatisfiedLinkError

exception when you run, chances are you do not have the PATH set up correctly.

Or, of course, you may copy the built dynamic libraries (libdb and java_db) to a directory already in your path.

To ensure that everything is running correctly, you may want to try a simple test from the example programs in:

db-VERSION/java/src/com/sleepycat/examples

(which should have been built in the "BUILDING JAVA" section above):

% java com.sleepycat.examples.AccessExample

This example program will prompt for text input lines which are then stored with their reversed text in a simple Btree named "db.access" in your current directly. Try giving it two lines of text and then end-of-file. Before it exits, you should see the reversed text. If you run it again, lines will be there from your previous run. This is an excellent check to make sure the fundamental things are working right.

NOTE: when you run some of the other examples on Solaris, you may get an "rmutex" libc error message. This is a known bug in Solaris 2.5, and it is fixed by Sun patch 103187-25. See the Sleepycat Software Release FAQ web page (www.sleepycat.com) for further information on this problem.