SiXDML API Draft

Authors

Dare Obasanjo - kpako@yahoo.com

Status

Working Draft - 2002-06-23

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 SiXDML mailing list sixdml-dev@xmldb.org.

Abstract

XML has become a popular data interchange and storage format which in recent times has precipitated the rise of XML-enabled relational databases as well as native XML databases. In the relational database world there exist programming APIs as well as a single language that provides a single point from which to perform data definition, manipulation and management tasks within the database management system. Unfortunately nothing analogous to such a language (SQL) or such APIs(ODBC, JDBC, etc) exist for XML databases. This document describes an application programming interface that allows programmers to perform the aforementioned data management and data manipulation tasks in XML database applications.

Table of Contents

Appendices

Introduction

The XML:DB API was the first major attempt to create a common application programming interface amongst XML database products. The XML:DB was designed early in the evolution of the XML database sector and thus does not cover a number of areas of functionality that have become common amongst XML database products such as support for schemas and indexing of data. Also the XML:DB API was designed with some inherrent assumptions about the kind of operations that users would require from XML databases which may have been unwise. Chief amongst these are

the lack of an exception hierarchy meaning that users of the API have to resort to checking error codes when exceptions occur.
the fact that the results of a database query are assumed to be objects that implement the Resource interface which implies that the results of any XPath query against the database (be it string, number, boolean, or nodeset) can be stored in the database.

no real support for interacting with the results of a query if it isn't a nodeset or tree fragment.

the tying of services to collections.
This design is particularly irksome because it means that before one can start a transaction, manage collections, or perform a query that an unnecessary method call must be made to retrieve an arbitrary collection then the requested service retrieved from the specified collection. Since most (if not all) XML database products do not restrict a service to the context of a particular collection such as creating a transaction or query that is specific to only one collection, there is very little justification for the extra hoops one has to go through to utilize services.

Despite the aforementioned shortcomings, the XML:DB API has several desirable aspects as an attempt at a generic API for XML database systems. Since most of these shortcomings manifest themselves in the Core Level 1 conformance level of the XML:DB API, the SiXDML API is an implementation of the Core Level 0 compliance level of the XML:DB API. Any implementation of the SiXDML API is automatically a Core Level 0 XML:DB API as well. For instance, the prototype implementation of SiXDML that works over the eXcelon corporation's native XML database product is also a Core Level 0 implementation of the XML:DB API for eXcelon.

Modules

The SiXDML API is a set of interfaces for interacting with XML databases that are described in Java programming language. The API is split into three major divisions; Core, Object Model and Direct Execution. The Core module describes classes that are used to handle fundamental aspects of interacting with the database such as connections and transactions. The Object Model module describes classes that provide a rich object oriented framework for interacting with the database with the same degree of functionality as exists in the SiXDML language. The Direct Execution API is similar to database interaction APIs like JDBC, ODBC, ADO and Perl DBI which allow the user to directly execute commands agains the database.

The Core module are the aspect of the API that must exist in all SiXDML API implementations. Conformant SiXDML implementations can then decide to implement the Object Model module, Direct Execution module or both.

Future work will be done to describe these interfaces in other programming languages including C++, Perl and C#.

Core

org.sixdml
This package contains interfaces that represent the core of the API including the interface that represents the database and constants that are used by the entire API.

SixdmlConstants - The SixdmlConstants interface contains constants that are utilized throughout the SiXDML API such as the version number and the SiXDML namespace URI.

SixdmlDatabase - A SixdmlDatabase interface is a representation of the database driver that provides access to the functionality of the XML database. It contains methods that allow one to determine the supported services and index types in the database, retrieve collections, services and documents as well as methods for identifying the database instance.

org.sixdml.exceptions
This package contains the SiXDML API exception hierarchy.

SixdmlException - The SixdmlExceptionis the base class of all Exceptions in the org.sixdml hierarchy.

Object Model

org.sixdml
This package contains concrete implementations of certain utility classes for manipulating XML documents stored in a databases.

