The XmlManager is a new object in 2.0. It is used as a factory object for many Berkeley DB XML objects, as well as providing context for operations such as queries. Some of the common operations on XmlManager are:

Many of the operations that were previously methods on XmlContainer are now methods on XmlManager.

The following is a comparison of 1.2.1 and 2.0 code to create an XmlContainer and insert a new document:

// Create a container, insert a document
// Do not use environment or transactions
//
// In 1.2.1
    XmlContainer container(0, "test.dbxml");
    container.open(0, DB_CREATE|DB_EXCL, 0);
    XmlDocument doc;
    doc.setContent("<root>newdoc</root>");
    container.putDocument(0, doc, 0);
    container.close(0);
//
// In 2.0
    XmlManager mgr;
    XmlContainer container = mgr.createContainer("test.dbxml");
    // createContainer and openContainer return opened containers
    XmlUpdateContext uc = mgr.createUpdateContext();
    container.putDocument("doc1", "<root>newdoc</root>", uc);
    // container and manager are closed when objects go out of scope

The points to notice are:

In the 1.2.X API, the XmlContainer constructor takes a DbEnv * parameter which is used if a DbEnv is required. In 2.0, the DbEnv (Berkeley DB environment) is associated with the XmlManager object. In 1.2.X, the DbEnv, if provided, is managed externally to Berkeley DB XML. In 2.0, there is an option of passing the flag, DBXML_ADOPT_DBENV. If the DbEnv is adopted, it is owned by the XmlManager object, and is closed when the XmlManager destructor runs:

DbEnv *env = new DbEnv(0);
env->open("path", DB_INIT_MPOOL|DB_CREATE, 0);
XmlManager mgr(env, DBXML_ADOPT_DBENV);
// XmlManager will close and delete the DbEnv
// object when it goes out of scope 

The addition of the XmlManager object and the introduction of the XQuery query language to 2.0 change the way that queries are performed in two ways:

The following code compares a simple query in 1.2.X and 2.0:

// Assume an open container and XmlManager
// Assume container name is "test.dbxml"       
// Do not use environment or transactions
//
// In 1.2.1
       XmlResults results(container.queryWithXPath(0, "/vendor", 0));
       XmlValue value;
       while (results.next(value)) {
           // do something
       }      
//
// In 2.0
       // XmlQueryContext is required
       XmlQueryContext qc = mgr.createQueryContext();
       XmlResults results = 
            mgr.query("collection('test.dbxml')/vendor", qc);
       XmlValue value;
       while (results.next(value)) {
           // do something
       } 

The points to notice are:

2.0 introduces a new object, XmlTransaction, which is used to wrap the Berkeley DB DbTxn object, and aids in internal transaction management. Rather than using an optional DbTxn * argument to a single interface, 2.0 defines 2 separate interfaces for each operation that may be transacted. One takes an XmlTransaction & argument, and the other does not. The following code compares 1.2.X and 2.0 code that performs a simple, transacted operation:

// Create a container, insert a document
// Use environment and transactions
// Assume DbEnv* has been constructed as dbEnv;
//
// In 1.2.1
       DbEnv *dbEnv;
       ...
       XmlContainer container(dbEnv, "test.dbxml");
       DbTxn *txn;
       dbEnv->txn_begin(0, &txn, 0);
       container.open(txn, DB_CREATE|DB_EXCL, 0);
       txn->commit(0);
       // new transaction for insert
       DbTxn *txn1;
       dbEnv->txn_begin(0, &txn1, 0);
       XmlDocument doc;
       doc.setContent("<root>newdoc</root>");
       container.putDocument(txn1, doc, 0);
       txn1->commit(0);
       ...
       container.close(0);
       dbEnv->close(0);
//
// In 2.0
       DbEnv *dbEnv;
       ...
       XmlManager mgr(dbEnv, DBXML_ADOPT_DBENV); // adopt env
       // create a transacted container
       XmlContainer container =
              mgr.createContainer("test.dbxml", DBXML_TRANSACTIONAL);
       XmlTransaction txn = mgr.createTransaction();
       // createContainer and openContainer return opened containers
       XmlUpdateContext uc = mgr.createUpdateContext();
       container.putDocument(txn, "doc1", "<root>newdoc</root>", uc);
       txn.commit(); 

The points to notice are:

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.

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

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.

Migrating data is best thought about in terms of what information is needed to load into 2.0. A load comprises the following operations:

The remaining task is thinking about how to dump a 1.2.X container such that the information above is available: