- Berkeley DB Reference Guide:
- Programmer Notes
|
|
The Java API closely parallels the Berkeley DB C++ interface, and to a great degree, the Berkeley DB C interface. 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.
If there are embedded null strings in the db_config argument for DbEnv.open, 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. This same comment applies to the curslist argument for Db.join.
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.
The Berkeley DB package requires that you explicitly call close on each individual Db and Dbc object that you obtained. Your database activity may not be synchronized to disk unless you do so.
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.
The Java runtime does not automatically close 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.
Berkeley DB always turns on the Db.DB_THREAD flag since threads are expected in Java.
Many methods in the API often 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. There are others. This allows the programmer to check for typical data driven errors by watching return values without special casing exceptions. 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 DbMemoryException is thrown when the system cannot provide enough memory to complete the operation (ENOMEM on UNIX). See the JAVA API interface documentation for specific details.
An object of type DbDeadlockException is thrown when a deadlock would occur. See the JAVA API interface documentation for specific details.
|
|