SixdmlResourceSet - The SixdmlResourceSet class is an implementation of the XML:DB API's ResourceSet interface which defines a data structure that holds database resources like XML documents.

SixdmlResourceIterator - The SixdmlResourceIterator class is an implementation of the XML:DB API's ResourceIterator interface which defines an iterator over a ResourceSet.

SixdmlNamespaceMap - The SixdmlNamespaceMap class is a table that maps prefixes to namespace names for use in the XPath expressions used by SiXDML query and update operations.

org.sixdml.dbmanagement
This package contains interfaces and classes related to management of collection and indices.

SixdmlCollectionManagementService - The SixdmlCollectionManagementService interface is a representation of a service that allows one to create and delete collections.

SixdmlCollection - A SixdmlCollection interface is a representation of a collection of XML documents in an XML database. This interface gives one the ability to add and remove XML documents, indices, subcollections and a schema that belong to the collection.

SixdmlResource - A SixdmlResource is a representation of an XML document that can be stored in the database. It contains methods to set and retrieve the XML content of the document.

SixdmlIndex - The SixdmlIndex interface is an is a representation an XML database index.

SixdmlIndexType - The SixdmlIndexType class is used to represent type information about database indices.

SixdmlTransactionService - The SixdmlTransactionService interface is a representation of a service that allows one to begin, end or rollback database transactions.

org.sixdml.query
This package contains interfaces and classes related to performing XPath queries over the contents of the database.

SixdmlQueryService - The SixdmlQueryService interface is a representation of a service that allows one to execute XPath queries over SixdmlCollections and SixdmlResources.

SixdmlXpathObject - The SixdmlXpathObject interface is a representation of the results of an XPath query and contains methods to access these results as a string, boolean, number or nodeset where applicable.

SixdmlQueryResultsMap - The SixdmlQueryResultsMap class is a data structure that holds the SixdmlXpathObjects that result from an XPath query over a collection.

SixdmlXpathObjectType - The SixdmlXpathObjectType class is used to represent type information about the results of an XPath query..

org.sixdml.transform
This package contains interfaces and classes used for transforming XML data from one form to another such as via XSLT.

SixdmlTransformService - The SixdmlTransformService interface is a representation of a service that allows one to transform XML data either in a SixdmlResources or in a string.

SixdmlTransformType - The SixdmlTransformType class is used to represent type information about transforms.

org.sixdml.update
This package contains interfaces and packages related to updating the XML data in the database

SixdmlUpdateService - The SixdmlUpdateService interface is a representation of a service that allows one to update XML documents in the database.

org.sixdml.exceptions
This package contains the SiXDML API exception hierarchy.

DocumentAlreadyExistsException - The DocumentAlreadyExistsException is thrown when an attempt is made to add a document to a collection that has the same name as one that already exists in the collection.

IndexAlreadyExistsException - The IndexAlreadyExistsException is thrown when an attempt is made to add an index to a collection when one with the same name already exists in that collection.

InvalidCollectionDocumentException - The InvalidCollectionDocumentException is thrown when an XML document in a SixdmlCollection fails to be validate against a given schema that is being applied to the

InvalidQueryException - The InvalidQueryException is thrown when an attempt is made to query a collection or document with an invalid query.

InvalidSchemaException - The InvalidSchemaException is thrown when an attempt is made to constrain a collection with an invalid schema.

InvalidTransformException - The InvalidTransformException is thrown when an invalid transform document or query is used in a transformation attempt.

NonExistentDocumentException - The NonExistentDocumentException is thrown when an attempt is made to delete a document that does not exist.

NonExistentIndexException - The NonExistentIndexException is thrown when an attempt is made to delete an index that does not exist. an attempt is made to delete a

NonWellFormedXMLException - The NonWellFormedXMLException is thrown when an attempt is made to store a non-well formed XML fragment in the database.

UnsupportedIndexTypeException - The UnsupportedIndexTypeException is thrown when an attempt is made to add an index to a collection in a database that does not support that type of index.

