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.
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 XML:DB API Base Module
2 Core Interfaces
    2.1 Resource
        2.1.1 IDL Specification
        2.1.2 Methods
    2.2 Collection
        2.2.1 IDL Specification
        2.2.2 Methods
    2.3 Service
        2.3.1 IDL Specification
        2.3.2 Methods
    2.4 Database
        2.4.1 IDL Specification
        2.4.2 Methods
    2.5 Configurable
        2.5.1 IDL Specification
        2.5.2 Methods
    2.6 ResourceIterator
        2.6.1 IDL Specification
        2.6.2 Methods
    2.7 DatabaseManager
        2.7.1 IDL Specification
        2.7.2 Methods
3 List Types
    3.1 ServiceList
    3.2 CollectionList
    3.3 VersionList
    3.4 DatabaseList
4 Exceptions

Appendices



XML:DB API Base Module

The XML:DB API Base module provides the core framework that the rest of the API is built upon. It provides common types and access mechanisms to gain access to the services provided by the API. The API Base as a standalone module is not particulary useful. It must be coupled with resource and service implementations to take care of the real work required. However, without the services of the API Base module all other modules are completely useless. Understanding the basic workings of the API Base module is essential to understanding the XML:DB API overall.


Core Interfaces

Resource

Resource is an abstract container wrapper for data stored in an XML database. It exists because there are several different ways of accessing data in XML databases e.g. text, DOM, SAX and it may be desireable to store other types of data as well e.g. binary content. The XML:DB API defines several common resource types in seperate modules. The Resource interface itself provides a common management API for these Resource types.

The Resource interface can not be used directly it must be extended to handle particular resource types.

Resource types supported by an API implementation will vary based on Core Level and optional resource support as provided by the vendor.

IDL Specification

 
interface Resource {    
   Collection getParentCollection();
   string getId();
   Object getContent();
   void setContent( in Object value );      
};
      

Methods

getParentCollection

Returns the parent Collection object for the current collection.

NoteBehaviour for collections that do not have parents must be defined

NoteIDs are troublesome as it is very possible to have a Resource that does not have an associated ID.

NoteTheir is an implicit connection between a resource and a collection instance. This needs to be clarified.

Return Value

A Collection object representing the parent of the current Collection


Exceptions

To be defined


getID

Returns the ID associated with this resource. If no ID exists for the Resource then a null value will be returned

Return Value

The ID associated with this resource or null if no ID exists.


Exceptions

To be defined


getContent

Returns the content that is encapsulated by the resource. The type of the content is determined by the subclass instance that is actually used.

Return Value

An abstract object that reprsents the content.


Exceptions

To be defined


setContent

Sets the encapsulated content object that is associated with the resource.

Parameters

value The content value to be stored.


Exceptions

To be defined




Collection

A Collection represents a collection of Resources stored within an XML database. Collection is the primary mechanism for getting access to resources and services that operate on those resources. An XML database MAY expose collections as a hierarchical set of parent and child collections.

IDL Specification

 
interface Collection : Configurable {      
   ServiceList getServices();
   Service getService( in string name, in string version );
   void registerService( in Service service );
   
   Collection getParentCollection();      
   long getChildCollectionCount();
   CollectionList getChildCollections();
         
   long getResourceCount();
   ResourceIterator getResources();
   Resource createResource( in string id );
   void removeResource( in Resource resource );
   void storeResource( in Resource resource );
   Resource getResource( in string id );
   
   string createId();
   void close();
};
      

Methods

getServices

Returns a ServiceList containing all services available for this collection

Return Value

Returns a ServiceList containing the names of all services available for this collection


Exceptions

To be defined


getService

Returns a Service instance for the service requested.

Parameters

name The name of the service instance requested.

version The version string if a particular version of a service is required.


Return Value

The requested Service instance


Exceptions

To be defined


registerService

Registers a new Service for use by this Collection. The Service instance will be queried for the Service name and versions supported. After registration the Service can be retrieved via getService.

Parameters

service The service instance to register.


Exceptions

To be defined


getParentCollection

Returns the parent Collection instance for this collection.

NoteShould throw an exception if no parent collection exists?

Return Value

The Collection instance for the parent of this collection.


Exceptions

To be defined


getChildCollectionCount

Returns the number of child collections nested under this collection. If no child collections exist 0 is returned.

Return Value

The number of child collections.


Exceptions

To be defined


getChildCollections

Returns a CollectionList containing all child collections for this collection. If no child collections exist an empty list will be returned.

Return Value

The CollectionList containing a child collections.


Exceptions

To be defined


getResourceCount

Returns the number of resources contained by this collection. If the collection is empty 0 is returned.

Return Value

The number of resources contained in the collection.


Exceptions

To be defined


getResources

Returns a ResourceIterator containing Resource objects for all resources in the collection. Provides a simple way to perform operations on all resources stored in the collection.

Return Value

The ResourceIterator containing a list of all Resources in the collection.


Exceptions

To be defined


createResource

Creates a new Resource instance associated with the provided ID. The ID must be unique within the context of the associated collection.

NoteWhat happens if id is not unique?

NoteShould id be optional? Maybe this method should be createResource() with no id and a seperate method setID on Resource should be added?

Parameters

id The ID to associate with this resource.


Return Value

A new Resource instance.


Exceptions

To be defined


removeResource

Removes the provided resource from this collection.

NoteWhat is the behavior with a Resource from another collection?

NoteHow does this fit in a transaction?

Parameters

resource The resource instance to remove from the repository.


Exceptions

To be defined


storeResource

Saves the provided resource to the database.

Parameters

resource The resource to save.


Exceptions

To be defined


getResource

Retrieves a Resource from the database. The resource is located using the id specified as a parameter.

