gecko-dev/db/java/README

# @(#)README	10.7 (Sleepycat) 5/2/98

                        Notes for Java users of DB

These are notes to help you install and program to the Java DB library.
For the most part, the installation and usage is quite straightforward.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
COMPATIBILITY:

Java DB has been tested with the Sun JDK 1.1 (http://www.javasoft.com) 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.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
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 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
DB.  The directory tree looks like this:

			db-VERSION
		       /          \
		    java	libdb_java
		     |		    |
		    src		   ...
		     |
		 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 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 LIB VERSION of DB:

If you are on Windows/NT or Windows, you can build a shared lib version
of DB by opening the build.win32/Berkeley_DB.dsw workspace and selecting
target DB_DLL.  Set the configuration to Win32 Debug, and build.  Make
sure there is a build.win32/Debug/libdb.dll as a result.

If you are on UNIX, you will need to do a little extra work to build a
shared library version of DB.  By default, DB builds as a static library.
If you've already built DB, you can copy your build directory to use as
a work space, e.g.:

	% cd db-VERSION
	% cp -r build.unix build.shlib
	% cd build.shlib
	% make clean

Now you'll need to consult your system documentation to understand how to
build DB as a shared library.  As UNIX architectures do not all build
shared libraries the same way, DB is not distributed with support for
building shared libraries.  You MUST build DB as a shared library before
you proceed beyond this step.

For some examples of building shared library versions of DB, please see
the directory SHARED.example.  If you build a shared library version of
DB for a compiler/architecture combination that is not represented by a
file in that directory, please email it to us at db@sleepycat.com, and
we'll add it to the collection.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
BUILDING LIBDB_JAVA:

Before building libdb_java, make sure you have a shared library version
of 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/java/java_db;db-VERSION/build.win32/debug

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

   db-VERSION/java/java_db;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.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
PROGRAMMING NOTES:

The API closely parallels the DB/C++ interface, and to a great degree,
the DB C interface.  If you are currently using either of those APIs,
there will be very little to surprise you in Java DB.  We've even taken
great care to make the names of classes, constants, methods, and even
method arguments identical, where possible, across all three APIs.

If there are embedded null strings in the db_config argument for
DbEnv.appinit(), they will be treated as the end of the list of config
strings, even though you may have allocated a longer array.  Fill in all
the strings in your array unless you intend to cut it short.

The callback installed for DbEnv.set_errcall will run in the same thread
as the caller to DbEnv.set_errcall.  Make sure that thread remains running
until your application exits or DbEnv.appexit() is called.

The DB package requires that you explicitly call close on each individual
Db, Dbc that you obtained or any DbLocktab or DbTxnMgr that you explicitly
opened.  Your database activity may not be synchronized to disk unless you
do so.

The DbMpool class has a small subset of the corresponding DB/C++
functionality.  This has been provided to allow you to perform certain
administrative actions on underlying MPOOL's opened as a consequence
of DbEnv.appinit().  Direct access to other MPOOL functionality is
not appropriate for the Java environment.

The Java runtime DOES NOT automatically close Db* objects on finalization,
whether they be Db, Dbc, DbTxn, etc.  There are a couple reasons for
this.  One is that finalization is generally run only when GC occurs and
there is no guarantee that this occurs at all (even on exit).  Allowing
specific DB actions to occur in ways that cannot be replicated seems
wrong.  Secondly, finalization of objects may happen in an arbitrary
order, so we would have to do a lot of extra bookkeeping to make sure
everything got closed in the proper order.  The best word of advice is to
always do a close() for any matching open() call or equivalent.

DbEnv.appinit() always turns on the DB_THREAD flag since threads are
commonly used in Java.