UpdateTypeMismatchException - The UpdateTypeMismatchException is thrown when an update is done against a type that does not allow such updates.

Direct Execution

org.sixdml
This package contains interfaces for classes that enable the directly executing SiXDML statements over the database in the manner of traditional database access APIs like JDBC, ODBC and Perl DBI.

SixdmlStatementService - The SixdmlStatementService is a representation of a service that allows one to create SixdmlStatement and SixdmlPreparedStatement objects for use in querying the database.

SixdmlStatement - The SixdmlStatement interface is a representation of an object that enables one to execute SiXDML statements over the datavase.

SixdmlPreparedStatement - The SixdmlPreparedStatement interface is a representation of an object that enables one to precompile SiXDML queries for more efficient execution of repeated queries over the database.

Use Cases for Object Model

Besides the first example, the sample code shown are small snippets of a program.

Complete Sample Program


 import org.sixdml.excelon.*; 
 import org.sixdml.exceptions.*; 
 import org.sixdml.query.*; 
 import org.sixdml.update.*; 
 import org.sixdml.dbmanagement.*; 
 import org.sixdml.*; 
 import org.sixdml.transform.*; 

 import org.xmldb.api.*; 
 import org.xmldb.api.base.*; 
 import java.net.*; 

 class SixdmlTest{ 

     public static void main(String[] args) throws Exception{ 

         Collection col = null;
         try {

             String driver = "org.sixdml.excelon.xlnSixdmlDatabase";
             Class c = Class.forName(driver);

             SixdmlDatabase database = (SixdmlDatabase) c.newInstance(); 
             SixdmlTransactionService transaction = 
                 (SixdmlTransactionService) database.getService(
                     "SixdmlTransactionService", "1.0"); 

             transaction.begin(); 
             DatabaseManager.registerDatabase(database); 

             SixdmlCollectionManagementService colManager = 
                 (SixdmlCollectionManagementService) database.getService( 
                     "SixdmlCollectionManagementService", "1.0"); 

             col = DatabaseManager.getCollection("xmldb:sixdml:/auctiondata"); 

             System.out.println(col.getName());
             transaction.commit(); 

         } finally {
             if (col != null) 
                 col.close();
         }
	
     }
 }

Creating a collection I


 String id     = "bookstore"; 
 String id2    = "logfiles"; 
 String schema = "http://www.example.com/logfile_schema.xsd"; 

 SixdmlCollectionManagementService colManager = 
     (SixdmlCollectionManagementService) database.getService( 
         "SixdmlCollectionManagementService", "1.0"); 

 /* collection without a schema */
 SixdmlCollection col1 = (SixdmlCollection) colManager.createCollection(id); 

 /* collection with a schema */				
 SixdmlCollection col = (SixdmlCollection) colManager.createCollection(id2, 
     new java.net.URL(schema));

Obtaining the contents of a collection


 String id = "bookstore"; 

 SixdmlCollection col = (SixdmlCollection) database.getCollection(id, null, null); 

 if(col == null)
     throw new XMLDBException(0, "Cannot find collection named " + id); 

 String[] resources = col.listResources(); 
 if (resources.length == 0) {
     System.out.println("No XML documents in " + id);
 } else { 
     System.out.println("XML documents stored in " + id + " are: \n");

     for(int i=0; i &lt; resources.length; i++) {
         System.out.println(resources[i] + "\n"); 
     } //for
 } //else

 System.out.println("\n"); 

 String[] collections = col.listChildCollections(); 

 if (collections.length == 0) {
     System.out.println("No child collections located in " + id);
 } else { 
     System.out.println("Child collections of " + id + " are: \n");

     for (int i=0; i &lt; collections.length; i++) {
         System.out.println(collections[i] + "\n"); 
     } //for
 } //else

 System.out.println("\n\n");

Dropping a collection


 String id = "bookstore"; 

 SixdmlCollectionManagementService colManager = 
     (SixdmlCollectionManagementService) database.getService( 
         "SixdmlCollectionManagementService", "1.0");
			
 colManager.removeCollection(id);