Parameters

id The id to use when locating the resource.


Return Value

The Resource instance for the requested resource.


Exceptions

To be defined


createId

Creates a new unique ID within the context of this collection.

Return Value

The created ID


Exceptions

To be defined


close

Closes the Collection instance and releases all resources in use by the instance. Once close has been called the Collection instance can not be used again.

Exceptions

To be defined




Service

Service provides a mechanism to enable extra processing to occur within the context of a collection. It is basically an extension mechanism for the API to enable it to handle situations not forseen at the time of the APIs creation. The Service interface just defines the basic control methods that are necessary to register and use a service. It is expected that Service implementations will define their own detailed interfaces that will vary from service to service.

The XML:DB API defines several optional Service modules that can be implemented. It is also acceptable for a vendor to define their own custom Services to expose special features of their products. A warning must be attached to these services however, that makes it clear that their use will cause incompatibility with other vendors products.

Service support in implementations will vary based on Core Level and optional service implementations included by the vendor.

IDL Specification

 
interface Service : Configurable {                
   string getName();
   string getVersion();
   void setCollection( in Collection col );
};
      

Methods

getName

Returns the name that this service should be registered under. The name in combination with the version must be unique within the API. This name is used by Collection.getService() to return the requested service instance

NoteIf multiple entities are publishing services there is a risk of collision on naming.

Return Value

The service name


Exceptions

To be defined


getVersion

Returns the version string for this service implementation.

NoteShould this return a VersionList so that a service can claim to implement multiple versions of an API?

Return Value

The version string for this service


Exceptions

To be defined


setCollection

Sets the associated Collection within which all service operations will be performed.

Parameters

col The Collection instance to use.


Exceptions

To be defined




Database

A Database instance represents a driver for a particular XML database.

IDL Specification

 
interface Database : Configurable {
   Collection getCollection( in string uri );        
   boolean acceptsURI( in string uri );
   long getConformanceLevel();   
};
      

Methods

getCollection

Returns a Collection instance. The collection is located using a URI specific to the underlying database

Parameters

uri The database specific URI to use to locate the collection


Return Value

The Collection instance


Exceptions

To be defined


acceptsURI

Returns true if the provided URI is handled by this database. This is used by the DatabaseManager to select which Database instance should handle a request.

Return Value

Returns true if the URI is handled by this Database false otherwise.


Exceptions

To be defined


getConformanceLevel

Returns the maximum XML:DB API Core Level conformance supported by this database driver.

Return Value

Returns the numeric Core Level conformance supported by this Database.


Exceptions

To be defined




Configurable

Configurable is an interface extended to provide basic configuration abilities to an object. This consists of basic setting and getting of property values keyed off of a unique string.

IDL Specification


interface Configurable {      
   string getProperty(in string name);
   void setProperty(in string name, in string value);
};
      

Methods

getProperty

Returns the property value for the property identified by name. The value is returned as a string

Parameters

name The name of the property being requested.


Return Value

The string value for the property.


Exceptions

To be defined


setProperty

Sets a string value property

Parameters

name The name of the property to set.

value The value to set the property to.


Exceptions

To be defined




ResourceIterator

ResourceIterator provides an iterator over a set of Resources.

NoteHow is the set ordered?

IDL Specification

 
interface ResourceIterator {
   boolean hasMoreResources();
   Resource nextResource();
};
      

Methods

hasMoreResources

Returns true as long as more resources are available in the set.

Return Value

Returns true if more resources are available, false otherwise.


Exceptions

To be defined


nextResource

Returns the next Resource from the set. If no more resources are available null will be returned.

Return Value

The next Resource from the set.


Exceptions

To be defined




DatabaseManager

DatabaseManager is the entry point for the API. It is the control point that provides access to Collections. DatabaseManager is intended to be provided as a concrete implementation in a particular programming language. Individual language mappings should define the exact syntax and semantics of its use. This interface specification serves as a basic guide.

IDL Specification

 
interface DatabaseManager : Configurable {
   DatabaseList getDatabases();
   void registerDatabase( in Database database );                    
   void deregisterDatabase( in Database database );           

   Collection getCollection( in string uri/*, in Properties props */);
   long getConformanceLevel( in string uri );
};
      

Methods

getDatabases

Returns a DatabaseList containing all Database instances known to the DatabaseManager.

Return Value

DatabaseList containing all known Databases.


Exceptions

To be defined


registerDatabase

Registers a new Database instance with the DatabaseManager. The Database instance will be queried to find other relavent information.

Parameters

database The database instance to register.


Exceptions

To be defined


deregisterDatabase

Removes a Database instance registration from the DatabaseManager.

NoteHow is equivalence of instance determined?

Parameters

database The database instance to deregister.


Exceptions

To be defined


getCollection

Retrieves a Collection instance using the provided URI. The URI will be used to determine which Database driver to use by calling the acceptsURI method on each Database instance until a match is found.

Parameters

uri The uri used to retrieve the collection.


Return Value

The retrieved Collection.


Exceptions

To be defined


getConformanceLevel

Returns the maximum XML:DB API Core Level conformance supported by the provided URI.

Parameters

uri The uri to request Core Level conformance for.


Return Value

Returns the numeric Core Level conformance supported for the URI.


Exceptions

To be defined





List Types

ServiceList

A ServiceList is list of services supported by a Collection.


typedef sequence<Service> ServiceList;
   

CollectionList

A CollectionList stores lists of child Collections under a root Collection.


typedef sequence<Collection> CollectionList;
   

VersionList

A VersionList stores a list of version strings


typedef sequence<string> VersionList;
   

DatabaseList

A DatabaseList stores a list of Database instances


typedef sequence<Database> DatabaseList;
   




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