зеркало из https://github.com/mozilla/gecko-dev.git
230 строки
9.0 KiB
Plaintext
230 строки
9.0 KiB
Plaintext
# @(#)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.
|