Inserting a document into a collection


 String id       = "bookstore";
 String docURL   = "http://www.example.com/fantasy-books.xml"; 
 String docName1 = "books.xml"; 	

 /* get collection */
 SixdmlCollection col = 
     (SixdmlCollection) database.getCollection(id, null, null); 

 if (col == null)
     throw new XMLDBException(0, "Cannot find collection named " + id); 
		
 /* do insert from xml string */
 col.insertDocument(docName1, "<books><book>Thinking In Java</book></books>"); 

 /* do insert from URL */
 java.net.URL url = new URL(docURL.getText()); 
 int fileIndx = url.getFile().lastIndexOf('/') + 1; 
 docName2 = url.getFile().substring(fileIndx);
 col.insertDocument(docName2, url);

Deleting a document from a collection


 String id       = "bookstore";
 String docName  = "books.xml"; 	

 /* get collection */
 SixdmlCollection col = 
     (SixdmlCollection) database.getCollection(id, null, null);

 if (col == null)
     throw new XMLDBException(0,"Cannot find collection named " + id); 
		
 col.removeDocument(docName);

Specifying a schema for a collection


 String id         = "bookstore";
 String schemaURL  = "http://www.example.com/bookstore.xsd"; 	

 /* get collection */
 SixdmlCollection col = 
     (SixdmlCollection) database.getCollection(id, null, null);

 if (col == null)
     throw new XMLDBException(0, "Cannot find collection named " + id);  

 col.setSchema(new java.net.URL(schemaURL));

Deleting a schema on a collection


 String id         = "bookstore";

 /* get collection */
 SixdmlCollection col = 
     (SixdmlCollection) database.getCollection(id, null, null);
				
 if (col == null)
     throw new XMLDBException( 0, "Cannot find collection named " + id); 

 col.unsetSchema();

Obtaining the schema for a collection


 String id         = "bookstore";

 /* get collection */
 SixdmlCollection col = 
     (SixdmlCollection) database.getCollection(id, null, null);

 if (col == null)
     throw new XMLDBException(0, "Cannot find collection named " + id); 

 String schemaStr = col.showSchema(); 

 if (schemaStr == null) 
     System.out.println("No schema exists for " + id); 
 else
     System.out.println(schemaStr); 

 System.out.println("\n");

Creating an index on a collection


 /* 
   The following code is specific to the eXcelon implementation.
  */

 // create hashtable of index fields 
 HashMap fields = new HashMap(); 
 fields.put("indexKey", "/name"); 
 fields.put("indexElement", "/document/person"); 
 fields.put("type","" + XlnIndex.TEXT_INDEX); 
 fields.put("options", "" + XlnTextIndex.INDEX_SHALLOW);

 String idxName = "my-text-index";
 String id      = "employees";

 SixdmlCollection col = 
     (SixdmlCollection) database.getCollection(id, null, null);

 if (col == null)
     throw new XMLDBException(0, "Cannot find collection named " + id);  

 SixdmlCollectionManagementService colManager = 
    (SixdmlCollectionManagementService) database.getService("SixdmlCollectionManagementService", "1.0"); 
	    
 SixdmlIndex index = colManager.createIndex(idxName, fields);
 col.addIndex(index);

Deleting an index from a collection


 String idxName = "my-text-index";
 String id      = "employees";	

 SixdmlCollection col = 
     (SixdmlCollection) database.getCollection(id, null, null);

 if (col == null)
     throw new XMLDBException(0,"Cannot find collection named " + id); 

 col.removeIndex(idxName);

