XML Database API Draft Proposal

API Use Cases

The XML:DB API Use Cases attempt to outline the most common usage scenarios for the API and provide solutions to those scenarios. The solutions are written in a language that is basically Java but without the surrounding class context or error handling. These solutions are very similar to the source IDL but it is necessary to use a concrete programming language to show proper type handling.

All Use Cases assume the following preamble code. The scenario is simple access to a database from Vendor X. The database contains a collection of documents containing movie descriptions.


	// Get a reference to the movies Collection String collectionURI = "xmldb:vendorx://db.xmlmovies.com:2030/movies"; Collection collection = DatabaseManager.getCollection(collectionURI, null);

Complete Example Program

Most of the use cases here are small snippits of a program so it might not be entirely clear what an XML:DB API program would look like. To clarify things, this example is a fully functioning Java program that simply needs a proper XML:DB Database implementation to work. This program will query the database using XPath looking for movies that have a title attribute of "Music Man". It then simply prints the results to the screen.

One thing in particular to note about this example is the finally clause that closes the collection. This is not apparent in the other use cases and for many Database implementations it is an essential step to insure that resources are managed properly.

Required Modules

Core Level 1

Solution

 
package examples;

import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
import org.xmldb.api.*;

/**
 * Simple XML:DB API example to query the database.
 */
public class Example1 {
   public static void main(String[] args) throws Exception {
      Collection col = null;
      try {
         String driver = "org.vendorx.xmldb.DatabaseImpl";
         Class c = Class.forName(driver);
         
         Database database = (Database) c.newInstance();
         DatabaseManager.registerDatabase(database);
         col =
            DatabaseManager.getCollection("xmldb:vendorx://db.xmlmovies.com:2030/movies");
   
         String xpath = "//movie[@title='Music Man']";
         XPathQueryService service =
            (XPathQueryService) col.getService("XPathQueryService", "1.0");
         ResourceSet resultSet = service.query(xpath);
         
         ResourceIterator results = resultSet.getIterator();
         while (results.hasMoreResources()) {
            Resource res = results.nextResource();
            System.out.println((String) res.getContent());
         }
      }
      catch (XMLDBException e) {
         System.err.println("XML:DB Exception occured " + e.errorCode);
      }
      finally {
         if (col != null) {
            col.close();
         }
      }
   }
}

DOM Document Retrieval

Retrieve a document from the database using a known ID. We want to work with the result as a DOM Document object.

Required Modules

Core Level 0

Solution


	String id = "gladiator-2000"; XMLResource resource = (XMLResource) collection.getResource(id); Document doc = (Document) resource.getContentAsDOM();

Test XML Document Retrieval

Retrieve a document from the database using a known ID. We want to work with the result as text XML.

Required Modules

Core Level 0

Solution


	String id = "gladiator-2000"; XMLResource resource = (XMLResource) collection.getResource(id); String doc = (String) resource.getContent();

SAX Document Retrieval

Retrieve a document from the database using a known ID. We want to use a SAX content handler to handle the document.

Required Modules

Core Level 0

Solution

 
String id = "gladiator-2000";
XMLResource resource = 
   (XMLResource) collection.getResource(id);

// A custom SAX Content Handler is required to handle the SAX events
ContentHandler handler = new MyContentHandler();

resource.getContentAsSAX(handle);

Binary Content Retrieval

Retrieve a binary BLOB from the database. The blob is identified with a known ID. The database will need to determine the data is binary and return to you the proper Resource type.

Required Modules

Core Level 0, BinaryResource

Solution

 
String id = "gladiator-2000-img";
BinaryResource resource = 
   (BinaryResource) collection.getResource(id);

// Return value of getContent must be defined in the specific language mapping
// for the language used. For Java this is a byte array.
byte[] img = (byte[]) resource.getContent();

Retrieving a DOM Node

Retrieve a document from the database using a known ID. We want to work with the result as a DOM Node object.

Required Modules

Core Level 0

Solution


	String id = "gladiator-2000"; XMLResource resource = (XMLResource) collection.getResource(id); Node node = (Node) resource.getContentAsDOM();

