uk.org.ogsadai.dataresource
Class XMLDBDataResourceAccessor

java.lang.Object
  |
  +--uk.org.ogsadai.dataresource.XMLDBDataResourceAccessor

All Implemented Interfaces:

DataResourceAccessor, PersistInFiles, XMLDBCollectionProvider

public class XMLDBDataResourceAccessor

extends java.lang.Object

implements DataResourceAccessor, PersistInFiles, XMLDBCollectionProvider

A data resource accessor that provides access to XMLDB data resources.

The configuration file is named dataResourceConfig.xml and is assumed to reside in the configuration files directory for the data service resource that owns this data resource accessor.

Author:

The OGSA-DAI Project Team

Field Summary

private static java.lang.String	COPYRIGHT_NOTICE
private static DAILogger	LOG
private static java.lang.String	MAIN_CONFIG_FILE_NAME
private java.lang.String	mCollectionURI
private java.lang.String	mDriverClassName
private Property[]	mProperties
private java.lang.String	mResourceName
private RoleMapper	mRoleMapper

Constructor Summary

XMLDBDataResourceAccessor()

Method Summary

private java.lang.String	getAndLoadDriverClassName(org.w3c.dom.Document configDoc) Returns the name of the XMLDB driver class and loads the class and registers it with the XMLDB database manager.
java.lang.String	getBaseCollectionURI() Return the URI of the base collection.
protected org.xmldb.api.base.Collection	getCollection(java.lang.String collectionURI, java.lang.String user, java.lang.String password) Obtains a collection from the database.
private Property	getCollectionSchema(java.lang.String name, org.w3c.dom.Document configDoc) Extract collection schema meta data from the data resource accessor configuration and converts to a property.
private java.lang.String	getCollectionURI(org.w3c.dom.Document configDoc) Returns the URI of the database.
private org.w3c.dom.Document	getConfigAsDOM(java.lang.String name, java.io.File dir) Reads the data resource accessor configuration file and converts it to DOM.
private Property[]	getMetaData(java.lang.String name, org.w3c.dom.Document configDoc) Extract meta data from the data resource accessor configuration and convert to properties.
private Property	getProductInfo(org.w3c.dom.Document configDoc) Extract product meta data from the data resource accessor configuration and convert to property.
Property[]	getProperties() Gets the resource properties associated with the data resource accessor.
private Property[]	getProperties(Property productInfo, Property collectionSchema, Property[] metaData) Gets data resource accessor properties - formed from aggregation of all meta data properties.
private RoleMapper	getRoleMapper(org.w3c.dom.Document configDoc) Extracts the role mapper implementation class, creates an instance of it and initialises it with a role map file.
org.xmldb.api.base.Collection	getXMLDBCollection(java.lang.String userCredentials) Returns an open collection for the base collection of a data resource.
org.xmldb.api.base.Collection	getXMLDBCollection(java.lang.String subCollection, java.lang.String userCredentials) Returns an open collection for the specified sub-collection of a data resource.
void	releaseXMLDBCollection(org.xmldb.api.base.Collection collection) Releases a previously obtained XMLB collection.
void	restoreFromConfig(java.io.File directory) Configures the data resource accessor by reading any relevant configuration files in the given directory.
void	setResourceName(java.lang.String resourceName) Sets the name of the resource.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COPYRIGHT_NOTICE

private static final java.lang.String COPYRIGHT_NOTICE

See Also:

Constant Field Values

LOG

private static DAILogger LOG

MAIN_CONFIG_FILE_NAME

private static final java.lang.String MAIN_CONFIG_FILE_NAME

See Also:

Constant Field Values

mResourceName

private java.lang.String mResourceName

mProperties

private Property[] mProperties

mRoleMapper

private RoleMapper mRoleMapper

mDriverClassName

private java.lang.String mDriverClassName

mCollectionURI

private java.lang.String mCollectionURI

Constructor Detail

XMLDBDataResourceAccessor

public XMLDBDataResourceAccessor()

Method Detail

setResourceName

public void setResourceName(java.lang.String resourceName)

Description copied from interface: DataResourceAccessor

Sets the name of the resource. This method will be called one before any other methods in this interface are called. Data resource accessors are not required to do anything with this name although it is sometimes useful to include it in any error messages.

Specified by:

setResourceName in interface DataResourceAccessor

Parameters:

resourceName - Name of the data service resource which will use this data resource accessor to mediate access to a data resource.

restoreFromConfig