Obtaining the indices on a collection


 String id      = "employees";		

 SixdmlCollection col = 
     (SixdmlCollection) database.getCollection(id, null, null);

 if (col == null)
     throw new XMLDBException(0, "Cannot find collection named " + id); 

 SixdmlIndex[] indices = col.getIndices(); 

 if (indices.length == 0) {
     System.out.println("No indices in effect on " + id + "\n");
 } else { 
     System.out.println("Indices in effect on " + id + " are: \n");

     for (int i=0; i &lt; indices.length; i++) {
         System.out.println("name = " + indices[i].getName() + "\ntype = " + 
                            indices[i].getType() + 
                            "\nfields = " + indices[i].getIndexFields() + "\n\n"); 
     } //for
 } //else

Querying documents and collections


 String cid         = "bookstore";
 String did         = "books.xml";
 String qstring     = "//book[1]";	
 String interimResults; 

 SixdmlQueryService queryManager = 
     (SixdmlQueryService) database.getService("SixdmlQueryService", "1.0"); 

 /* query a document */
 SixdmlResource document = (SixdmlResource) database.getResource(did, null, null); 

 if (document == null)
     throw new XMLDBException(0, "Cannot find document named " + did);

 SixdmlXpathObject sxo = queryManager.executeQuery(qstring, document); 

 if (sxo.getType() == SixdmlXpathObject.NODESET)
     interimResults = sxo.getNodeSetAsXML(); 
 else
     interimResults = sxo.getObjectAsString(); 
	
 /* transform results of query */
 SixdmlTransformService transformer = 
     (SixdmlTransformService) database.getService("XsltTransformService", "1.0"); 

 java.net.URL transformURL = new URL("http://www.example.com/transform.xsl")
 String transformedXML =  
     transformer.transformAndReturnString(transformURL, interimResults);  

 System.out.println(transformedXML);

 /* query collection */
 SixdmlCollection collection = 
     (SixdmlCollection) database.getCollection(cid, null, null); 

 if (collection == null)
     throw new XMLDBException(0, "Cannot find collection named " + cid); 

 SixdmlQueryResultsMap sqrm = queryManager.executeQuery(qstring.trim(), collection); 

 System.out.println(sqrm.getXML());

Inserting nodes into documents and collections


 String cid         = "bookstore";
 String did         = "books.xml";
 String qstring     = "//book[1]";	

 /* inserting XML text into a collection (INSERT BEFORE) */

 SixdmlUpdateService updateManager = 
     (SixdmlUpdateService) database.getService("SixdmlUpdateService", "1.0"); 

 SixdmlCollection collection = 
     (SixdmlCollection) database.getCollection(cid, null, null); 

 if (collection == null)
     throw new XMLDBException(0, "Cannot find collection named " + cid);

 updateManager.insertSibling(qstring, "<book>Silence of the Lambs</book>",
                             collection, true);

 /* inserting XML text into a document (INSERT AT) */
 SixdmlResource document = (SixdmlResource) database.getResource(did, null, null); 

 if (document == null)
     throw new XMLDBException(0, "Cannot find document named " + did); 

 updateManager.insertChild(qstring, "<author>Thomas Harris</author>" ,document);

Inserting attributes in documents and collections


 String cid         = "bookstore";
 String did         = "books.xml";
 String qstring     = "//book[1]";	
 String name        = "genre"; 
 String value       = "thriller"
 String namespace   = "urn:bookstore-schema"

 /* inserting attribute w/out namespace into a collection */

 SixdmlUpdateService updateManager = 
     (SixdmlUpdateService) database.getService("SixdmlUpdateService", "1.0"); 

 SixdmlCollection collection = 
     (SixdmlCollection) database.getCollection(cid, null, null); 

 if (collection == null)
     throw new XMLDBException(0, "Cannot find collection named " + cid);

 updateManager.insertAttribute(qstring, collection, name, value);

 /* inserting attribute with namespace URI into a document */
	
 SixdmlResource document = (SixdmlResource) database.getResource(did, null, null); 

 if (document == null)
     throw new XMLDBException(0, "Cannot find document named " + did); 

 updateManager.insertAttribute(qstring, document, name, value, new URI(namespace));

