uk.ac.ic.doc.automed.wrappers
Class AutoMedWrapper

java.lang.Object
  |
  +--uk.ac.ic.doc.automed.wrappers.AutoMedWrapper

Direct Known Subclasses:

HdmWrapper, SQLWrapper, XMLWrapper, YattaWrapper

public abstract class AutoMedWrapper

extends java.lang.Object

An AutoMedWrapper represents an open connection to a datasource. Since datasources are so varied, much of the functionality of is deligated to implemention. Thus AutoMedWrapper is a foundation class for AutoMed wrappers to be built upon.

Author:

Peter McBrien (pjm@doc.ic.ac.uk)

Field Summary

protected AccessMethod	am
protected AutoMedWrapperFactory	awf
protected static int	debug
protected java.lang.String	driver
protected java.lang.String	password
protected Protocol	protocol
protected Schema	s
protected java.lang.String	url
protected java.lang.String	username

Constructor Summary

AutoMedWrapper()

Method Summary

static boolean	atDebugLevel(int level) Determine is debug is at or above a certain level.
protected void	cacheWrapper() Cache this AutoMedWrapper as being able to provide the implementation of an AccessMethod used to create the wrapper.
protected abstract void	connect() Use the connection details held with this wrapper to connect to the data source.
boolean	deleteIQL(ASG q)
abstract ASG	executeIQL(ASG q) Execute an IQL query on the datasource.
AutoMedResult	executeLocalQuery(AutoMedQuery q) Execute a query in the datasource's native query language, and obtain a result in an AutoMedResult class
AccessMethod	getAccessMethod() Returns the AccessMethod associated with this wrapper, which holds the details of the datasource being wrapped.
static AutoMedWrapper	getAutoMedWrapper(AccessMethod am) Equivalent to calling newAutoMedWrapper(am,null)
static AutoMedWrapper	getAutoMedWrapper(AccessMethod am, java.lang.String password) Return the wrapper asspciated to a stored AccessMethod.
AutoMedWrapperFactory	getAutoMedWrapperFactory() Return the AutoMedWrapperFactory currently associated with this wrapper.
protected abstract AutoMedWrapperFactory	getDefaultWrapperFactory() Return the default AutoMedWrapperFactory that is used to generate Schema instances from information in a data sources
java.lang.String	getOption(java.lang.String key) Return an option setting.
java.lang.String[]	getOptionKeys() Return the list of option setting key provided by the wrapper factory.
Protocol	getProtocol() Returns the Protocol associated with the Wrapper.
abstract java.lang.String	getProtocolName() The name of the Protocol that this wrapper uses
Schema	getSchema() Returns the Schema that represents in the datasource in terms of SchemaObjects in a data source oriented manner.
Schema	getSchema(java.lang.String schemaName) A method that creates in the repository a Schema and AccessMethod from the supplied information, together with a Protocol if necessary, and returns the AccessMethod.
boolean	insertIQL(ASG q) Execute an IQL insert on the datasource.
Schema	newAutoMedSchema(java.lang.String name) Returns the Schema that represents in the datasource in terms of SchemaObjects in an AutoMed oriented manner.
static AutoMedWrapper	newAutoMedWrapper(AccessMethod am) Deprecated. use getAutoMedWrapper(am) instead
static AutoMedWrapper	newAutoMedWrapper(AccessMethod am, java.lang.String password) Deprecated. use getAutoMedWrapper
static void	registerWrapper(java.lang.Class c, Protocol protocol, java.lang.String driver, java.lang.String url) Register an AutoMedWrapper implementation with the AutoMed system.
static AutoMedWrapper	selectNewAutoMedWrapper(java.lang.String username, java.lang.String password, Protocol protocol, java.lang.String driver, java.lang.String url) Using the url and driver information, try to select an appropriate type of AutoMedWrapper to create.
static AutoMedWrapper	selectNewAutoMedWrapper(java.lang.String username, java.lang.String password, Protocol protocol, java.lang.String driver, java.lang.String url, java.lang.String schemaName, AutoMedWrapperFactory wrapperFactory) Using the url and driver information, try to select an appropriate type of AutoMedWrapper to create.
static void	setDebugLevel(int debug) Set the debug level for all AutoMed wrappers.
void	setOption(java.lang.String key, java.lang.String value) Make an option setting.