public void restoreFromConfig(java.io.File directory)
                       throws DataResourceAccessorConfigException,
                              DataResourceAccessorMetaDataException,
                              DataResourceAccessorSetupException,
                              java.lang.IllegalArgumentException

Description copied from interface: PersistInFiles

Configures the data resource accessor by reading any relevant configuration files in the given directory.

If a data service resource is being constructed by reading from a configuration file this method will be called once immediately after the setName method is called. The data resource accessor should read its configuration from the files in the given directory of the data service resource which uses it.

Data resource accessors are free to add, amend or delete files in the given directory at any time throughout their lifetime. The exception to this rule is the dataResourceClassConfig.xml file which must be left unaltered since this specifies the data resource accessor class name.

Specified by:

restoreFromConfig in interface PersistInFiles

Parameters:

directory - Directory containing the data service resource configuration files. This includes the data resource accessor configuration files.

Throws:

java.lang.IllegalArgumentException - if the directory argument is null or is not a directory.

DataResourceAccessorSetupException - if an error occurs when setting up the data resource accessor after having read the configuration files.

DataResourceAccessorConfigException - if an error occurs reading the configuration files.

DataResourceAccessorMetaDataException - if an error occurs when constructing data resource accessor meta data properties.

getConfigAsDOM

private org.w3c.dom.Document getConfigAsDOM(java.lang.String name,
                                            java.io.File dir)
                                     throws DataResourceAccessorConfigException

Reads the data resource accessor configuration file and converts it to DOM.

Parameters:

name - Data service resource name.

dir - Data service resource configuration files directory.

Returns:

DOM representation of data resource accessor configuration file.

Throws:

DataResourceAccessorConfigException - if there is an error in reading the configuration file.

getProductInfo

private Property getProductInfo(org.w3c.dom.Document configDoc)

Extract product meta data from the data resource accessor configuration and convert to property.

Parameters:

configDoc - Data resource accessor configuration document.

Returns:

product meta data property or null if none.

getMetaData

private Property[] getMetaData(java.lang.String name,
                               org.w3c.dom.Document configDoc)
                        throws DataResourceAccessorMetaDataException

Extract meta data from the data resource accessor configuration and convert to properties.

Parameters:

name - Data service resource name.

configDoc - Data resource accessor configuration document.

Returns:

meta data properties.

Throws:

DataResourceAccessorMetaDataException - if an error occurs when constructing data resource accessor meta data properties.

getProperties

private Property[] getProperties(Property productInfo,
                                 Property collectionSchema,
                                 Property[] metaData)

Gets data resource accessor properties - formed from aggregation of all meta data properties.

Parameters:

productInfo - Product meta data property.

collectionSchema - Collection schema property.

metaData - Other meta data properties.

Returns:

data resource accessor properties.

getCollectionSchema

private Property getCollectionSchema(java.lang.String name,
                                     org.w3c.dom.Document configDoc)
                              throws DataResourceAccessorMetaDataException

Extract collection schema meta data from the data resource accessor configuration and converts to a property.

Extracts a collection schema meta data extractor class from the value of a callback attribute of a collectionSchema child element of metaData. From this a dynamic property is constructed. The dynamic property callback callsback in turn to this class.

Parameters:

name - Data service resource name.

configDoc - Data resource accessor configuration document.

Returns:

Collection schema meta data propert.

Throws:

DataResourceAccessorMetaDataException - if an error occurs when constructing data resource accessor meta data properties.

getRoleMapper

private RoleMapper getRoleMapper(org.w3c.dom.Document configDoc)
                          throws RoleMapperCreationException,
                                 RoleMapConfigurationException

Extracts the role mapper implementation class, creates an instance of it and initialises it with a role map file.

The information is held within the roleMap element of a data resource accessor configuration file.

Parameters:

configDoc - Data resource accessor configuration document.

Returns:

role mapper.

Throws:

RoleMapperCreationException - if the role mapper cannot be created.

RoleMapConfigurationException - if the role mapper cannot be configured with a role map file.

getAndLoadDriverClassName

private java.lang.String getAndLoadDriverClassName(org.w3c.dom.Document configDoc)
                                            throws DAIClassNotFoundException,
                                                   DAIClassCreateException,
                                                   DAIClassMissingInterfaceException,
                                                   XMLDBRegistrationException

Returns the name of the XMLDB driver class and loads the class and registers it with the XMLDB database manager.

Parameters:

configDoc - Data resource accessor configuration document.

Returns:

name of JDBC driver class.

Throws:

DAIClassNotFoundException - if the driver class cannot be loaded.

DAIClassCreateException - if an instance of the driver cannot be created.

DAIClassMissingInterfaceException - if the driver class does not implement interfaces required by the XMLDB driver manager. throws XMLDBRegistrationException if the driver instance cannot be registered with the XMLDB driver manager.

XMLDBRegistrationException

getCollectionURI

private java.lang.String getCollectionURI(org.w3c.dom.Document configDoc)

Returns the URI of the database.

Parameters:

configDoc - Data resource accessor configuration document.

Returns:

URI of database.

getProperties

public Property[] getProperties()

Description copied from interface: DataResourceAccessor

Gets the resource properties associated with the data resource accessor. These are made available as properties of the data service resource to which the data resource accessor belongs.

This method should be called once after the readConfig method has been called but before any other methods are called.

Specified by:

getProperties in interface DataResourceAccessor

Returns:

The resource proporties. If there are no resource properties then a zero-sized array will be returned.

getBaseCollectionURI

public java.lang.String getBaseCollectionURI()

Description copied from interface: XMLDBCollectionProvider

Return the URI of the base collection.

Specified by:

getBaseCollectionURI in interface XMLDBCollectionProvider

Returns:

collection URI.

getXMLDBCollection

public org.xmldb.api.base.Collection getXMLDBCollection(java.lang.String userCredentials)
                                                 throws DataResourceAuthorizationException,
                                                        XMLDBCollectionUseException,
                                                        AuthorizationExecutionException

Description copied from interface: XMLDBCollectionProvider

Returns an open collection for the base collection of a data resource.

The specified user credential may be used to authorize access to the data resource.

Specified by:

getXMLDBCollection in interface XMLDBCollectionProvider

Parameters:

userCredentials - Credentials specifing a user.

Returns:

an open collection for the base collection.

Throws:

XMLDBCollectionUseException - if there is a problem in using the data resource.

AuthorizationExecutionException - if there is a problem encountered during the authorization.

DataResourceAuthorizationException - if the user is not authorized to access the collection.

getXMLDBCollection

public org.xmldb.api.base.Collection getXMLDBCollection(java.lang.String subCollection,
                                                        java.lang.String userCredentials)
                                                 throws DataResourceAuthorizationException,
                                                        XMLDBUnknownSubCollectionException,
                                                        XMLDBCollectionUseException,
                                                        AuthorizationExecutionException

Description copied from interface: XMLDBCollectionProvider

Returns an open collection for the specified sub-collection of a data resource.

The specified user credential may be used to authorize access to the data resource.

Specified by:

getXMLDBCollection in interface XMLDBCollectionProvider

Parameters:

subCollection - The path to the sub-collection relative to the data resource's base collection. This should not begin with a "/". The "/" is added automatically to the base collection URI when the full collection URI is composed. For example, if the base collection is db and the sub-collection is test/addresses then an open collection for /db/test/addresses will be returned. If this is null then the base collection is returned.

userCredentials - Credentials specifing a user.

Returns:

an open collection for the sub-collection.

Throws:

AuthorizationExecutionException - if there is a problem encountered during the authorization.

XMLDBUnknownSubCollectionException - if the sub-collection is unknown.

XMLDBCollectionUseException - if there is a problem in using the data resource.

DataResourceAuthorizationException - if the user is not authorized to access the collection or sub-collection.

releaseXMLDBCollection

public void releaseXMLDBCollection(org.xmldb.api.base.Collection collection)
                            throws XMLDBCollectionUseException

Description copied from interface: XMLDBCollectionProvider

Releases a previously obtained XMLB collection.

Once a collection is finished with it should be passed back to this method. This allows collection pooling to be performed under the surface.

Specified by:

releaseXMLDBCollection in interface XMLDBCollectionProvider

Parameters:

collection - XMLDB collection to release. If the collection is null or already released then nothing is done.

Throws:

XMLDBCollectionUseException - if there is a problem in closing the collection.

getCollection

protected org.xmldb.api.base.Collection getCollection(java.lang.String collectionURI,
                                                      java.lang.String user,
                                                      java.lang.String password)
                                               throws XMLDBCollectionUseException

Obtains a collection from the database.

Parameters:

collectionURI - URI of the database collection.

user - User name used to access database

password - Password used to access database.

Returns:

the collection or null if there is no such collection.

Throws:

XMLDBCollectionUseException - if the collection cannot be accessed.