From ec6ae091617bdfdca9e65e8d3e65b950d234f676 Mon Sep 17 00:00:00 2001 From: unknown Date: Sun, 4 Mar 2001 19:42:05 -0500 Subject: Import changeset --- bdb/docs/ref/java/compat.html | 34 ++++++++++++++++++ bdb/docs/ref/java/conf.html | 82 ++++++++++++++++++++++++++++++++++++++++++ bdb/docs/ref/java/faq.html | 31 ++++++++++++++++ bdb/docs/ref/java/program.html | 72 +++++++++++++++++++++++++++++++++++++ 4 files changed, 219 insertions(+) create mode 100644 bdb/docs/ref/java/compat.html create mode 100644 bdb/docs/ref/java/conf.html create mode 100644 bdb/docs/ref/java/faq.html create mode 100644 bdb/docs/ref/java/program.html (limited to 'bdb/docs/ref/java') diff --git a/bdb/docs/ref/java/compat.html b/bdb/docs/ref/java/compat.html new file mode 100644 index 00000000000..4619ec55794 --- /dev/null +++ b/bdb/docs/ref/java/compat.html @@ -0,0 +1,34 @@ + + + + + +Berkeley DB Reference Guide: Compatibility + + + + + + + +

Berkeley DB Reference Guide:
Java API

PrevRefNext +
+

+

Compatibility

+

The Berkeley DB Java API has been tested with the +Sun Microsystems JDK 1.1.3 on SunOS +5.5, and Sun's JDK 1.1.7, JDK 1.2.2 and JDK 1.3.0 on Linux and +Windows/NT. It should work with any JDK 1.1, 1.2 or 1.3 (the latter +two are known as Java 2) compatible environment. IBM's VM 1.3.0 has +also been tested on Linux. +

The primary requirement of the Berkeley DB Java API is that the target Java +environment supports JNI (Java Native Interface), rather than another +method for allowing native C/C++ code to interface to Java. The JNI was +new in JDK 1.1, but is the most likely interface to be implemented across +multiple platforms. However, using the JNI means that Berkeley DB will not be +compatible with Microsoft Visual J++. +

PrevRefNext +
+

Copyright Sleepycat Software + + diff --git a/bdb/docs/ref/java/conf.html b/bdb/docs/ref/java/conf.html new file mode 100644 index 00000000000..b7eedcaedba --- /dev/null +++ b/bdb/docs/ref/java/conf.html @@ -0,0 +1,82 @@ + + + + + +Berkeley DB Reference Guide: Configuration + + + + + + + +

Berkeley DB Reference Guide:
Java API

PrevRefNext +
+

+

Configuration

+

Building the Berkeley DB java classes, the examples and the native support +library is integrated into the normal build process. See +Configuring +Berkeley DB and Building for Windows +for more information. +

We expect that you've already installed the Java JDK or equivalent on +your system. For the sake of discussion, we'll assume it is 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. +

For your application to use Berkeley DB successfully, you must set your +CLASSPATH environment variable to include db-VERSION/java/classes as +well as the classes in your java distribution. On UNIX, CLASSPATH is +a colon separated list of directories; on Windows it is separated by +semicolons. Alternatively, you can set your CLASSPATH to include +db-VERSION/java/classes/db.jar which is created as a result of the +build. The db.jar file contains the classes in com.sleepycat.db, it +does not contain any classes in com.sleepycat.examples. +

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

db-VERSION\build_win32\Release
+

On UNIX, you will want to set the LD_LIBRARY_PATH environment variable +to include the Berkeley DB library installation directory. Of course, the +standard install directory may have been changed for your site, see your +system administrator for details. Regardless, if you get a: +

java.lang.UnsatisfiedLinkError
+

exception when you run, chances are you do not have the library search +path configured correctly. Different Java interpreters provide +different error messages if the CLASSPATH value is incorrect, a typical +error is: +