Methods inherited from class java.lang.Object

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

Field Detail

protocol

protected Protocol protocol

debug

protected static int debug

am

protected AccessMethod am

s

protected Schema s

url

protected java.lang.String url

driver

protected java.lang.String driver

username

protected java.lang.String username

password

protected java.lang.String password

awf

protected AutoMedWrapperFactory awf

Constructor Detail

AutoMedWrapper

public AutoMedWrapper()

Method Detail

setDebugLevel

public static void setDebugLevel(int debug)

Set the debug level for all AutoMed wrappers. A value of 0 ensures no debug information is produced; 10 ensures all debug information is produced.

atDebugLevel

public static boolean atDebugLevel(int level)

Determine is debug is at or above a certain level.

Parameters:

level - to test if debug is at or above

getAccessMethod

public final AccessMethod getAccessMethod()

Returns the AccessMethod associated with this wrapper, which holds the details of the datasource being wrapped.

getSchema

public final Schema getSchema()
                       throws NotFoundException

Returns the Schema that represents in the datasource in terms of SchemaObjects in a data source oriented manner.

Throws:

NotFoundException - if you have not called getSchema(String) on the wrapper previously

getProtocolName

public abstract java.lang.String getProtocolName()

The name of the Protocol that this wrapper uses

connect

protected abstract void connect()
                         throws DataSourceException

Use the connection details held with this wrapper to connect to the data source.

Throws:

DataSourceException - if unable to connect to the data source

getSchema

public final Schema getSchema(java.lang.String schemaName)
                       throws IntegrityException,
                              DataSourceException

A method that creates in the repository a Schema and AccessMethod from the supplied information, together with a Protocol if necessary, and returns the AccessMethod. This may be used to create any number of SQLWrappers for the database. This method is for use by wrapper implementations as part of the wrapper creation process.

Parameters:

schemaName - is the name of the Schema that is used to represent the datasource in AutoMed.

Throws:

IntegrityException - is the schemaName already exists

DataSourceException

getProtocol

public Protocol getProtocol()

Returns the Protocol associated with the Wrapper.

newAutoMedSchema

public final Schema newAutoMedSchema(java.lang.String name)
                              throws IntegrityException,
                                     NotFoundException

Returns the Schema that represents in the datasource in terms of SchemaObjects in an AutoMed oriented manner. This might be the same as the result of getSchema() or might not.

Parameters:

name - of new schema, which must not already exist

Throws:

NotFoundException - if you have not previously wrapped the datasource as a source oriented schema, using either #AutoMedWrapper.getSchema(String) or #AutoMedWrapper.selectNewAutoMedWrapper

IntegrityException

executeLocalQuery

public AutoMedResult executeLocalQuery(AutoMedQuery q)
                                throws DataSourceException

Execute a query in the datasource's native query language, and obtain a result in an AutoMedResult class

DataSourceException

newAutoMedWrapper

public static AutoMedWrapper newAutoMedWrapper(AccessMethod am)
                                        throws DataSourceException

Deprecated. use getAutoMedWrapper(am) instead

DataSourceException

getAutoMedWrapper

public static AutoMedWrapper getAutoMedWrapper(AccessMethod am)
                                        throws DataSourceException

Equivalent to calling newAutoMedWrapper(am,null)

DataSourceException

newAutoMedWrapper

public static AutoMedWrapper newAutoMedWrapper(AccessMethod am,
                                               java.lang.String password)
                                        throws DataSourceException

Deprecated. use getAutoMedWrapper

DataSourceException

registerWrapper

public static void registerWrapper(java.lang.Class c,
                                   Protocol protocol,
                                   java.lang.String driver,
                                   java.lang.String url)

Register an AutoMedWrapper implementation with the AutoMed system. By performing this registration, an AutoMedWrapper will be instantiated when the user uses selectNewAutoMedWrapper(java.lang.String, java.lang.String, uk.ac.ic.doc.automed.reps.Protocol, java.lang.String, java.lang.String).

