Berkeley DB XML Reference Guide: Migrating Berkeley DB XML Java Applications

Berkeley DB XML Reference Guide:
Upgrading Berkeley DB XML Applications

Migrating Berkeley DB XML Java Applications

The Java interface to Berkeley DB XML is similar to the C++ interface in spirit. In addition to the changes to the interface due to functional changes in Berkeley DB XML, the Java interface has changed to be more compatible with the Berkeley DB Java interface.

XmlManager and Environment

The Berkeley DB Java interface replaces the DbEnv object with an Environment object. It also replaces the DbTxn object with Transaction. The interface also replaces the use of integer flags with configuration objects. Berkeley DB XML has adopted this mechanism as well.

Configuration Object

There are 3 new configuration objects in Berkeley DB XML, replacing corresponding use of flags:

XmlManagerConfig: use this object to configure a new XmlManager object.
XmlContainerConfig: use this object to configure XmlContainer objects. A default XmlContainerConfig object can be set on an XmlManager object that affects all containers it creates and opens. This object extends DatabaseConfig, and inherits state, such as encryption, read isolation level, threading configuration, and read-only.
XmlDocumentConfig: use this object to configure XmlDocument-level state, such as DBXML_LAZY_DOCS or DBXML_GEN_NAME (C++ flags).

Delete, GC and Object Life Cycle

Because Java objects in Berkeley DB XML are wrappers for native (C++) objects, the Java VM is not aware of memory consumed by the native objects. Therefore, GC on objects may not happen in a timely manner, if at all. This can result in out of memory conditions, outside of the Java VM control.

For this reason, it is necessary to explicitly delete most Berkeley DB XML Java objects when they are not longer required. This is especially true for the XmlResult, XmlValue, and XmlDocument objects, of which there can be many. All of the objects include delete() methods for this purpose.