Deleting nodes from documents and collections


 String cid         = "bookstore";
 String did         = "books.xml";
 String qstring     = "//book[1]";

 SixdmlUpdateService updateManager = 
     (SixdmlUpdateService) database.getService("SixdmlUpdateService", "1.0"); 

 /* delete first <book> in a document */
 SixdmlResource document = (SixdmlResource) database.getResource(did, null, null); 

 if(document == null)
     throw new XMLDBException(0, "Cannot find document named " + did); 

 updateManager.delete(qstring, document); 

 /* delete all comments in a collection */
 qstring = "//comment()"; 

 SixdmlCollection collection = 
     (SixdmlCollection) database.getCollection(cid, null, null); 

 if(collection == null)
     throw new XMLDBException(0, "Cannot find collection named " + cid);

 updateManager.delete(qstring, collection);

Replacing nodes in documents and collections


 String cid         = "bookstore";
 String did         = "books.xml";
 String qstring     = "//book[1]";

 SixdmlUpdateService updateManager = 
     (SixdmlUpdateService) database.getService("SixdmlUpdateService", "1.0"); 

 /* replace first <book> in a document */
 SixdmlResource document = (SixdmlResource) database.getResource(did, null, null); 

 if (document == null)
     throw new XMLDBException(0, "Cannot find document named " + did); 

 updateManager.delete(qstring, "<book>The Hunt For Red October</book>", document); 

 /* replace all comments in a collection with CDATA sections */
 qstring = "//comment()"; 
		
 SixdmlCollection collection = 
     (SixdmlCollection) database.getCollection(cid, null, null); 

 if (collection == null)
     throw new XMLDBException(0, "Cannot find collection named " + cid);

 updateManager.delete(qstring,"<![CDATA[ TODO: Update comments ]] >",collection);

Renaming nodes in documents and collections


 String cid         = "bookstore";
 String did         = "books.xml";
 String qstring     = "//@genre";
 String ns          = "urn:bookstore-schema";
 String newName     = "section";

 SixdmlUpdateService updateManager = 
     (SixdmlUpdateService) database.getService("SixdmlUpdateService", "1.0"); 

 /* rename genre attribute to section attribute in a document */
 SixdmlResource document = (SixdmlResource) database.getResource(did, null, null); 

 if(document == null)
     throw new XMLDBException(0, "Cannot find document named " + did); 

 updateManager.rename(qstring, newName ,null,document); 

 /* rename <book> to <bk:book> in a colection and specify namespace URI */
 qstring = "//book"; 
 newName = "bk:book"; 

 SixdmlCollection collection = 
     (SixdmlCollection) database.getCollection(cid, null, null); 

 if(collection == null)
     throw new XMLDBException(0, "Cannot find collection named " + cid);

 URI nsuri = new URI(ns)); 
 updateManager.rename(qstring, newName, nsuri, document);

Use Cases for Direct Execution

Below are examples showing the SixdmlStatement and SixdmlPreparedStatement classes in action.