cacheWrapper

protected void cacheWrapper()

Cache this AutoMedWrapper as being able to provide the implementation of an AccessMethod used to create the wrapper. This means that any call to getAutoMedWrapper(uk.ac.ic.doc.automed.reps.AccessMethod) will return an existing AutoMedWrapper rather than instantiate a new one, which is more efficient. However the AutoMedWrapper will then need to support possibly concurrent execution of queries.

getAutoMedWrapper

public static AutoMedWrapper getAutoMedWrapper(AccessMethod am,
                                               java.lang.String password)
                                        throws DataSourceException

Return the wrapper asspciated to a stored AccessMethod. This method is provided as a convenience, so that the correct implementing wrapper class is found based on details held in the AccessMethod.

Parameters:

am - The AccessMethod which contains the details needed in order to create the wrapper.

password - Any password that the datasource may require to access it. If no password is required, or the password has been stored in the AccessMethod, this may be left null.

Throws:

DataSourceException - if the AccessMethod.getDBDriver() returns a java class for which there is not a known supporting AutoMedWrapper subclass.

selectNewAutoMedWrapper

public static AutoMedWrapper selectNewAutoMedWrapper(java.lang.String username,
                                                     java.lang.String password,
                                                     Protocol protocol,
                                                     java.lang.String driver,
                                                     java.lang.String url)
                                              throws IntegrityException,
                                                     DataSourceException

Using the url and driver information, try to select an appropriate type of AutoMedWrapper to create.

IntegrityException

DataSourceException

selectNewAutoMedWrapper

public static AutoMedWrapper selectNewAutoMedWrapper(java.lang.String username,
                                                     java.lang.String password,
                                                     Protocol protocol,
                                                     java.lang.String driver,
                                                     java.lang.String url,
                                                     java.lang.String schemaName,
                                                     AutoMedWrapperFactory wrapperFactory)
                                              throws IntegrityException,
                                                     DataSourceException

Using the url and driver information, try to select an appropriate type of AutoMedWrapper to create.

IntegrityException

DataSourceException

executeIQL

public abstract ASG executeIQL(ASG q)
                        throws DataSourceException

Execute an IQL query on the datasource.

Parameters:

q - An IQL query held in an ASG which complies with the limitations of what this wrapper is able to process

Returns:

An ASG containing the results of the query

DataSourceException

insertIQL

public boolean insertIQL(ASG q)
                  throws DataSourceException

Execute an IQL insert on the datasource. Note that in later releases this method will become abstract, but at present no Wrapper implements this method.

Parameters:

q - is the ASG representation of an IQL query of the form

sub [t1, ..., tn] s

where:

• 'sub' is the sub-bag builtin function (this has the same semantics as sub-set if operating on sets, which is what the extents of schemes are)
• [t1, ..., tn] are the tuples to be inserted/deleted
• s is the scheme that they will be inserted into/deleted from

The semantics and execution of the insert request will depend on the data source e.g. for a relational database it could be translated into a series of INSERT requests within a single transaction, which may fail or succeeed as a whole (and thus return False or True respectively from the insertIQL method). For a non-transactional repository like the HDM or XML flat files, we may choose to allow partial updates e.g. some of a set of tuples are inserted, while some already exist or violate some constraint or another.

DataSourceException

deleteIQL

public boolean deleteIQL(ASG q)
                  throws DataSourceException

DataSourceException

getDefaultWrapperFactory

protected abstract AutoMedWrapperFactory getDefaultWrapperFactory()

Return the default AutoMedWrapperFactory that is used to generate Schema instances from information in a data sources

getAutoMedWrapperFactory

public AutoMedWrapperFactory getAutoMedWrapperFactory()

Return the AutoMedWrapperFactory currently associated with this wrapper.

getOption

public final java.lang.String getOption(java.lang.String key)

Return an option setting.

setOption

public final void setOption(java.lang.String key,
                            java.lang.String value)

Make an option setting. The options available varying according to which AutoMedWrapper implementation is used.

getOptionKeys

public java.lang.String[] getOptionKeys()

Return the list of option setting key provided by the wrapper factory.