XML:DB Home

Index
Requirements
Working Draft
API Use Cases

Mail List
Mail Archive
Authors
Members of the XML:DB API Mailing List - xapi-dev@xmldb.org
Kimbro Staken (Editor) - kstaken@dbxmlgroup.com
Status
Working Draft (Experimental) - 2001-03-16
Notice
This is a XML:DB Working Draft for review by all interested parties. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Working Drafts as reference material or to cite them as other than "work in progress". This work is part of the XML:DB Project. Comments on this specification should be sent to XML:DB API mailing list xapi-dev@xmldb.org.
Abstract
This document defines a draft specification for the XML Database API. This API is being developed through the mailing lists of the XML:DB organization and the contents are attributed to the members of those lists.

Table of Contents


1 API Use Cases
    1.1 DOM Document Retrieval
        1.1.1 Required Modules
        1.1.2 Solution
    1.2 Test XML Document Retrieval
        1.2.1 Required Modules
        1.2.2 Solution
    1.3 SAX Document Retrieval
        1.3.1 Required Modules
        1.3.2 Solution
    1.4 Binary Content Retrieval
        1.4.1 Required Modules
        1.4.2 Solution
    1.5 Retrieving a DOM Node
        1.5.1 Required Modules
        1.5.2 Solution
    1.6 Inserting a DOM Document
        1.6.1 Required Modules
        1.6.2 Solution
    1.7 Inserting a SAX Document
        1.7.1 Required Modules
        1.7.2 Solution
    1.8 Inserting a Text XML Document
        1.8.1 Required Modules
        1.8.2 Solution
    1.9 Deleting a Resource
        1.9.1 Required Modules
        1.9.2 Solution
    1.10 Updating a DOM Document
        1.10.1 Required Modules
        1.10.2 Solution
    1.11 Updating a Document using SAX
        1.11.1 Required Modules
        1.11.2 Solution
    1.12 Updating a Text XML Document
        1.12.1 Required Modules
        1.12.2 Solution
    1.13 Searching with XPath
        1.13.1 Required Modules
        1.13.2 Solution
    1.14 Transactional Inserting of DOM Documents
        1.14.1 Required Modules
        1.14.2 Solution

Appendices



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);
         
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 1


Solution

 
collection.setProperty("ResourceType", "DOMNode");

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

Document doc = (Document) resource.getContent();
               


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

 
collection.setProperty("ResourceType", "TextXML");

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 1


Solution

 
collection.setProperty("ResourceType", "SAX");

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

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

resource.setContentHandler(handler);
resource.getContent();
               


Binary Content Retrieval

Retrieve a binary BLOB from the database. The blob is identified with a known ID.

Required Modules

Core Level 0, BinaryResource


Solution

 
collection.setProperty("ResourceType", "Binary");

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 InputStream.
InputStream img = (InputStream) 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 1


Solution

 
collection.setProperty("ResourceType", "DOMNode");

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

Node node = (Node) resource.getContent();
               


Inserting a DOM Document

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

Required Modules

Core Level 1


Solution

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

collection.setProperty("ResourceType", "DOMNode");

String id = "gladiator-2000";
DOMNodeResource resource = 
   (DOMNodeResource) collection.createResource(id);

resource.setContent(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 1


Solution

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

collection.setProperty("ResourceType", "SAX");

String id = "gladiator-2000";
SAXResource resource = 
   (SAXResource) collection.createResource(id);

ContentHandler handler = resource.getContentHandler();

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;

collection.setProperty("ResourceType", "TextXML");

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

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 1


Solution

 
collection.setProperty("ResourceType", "DOMNode");

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

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

// Change document ...

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


Updating a Document using SAX

NoteNot sure how to do this.

Required Modules

Core Level 1




Updating a Text XML Document

Update an existing Text XML document stored in the database.

Required Modules

Core Level 0


Solution

 
collection.setProperty("ResourceType", "TextXML");

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'";

collection.setProperty("ResourceType", "DOMNode");

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

ResourceIterator results = service.query(xpath);
while (results.hasMoreResources()) {
   DOMNodeResource resource = 
      (DOMNodeResource) results.nextResource();
   Node result = (Node) resource.getContent();
}
               


Transactional Inserting of DOM Documents

Insert multiple DOM documents under the control of a transaction.

NoteThe 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 1, 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;

collection.setProperty("ResourceType", "DOMNode");

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

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

transaction.begin();   

DOMNodeResource resource1 = 
   (DOMNodeResource) collection.createResource(id1);

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

DOMNodeResource resource2 = 
   (DOMNodeResource) collection.createResource(id2);

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

transaction.commit();
               




Copyright © 2000,2001 The XML:DB Initiative. All Rights Reserved.