Inserting a DOM Document

Store a new DOM document in the database using a known ID.

Required Modules

Core Level 0

Solution

 
// Document is assumed to be a valid DOM document. Where this comes from is
// outside the scope of the API
Document document;

String id = "gladiator-2000";
XMLResource resource = 
   (XMLResource) collection.createResource(id, XMLResource.RESOURCE_TYPE);

resource.setContentAsDOM(document);
collection.storeResource(resource);

Inserting a SAX Document

Use a SAX ContentHandler to store a new document in the database using a known ID.

Required Modules

Core Level 0

Solution

 
// File containing the XML to be inserted
String fileName = "gladiator-2000.xml";

String id = "gladiator-2000";
XMLResource resource = 
   (XMLResource) collection.createResource(id, XMLResource.RESOURCE_TYPE);

ContentHandler handler = resource.setContentAsSax();

XMLReader reader = XMLReaderFactory.createXMLReader();
reader.setContentHandler(handler);
reader.parse(new InputSource(fileName));

collection.storeResource(resource);

Inserting a Text XML Document

Store a new text XML document in the database using a known ID.

Required Modules

Core Level 0

Solution


// document is assumed to be a valid XML document. Where this comes from is
// outside the scope of the API
String document;

String id = "gladiator-2000";
XMLResource resource = 
   (XMLResource) collection.createResource(id, XMLResource.RESOURCE_TYPE);

resource.setContent(document);
collection.storeResource(resource);

Deleting a Resource

Remove an existing Resource from the database using a known ID.

Required Modules

Core Level 0

Solution


	String id = "gladiator-2000"; collection.removeResource(collection.getResource(id));

Updating a DOM Document

Update an existing DOM document stored in the database.

Required Modules

Core Level 0

Solution

 
String id = "gladiator-2000";
XMLResource resource = 
   (XMLResource) collection.getResource(id);

Document document = (Document) resource.getContentAsDOM();

// Change document ...

resource.setContent(document);
collection.storeResource(resource);

Updating a Document using SAX

Not sure how to do this.

Required Modules

Core Level 0

Solution

Updating a Text XML Document

Update an existing Text XML document stored in the database.

Required Modules

Core Level 0

Solution

 
String id = "gladiator-2000";
XMLResource resource = 
   (XMLResource) collection.getResource(id);

String document = (String) resource.getContent();

// Change document ...

resource.setContent(document);
collection.storeResource(resource);

Searching with XPath

Search the collection for all movies with the title Gladiator. We want to work with the results as DOM Nodes.

Required Modules

Core Level 1

Solution

 
String xpath = "/movie/title='Gladiator'";

XPathQueryService service =
   (XPathQueryService) collection.getService("XPathQueryService", "1.0");

ResourceSet resultSet = service.query(xpath);

ResourceIterator results = resultSet.getIterator();
while (results.hasMoreResources()) {
   XMLResource resource = 
      (XMLResource) results.nextResource();
   Node result = resource.getContentAsDOM();
}

Transactional Inserting of DOM Documents

Insert multiple DOM documents under the control of a transaction.

The current IDL for the TransactionService is more of a stub then anything. We should probably reuse an existing transaction API if possible.

Required Modules

Core Level 0, TransactionService

Solution

 
// Documents are assumed to be valid DOM documents. Where this comes from is
// outside the scope of the API
Document document1;
Document document2;

String id1 = "gladiator-2000";
String id2 = "gonein60seconds-2000";

TransactionService transaction = 
   (TransactionService) collection.getService("TransactionService", "1.0");

transaction.begin();   

XMLResource resource1 = 
   (XMLResource) collection.createResource(id1, XMLResource.RESOURCE_TYPE);

resource1.setContentAsDOM(document1);
collection.storeResource(resource1);

XMLResource resource2 = 
   (XMLResource) collection.createResource(id2, XMLResource.RESOURCE_TYPE);

resource2.setContentAsDOM(document2);
collection.storeResource(resource2);

transaction.commit();