Using SAX and the SixdmlStatement


 import java.io.FileReader;

 import org.xml.sax.XMLReader;
 import org.xml.sax.Attributes;
 import org.xml.sax.InputSource;
 import org.xml.sax.helpers.XMLReaderFactory;
 import org.xml.sax.helpers.DefaultHandler;

 import org.sixdml.dbmanagement.*; 
 import org.sixdml.exceptions.*; 
 import org.sixdml.command.*; 
 import org.sixdml.*; 

 import org.xmldb.api.*; 
 import org.xmldb.api.base.*; 
 import java.net.*; 

 class MySaxHandler extends DefaultHandler{ 

     public static void main(String[] args) throws Exception{ 

         Collection col = null;

             String driver = "org.sixdml.excelon.xlnSixdmlDatabase";
             Class c = Class.forName(driver);

             SixdmlDatabase database = (SixdmlDatabase) c.newInstance(); 
             SixdmlTransactionService transaction = 
                 (SixdmlTransactionService) database.getService(
                     "SixdmlTransactionService", "1.0"); 

             transaction.begin(); 
             DatabaseManager.registerDatabase(database); 

             SixdmlStatementService stmtManager = 
                 (SixdmlStatementService) database.getService( 
                     "SixdmlStatementService", "1.0"); 

	     SixdmlStatement stmt = stmtManager.createStatement(); 
	     stmt.executeQuery("SELECT //auction FROM COLLECTION auctiondata", new MySaxHandler());


             transaction.commit(); 

	
     }//main(String[]) 

     
       public SixdmlTest ()
    {
	super();
    }


    ////////////////////////////////////////////////////////////////////
    // Event handlers.
    ////////////////////////////////////////////////////////////////////


    public void startDocument ()
    {
	System.out.println("Start document");
    }


    public void endDocument ()
    {
	System.out.println("End document");
    }


    public void startElement (String uri, String name,
			      String qName, Attributes atts)
    {
	if ("".equals (uri))
	    System.out.println("Start element: " + qName);
	else
	    System.out.println("Start element: {" + uri + "}" + name);
    }


    public void endElement (String uri, String name, String qName)
    {
	if ("".equals (uri))
	    System.out.println("End element: " + qName);
	else
	    System.out.println("End element:   {" + uri + "}" + name);
    }


    public void characters (char ch[], int start, int length)
    {
	System.out.print("Characters:    \"");
	for (int i = start; i < start + length; i++) {
	    switch (ch[i]) {
	    case '\\':
		System.out.print("\\\\");
		break;
	    case '"':
		System.out.print("\\\"");
		break;
	    case '\n':
		System.out.print("\\n");
		break;
	    case '\r':
		System.out.print("\\r");
		break;
	    case '\t':
		System.out.print("\\t");
		break;
	    default:
		System.out.print(ch[i]);
		break;
	    }
	}
	System.out.print("\"\n");
    }



 }

Using DOM and the SixdmlPreparedStatement


 import org.apache.xerces.parsers.DOMParser;
 import org.w3c.dom.Document;
 import org.w3c.dom.Node;
 import org.w3c.dom.Element;
 import org.w3c.dom.NodeList;
 import org.xml.sax.SAXException;
 import java.io.IOException;

 import org.sixdml.dbmanagement.*;
 import org.sixdml.exceptions.*; 
 import org.sixdml.command.*; 
 import org.sixdml.*; 

 import org.xmldb.api.*; 
 import org.xmldb.api.base.*; 
 import java.net.*; 

 class SixdmlTest{ 

     public static void main(String[] args) throws Exception{ 

         Collection col = null;

             String driver = "org.sixdml.excelon.xlnSixdmlDatabase";
             Class c = Class.forName(driver);

             SixdmlDatabase database = (SixdmlDatabase) c.newInstance(); 
             SixdmlTransactionService transaction = 
                 (SixdmlTransactionService) database.getService(
                     "SixdmlTransactionService", "1.0"); 

             transaction.begin(); 
             DatabaseManager.registerDatabase(database); 

             SixdmlStatementService stmtManager = 
                 (SixdmlStatementService) database.getService( 
                     "SixdmlStatementService", "1.0"); 

	     SixdmlPreparedStatement pstmt = stmtManager.prepareStatement("SELECT ? FROM auctions/spring-garage-sale.xml"); 
	     pstmt.setObject(1, "//*[@buyer='Dare']"); 
	     Document doc = pstmt.executeQuery();
	     traverse(doc);      	     	     
	     
             transaction.commit();	


	
     }//main(String[]) 


    //  Traverse DOM Tree example from Apache Xerces documentation
   
   private void traverse (Node node) {
      int type = node.getNodeType();
      if (type == Node.ELEMENT_NODE)
         System.out.println (node.getNodeName());
      NodeList children = node.getChildNodes();
      if (children != null) {
         for (int i=0; i< children.getLength(); i++) 
            traverse (children.item(i));  
      }
   }


    
 }

Prototype Implementations

