+I<Berkeley DB Reference Guide: Programmer Notes[P6

Berkeley DB Reference Guide: Programmer Notes



,

Java Programming Notes



LThe Java API closely parallels the Berkeley DB C++ interface, and to a greatPdegree, the Berkeley DB C interface. If you are currently using either of thoseGAPIs, there will be very little to surprise you in the Java API. We'veGeven taken great care to make the names of classes, constants, methods,Eand even method arguments identical, where possible, across all threeAPIs.

GIf there are embedded null strings in the db_config argument forsDbEnv.appinit they will be treated as the end of the list of configHstrings, even though you may have allocated a longer array. Fill in allGthe strings in your array unless you intend to cut it short. This samefcomment applies to the curslist argument for Db.join.

uThe callback installed for DbEnv.set_errcall will run in the sameuthread as the caller to DbEnv.set_errcall. Make sure that threadpremains running until your application exits or DbEnv.appexit iscalled.

GThe Berkeley 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. YourCdatabase activity may not be synchronized to disk unless you do so.

uThe DbMpool class has a small subset of the corresponding Berkeley DBBC++ functionality. This has been provided to allow you to performpcertain administrative actions on underlying DbMpool opened as aťconsequence of DbEnv.appinit. Direct access to other DbMpool:functionality is not appropriate for the Java environment.

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

@Berkeley DB always turns on the DB_THREAD flag since threads areexpected in Java.

IMany methods in the API often have no return type, and throw an exceptionIwhen an severe error arises. There are some notable methods that do haveea return value, and can also throw an exception. Db.get andcDbc.get both return 0 when a get succeeds, Db.DB_NOTFOUNDDwhen the key is not found, and throw an error when there is a severeJerror. There are others. This allows the programmer to check for typicalCdata driven errors by watching return values without specialcasing exceptions.

MAN˙˙