java.lang.NoClassDefFoundError
+

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
+

For example, the sample program: +

% java com.sleepycat.examples.AccessExample
+

will prompt for text input lines which are then stored in a Btree +database named "access.db" in your current directory. Try giving it a +few lines of input text and then end-of-file. Before it exits, you +should see a list of the lines you entered display with data items. +This is a simple check to make sure the fundamental configuration is +working correctly. +

PrevRefNext +
+

Copyright Sleepycat Software + + diff --git a/bdb/docs/ref/java/faq.html b/bdb/docs/ref/java/faq.html new file mode 100644 index 00000000000..75b9e9f3bdb --- /dev/null +++ b/bdb/docs/ref/java/faq.html @@ -0,0 +1,31 @@ + + + + + +Berkeley DB Reference Guide: Frequently Asked Questions + + + + + + + +

Berkeley DB Reference Guide:
Java API

PrevRefNext +
+

+

Frequently Asked Questions

+

    +

  1. During one of the first calls to the Berkeley DB Java API, a +DbException is thrown with a "Bad file number" or "Bad file descriptor" +message. +

    There are known large-file support bugs under JNI in various releases +of the JDK. Please upgrade to the latest release of the JDK, and, if +that does not help, disable big file support using the --disable-bigfile +configuration option. +

+

PrevRefNext +
+

Copyright Sleepycat Software + + diff --git a/bdb/docs/ref/java/program.html b/bdb/docs/ref/java/program.html new file mode 100644 index 00000000000..c454a0910ee --- /dev/null +++ b/bdb/docs/ref/java/program.html @@ -0,0 +1,72 @@ + + + + + +Berkeley DB Reference Guide: Java Programming Notes + + + + + + +

Berkeley DB Reference Guide:
Programmer Notes

PrevRefNext +
+

+

Java Programming Notes

+

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

    +

  1. The Java runtime does not automatically close Berkeley DB objects on +finalization. There are a couple reasons for this. One is that +finalization is generally run only when garbage collection occurs and +there is no guarantee that this occurs at all, even on exit. Allowing +specific Berkeley 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 extra bookkeeping to make sure everything +was closed in the proper order. The best word of advice is to always +do a close() for any matching open() call. Specifically, the Berkeley DB +package requires that you explicitly call close on each individual +Db and Dbc object that you opened. Your database +activity may not be synchronized to disk unless you do so. +

  2. Some methods in the Java API have no return type, and throw a +DbException when an severe error arises. There are some notable +methods that do have a return value, and can also throw an exception. +Db.get and Dbc.get both return 0 when a get succeeds, +Db.DB_NOTFOUND when the key is not found, and throw an error when +there is a severe error. This approach allows the programmer to check +for typical data driven errors by watching return values without special +casing exceptions. +

    An object of type DbDeadlockException is thrown when a deadlock +would occur. +

    An object of type DbMemoryException is thrown when the system +cannot provide enough memory to complete the operation (the ENOMEM +system error on UNIX). +

    An object of type DbRunRecoveryException, a subclass of +DbException, is thrown when there is an error that requires a +recovery of the database, using db_recover. +

  3. There is no class corresponding to the C++ DbMpoolFile class in the Berkeley DB +Java API. There is a subset of the memp_XXX methods in the DbEnv +class. This has been provided to allow you to perform certain +administrative actions on underlying memory pools opened as a consequence +of DbEnv.open. Direct access to other memory pool functionality +is not appropriate for the Java environment. +

  4. Berkeley DB always turns on the Db.DB_THREAD flag since threads +are expected in Java. +

  5. If there are embedded null strings in the curslist argument for +Db.join, they will be treated as the end of the list of +cursors, even though you may have allocated a longer array. Fill in +all the strings in your array unless you intend to cut it short. +

  6. 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.close is +called. +
+

PrevRefNext +
+

Copyright Sleepycat Software + + -- cgit v1.2.1