Prototype implementations of both the SiXDML language and API have been developed by a number of authors including Dare Obasanjo, Sanjay Bhatia and Dietrich Ayala. Below are descriptions of the current prototype implementations.

An online demo of the SiXDML language is available as well as Javadoc documentation for the implemented classes. The language demo utilizes a language parser built using ANTLR.

Excelon Implementation

The SiXDML API has been implemented over the eXcelon corporation's native XML database product. The packages that constitute the eXcelon implementation are org.sixdml.excelon and org.sixdml.validation which contains a utility class that performs XML schema validation using Oracle's XDK API. The SiXDML implementation extends the functionality of eXcelon by providing support for W3C XML schemas even though eXcelon only supports DTD validation of XML documents stored in its native XML database. Also the SiXDML implementation allows one to create named indices which apply to an entire collection even though eXcelon has no mechanism for naming an index or applying it to multiple documents. The most pertinent details pertaining to the implementation are discussed next.

Collections and Directories. The eXcelon native XML database does not have the concept of collections of XML documents that can be manipulated with a single operation. Instead eXcelon's native XML database uses directories of which are akin to filesystems on a directory. Thus every SiXDML operation that operates on a collection iterates through the directory performing operations on any XML document within the directory. An instance of the xlnSixdmlCollection class is actually a wrapper around an eXcelon Directory object.

Although non-XML files can be stored in the eXcelon native XML database, the SiXDML implementation does not provide a mechanism to manipulate them since the API was designed for XML repositories and not hybrid repositories.

Explicit Document Storage. The eXcelon native XML database uses the ObjectStore object oriented database management system as a basis for its database infrastructure. ObjectStore does not have an explicit mechanism for storing objects instead transaction boundaries are marked between operations on objects stored in the database and inbetween these transaction boundaries modifications of these objects in memory are reflected in the database. The eXcelon XMLDocument class represents an XML document class stored in the database and reflects changes performed on it in-memory on the database instantly. To prevent this behavior an xlnSixdmlResource object is a wrapper around a XlnDOMTransientDocument object. The XlnDOMTransientDocument class is an implementation of the XML Document Object Model (DOM) which holds an in-memory representation of an XML document with some additional methods specific to eXcelon.

Once a request is made to create a SixdmlResource, the XMLDocument representing that object is retrieved from the database and its contents are placed in a XlnDOMTransientDocument which is then used to build an xlnSixdmlResource. Only when an explicit request is made to save the object via the SiXDML API are the contents of the XlnDOMTransientDocument placed in an XMLDocument which automatically stores it in the database since all SiXDML transaction boundaries specify that they are update transactions to the eXcelon native XML database.

W3C XML Schema Validation. When a schema is specified against a collection the first thing that is done is to make sure the schema is well-formed and valid by validating it using Oracle's XML Schema validation API. If the schema is valid it is then placed in the eXcelon directory and given the same name as the directory with a ".6dml" file extension. From then on any documents that are stored in the directory using the SiXDML API are first validated against the document before being stored.

The schema file acts as a special "hidden system file" because it can only be manipulated via the methods pertaining to schemas. Any attempts to retrieve or update a schema file without going through the proper access methods throws an exception.

Named Indices. An index in the eXcelon native XML database can be created on specific document but neither has a name nor can it apply to more than one document at a time. To get around this problem when an index is first created on an xlnSixdmlCollection, an index file is created. An index file is an XML file with the same name as the collection with a ".indx" file extension. Whenever a SixdmlIndex object is needed from the xlnSixdmlCollection the index file is queried and if an index with that name is found, it can be constructed from its properties described in the index file.

When a document is added to the database, the index file is queried and all indices in effect on that directory are applied to the XMLDocument object. The indices are applied to documents by instantiating XlnIndex objects based on the information in the index file. Similar actions are performed when an index is deleted from the xlnSixdmlCollection to remove the index from each document in the directory.

The index file acts as a special "hidden system file" because it can only be manipulated via the methods pertaining to indices. Any attempts to retrieve or update an index file without going through the proper access methods throws an exception.