Berkeley DB XML Reference Guide: Migrating Berkeley DB XML C++ Applications

Berkeley DB XML Reference Guide:
Upgrading Berkeley DB XML Applications

Migrating Berkeley DB XML C++ Applications

XmlManager

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:

XmlManager::createContainer()
XmlManager::openContainer()
XmlManager::createTransaction()
XmlManager::query()

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

XmlContainer Management

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:

XmlManager is a factory object
2.0 requires an XmlUpdateContext object for all modifications. This was happening under the covers in 1.2.X.
2.0 does not require creation of an XmlDocument object in order to insert content. It is still an option.
2.0 no longer exposes numeric document IDs. It requires names for documents, and the names must be unique within a container. The flag, DBXML_GEN_NAME, can be used to tell the system to generate a unique name if names are not important to an application.
Valid XmlContainer objects are implicitly opened when created.
Object scoping is used for automatic cleanup and exception safety. Internally, the 2.0 XmlManager and XmlContainer objects are reference counted, and closed upon release of last reference.
XmlManager has an openContainer() method that must be used to open existing containers. It can also be used to create new containers.

XmlManager and Berkeley DB DbEnv

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

Queries

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:

Query language is XQuery, and no longer XPath 1.0. Most XPath 1.0 queries are valid in XQuery, usually with the addition of additional required syntax in XQuery.
The Query context for 2.0 is the XmlManager object, and not constrained to a specific XmlContainer. A single XQuery can reference more than one container, and even reference specific documents, by name.

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:

XmlQueryContext is required in 2.0. In 1.2.X, it was created under the covers if it was defaulted.
The 2.0 query requires the string "collection('test.dbxml')" to point to a specific container. There are a number of ways to control query context in 2.0, both in the XQuery expression itself, and through the query interfaces.

Transactions

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:

2.0 adds a DBXML_TRANSACTIONAL flag that can be passed to createContainer() and openContainer() to avoid the necessity of creating and committing a transaction for this purpose.
The DBXML_ADOPT_DBENV flag simplifies cleanup in 2.0.
The use of XmlTransaction and XmlManager::createTransaction() allows an application to ignore DB objects for most operations.
There is an XmlManager::createTransaction() method that takes a DbTxn * argument, allowing a DbTxn to be wrapped.