Berkeley DB Reference Guide: Java API

Java programming notes

Although the Java API parallels the Berkeley DB C++/C interface in many ways, it differs where the Java language requires. For example, the handle method names are camel-cased and conform to Java naming patterns. (The C++/C method names are currently provided, but are deprecated.)

1. The Java runtime does not automatically close Berkeley DB objects on finalization. There are several 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. Second, finalization of objects may happen in an arbitrary order, so we would have to do extra bookkeeping to make sure that 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, return 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.

   An object of type IllegalArgumentException a standard Java Language exception, is thrown when there is an error in method arguments.

3. Berkeley DB always turns on the Db.DB_THREAD flag because threads are expected in Java.

4. Callbacks in Java manufacture Dbt objects from internal data. For efficiency, the data field in such Dbts is not set in the Java object until a Dbt.getData method call. This avoids the creation of a potentially large Java byte array if it isn't needed. If callback code can be written to defer calling Dbt.getData performance may be increased. For example, a bt_compare method might compare values returned by Dbt.getSize before deciding whether a call to Dbt.getData is needed.

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 if 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.setErrorHandler will run in the same thread as the caller to DbEnv.setErrorHandler . Make sure that thread remains running until your application exits or until DbEnv.close is called.

7. If you are using custom class loaders in your application, make sure that the Berkeley DB classes are loaded by the system class loader, not a custom class loader. This is due to a JVM bug that can cause an access violation during finalization (see the bug 4238486 in Sun Microsystem's Java Bug Database).

Copyright (c) 1996-2003 Sleepycat Software, Inc. - All rights reserved.