The XML:DB API is designed to enable a common access mechanism to XML databases. The API enables the construction of applications to store, retrieve, modify and query data that is stored in an XML database. These facilities are intended to enable the construction of applications for any XML database that claims conformance with the XML:DB API. The API can be considered generally equivalent to technologies such as ODBC, JDBC or Perl DBI.

A major goal of the XML:DB API is to be modular and to define a simple baseline for implementors to follow. To achieve this goal the API is broken into small modules that are then bundled together in the form of API Core Level specifications.

The API Core Level specifications form the basis for interoperability by enabling a vendor to specify the maximum Core Level at which they are conformant. Applications can tailor their functionality based on Core Level or may require a specific Core Level to function. Vendors are free to add any additional modules beyond the base Core Level requirements but they are not required to do so. This modular nature provides a very clean path to increase support from one Core Level to the next.

On the surface this structure may seem overly complex and at first brush it is. However it is born out of the fact that the XML database arena is very new and rapidly changing. At this stage of evolution the playing field has not stabalized enough to know exactly what level of functionality is required to build applications. The Core Level mechanism is designed to keep things simple while still allowing significant evolution of the specification over the next few years. This model is in many ways similar to that being taken by the W3C DOM working group and is in the spirit of the Internet Standards Process RFC2026.

All API functionality is specified in terms of OMG IDL. IDL is easy to understand and acts as a filter to minimize language specific functionality. Language bindings for specific languages will be provided. Initial language support looks to consist of Java and Python but is open to the contribution of additional languages as interest dictates.

This section provides some tips for getting started in understanding the XML:DB API.

The best place to start is probably by looking at the Use Cases document. This document provides common database usage scenarios with solutions implemented using the XML:DB API. Each solution specifies the Core Level support and optional API modules required to complete the task. This provides an example oriented introduction to the various API modules.

From there the next step is to study the API Base module. This module is required for all implementations and forms the heart of the XML:DB API functionality.

After studying the use cases and API Base module you should have a good idea of what the API is good for and how it works. If you need more detail then you can dig into the other modules.

Core Levels define a set of baseline implementation levels that implementors can strive for. They provide a common, simple to understand bundling of XML:DB API modules to form workable API implementations. This tiered approach is taken to achieve the highest level of interoperability possible while still enabling advanced functionality for applications that can limit their scope to a smaller set of API implementations.

While a minimum baseline is specified to insure interoperability, it is strongly suggested that implementors strive for the highest Core Level implementation possible.

Minimum Conformance Level

Core Level 0 is the minimum level that must be implemented in order to claim XML:DB API conformance. It is safe to assume that any product that claims conformance with the XML:DB API specification will at a minimum support Core Level 0 functionality in an interoperable fashion.

Core Level 0

Core Level 0 consists of the following modules. All modules must be implemented to be considered conformant. API Base XMLResource

Core Level 1

Core Level 1 consists of the following modules. All modules must be implemented to be considered conformant. All Core Level 0 functionality XPathQueryService

This is a list of all modules currently defined within the scope of the XML:DB API. Not all modules are included in the Core Level specifications but are available to be added to implementations at any Core Level.

You can view a frames based version of all module documentation here.

API Base

The API Base module is the core of the XML:DB API. It provides the basic framework that all other modules hang off of. All API implementations regardless of Core Level support must implement this module. Specification IDL

Resources

XMLResource An XMLResource represents basic XML data. It provides access to that XML data as either textual XML, a W3C DOM Node or via a SAX ContentHandler. Specification IDL BinaryResource A binary resource represents a block of binary data or blob stored in the database. Specification IDL

Services

XPathQueryService A Service to enable querying Collections using XPaths. Specification IDL XUpdateQueryService A Service to enable updating collections and documents using the XML:DB XUpdate language. Specification IDL CollectionManagementService A Service to enable basic Collection management. In general Collection management will vary widely across database implementations so this service provides a very simple interface. Specification IDL TransactionService A Service to enable wrapping of multiple changes to a Collection within a Transaction context. Specification IDL

Changes in this section cover all modules.

Changes from the May. 07, 2001 draft.

• Removed the INVALID_SERVICE error from ErrorCodes because it is no longer used.
• Removed the registerService method from the Collection interface.
• Changed ErrorCodes from being an Enum to being an Interface to better control the allocation of error code numbers.
• ErrorCodes are now allocated to categories and grouped with all related codes being in the same series.
• Added new getCollection method containing username and password parameters to DatabaseManager
• Added username and password paramters to the getCollection() method in the Database interface.
• Added RESOURCE_TYPE constant to XMLResource and BinaryResource
• Changed Java mapping for BinaryResource to handle byte arrays for content.
• Added XUpdateService.
• Added CollectionManagementService.
• Added COLLECTION_CLOSED error code to ErrorCodes.
• Added isOpen method to the Collection interface.
• Added ResourceSet interface as new result for XPath queries.
• Added setNamespace method to XPathQueryService.
• Added getNamespace method to XPathQueryService.
• Added clearNamespaces method to XPathQueryService.
• Added removeNamespace method to XPathQueryService.
• Added queryResource method to XPathQueryService to handle queries against a single resource.
• Added getDocumentId() to the XMLResource interface.
• Removed getName from Configurable interface.
• Added getName to the Database interface.
• Added getName to the Collection interface.
• Added getName to the Service interface.
• Added COLLECTION_CLOSED error code to all methods in Collection that should not be called after close has been called.
• In the Java API Changed XMLDBException to extend Exception instead of RuntimeException.

Changes from the Mar. 15, 2001 draft.

• Changed module specs from spec format to use Javadoc
• Fixed Compilation Errors when using a strict IDL compiler.
• Added getName to Configurable interface.
• Removed getName from Service interface
• Added XMLDBException and ErrorCodes
• Removed DatabaseManager from IDL
• Removed Resource scope around modules
• Added getResourceType to Resource
• Added listChildCollections to Collection
• Added getChildCollection to Collection
• Added listResources to Collection
• Removed getChildCollections from Collection
• Removed getResources from Collection
• Added DOM and SAX support directly to XMLResource
• Removed DOMNodeResource
• Removed SAXResource
• Added NOT_IMPLEMENTED error code
• Changed DatabaseManager.getProperty, setProperty and getDatabases to not throw exceptions
• Added a resourceType parameter to Collection.createResource()