uk.org.ogsadai.dataresource
Class JDBCDataResourceAccessor

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

All Implemented Interfaces:

DataResourceAccessor, JDBCConnectionProvider, PersistInFiles

public class JDBCDataResourceAccessor

extends java.lang.Object

implements DataResourceAccessor, PersistInFiles, JDBCConnectionProvider

A data resource accessor that provides access to JDBC 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

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

mConnectionURI

private java.lang.String mConnectionURI

JDBCDataResourceAccessor

public JDBCDataResourceAccessor()

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.

readConfig

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

DataResourceAccessorConfigException

DataResourceAccessorMetaDataException

DataResourceAccessorSetupException

java.lang.IllegalArgumentException

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[] metaData)

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

Parameters:

productInfo - Product meta data property.

metaData - Other meta data properties.

Returns:

data resource accessor 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

Returns the name of the JDBC driver class and loads the class.

Parameters:

configDoc - Data resource accessor configuration document.

Returns:

name of JDBC driver class.

Throws:

DAIClassNotFoundException - if the driver class cannot be loaded.

getConnectionURI

private java.lang.String getConnectionURI(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.

getJDBCDriverClassName

public java.lang.String getJDBCDriverClassName()

Description copied from interface: JDBCConnectionProvider

Returns the name of the JDBC driver class.

Specified by:

getJDBCDriverClassName in interface JDBCConnectionProvider

Returns:

the name of the JDBC driver class.

getJDBCConnection

public java.sql.Connection getJDBCConnection(java.lang.String userCredentials)
                                      throws DataResourceAuthorizationException,
                                             JDBCConnectionUseException,
                                             AuthorizationExecutionException

Description copied from interface: JDBCConnectionProvider

Returns a JDBC connection.

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

Specified by:

getJDBCConnection in interface JDBCConnectionProvider

Parameters:

userCredentials - Credentials specifing a user.

Returns:

a JDBC connection.

Throws:

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

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

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

releaseJDBCConnection

public void releaseJDBCConnection(java.sql.Connection connection)
                           throws JDBCConnectionUseException

Description copied from interface: JDBCConnectionProvider

Releases a previously obtained JDBC connection.

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

Specified by:

releaseJDBCConnection in interface JDBCConnectionProvider

Parameters:

connection - JDBC connection to release. If the connection is null or already released then nothing is done.

Throws:

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

getConnection

protected java.sql.Connection getConnection(java.lang.String connectionURI,
                                            java.lang.String user,
                                            java.lang.String password)
                                     throws JDBCConnectionUseException

Obtains a connection from the database.

Parameters:

connectionURI - URI of the database connection.

user - User name used to access database

password - Password used to access database.

Returns:

the connection or null if there is no such connection.

Throws:

JDBCConnectionUseException - if the connection cannot be accessed.