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

java.lang.Object
  uk.ac.ic.doc.automed.wrappers.AutoMedWrapper

Direct Known Subclasses:

CSVWrapper, HdmWrapper, HDMWrapper, P2PWrapper, QueryCacheWrapper, SQLWrapper, XMLSchemaWrapper, 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 a wrapper is deligated to implementions of this class. Thus AutoMedWrapper is a foundation class for AutoMed wrappers to be built upon. All valid implementations of this class must provide two constructors, one with no arguements, and one that takes an AccessMethod and String representing a password (that if not null overrides any password held in the AccessMethod. The PostgresWrapper and associated PostgresWrapperFactory can be used examples of correctly structured wrappers.

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 static boolean[]	emptyKeyProtection
protected static java.lang.String[]	emptyKeys
protected boolean[]	optionKeyProtection
protected java.lang.String[]	optionKeys
protected java.lang.String	password
protected Protocol	protocol
protected Schema	s
protected java.lang.String	url
protected java.lang.String	username

Constructor Summary

protected	AutoMedWrapper()
	AutoMedWrapper(AccessMethod am, java.lang.String password) Generate a new wrapper instance from information held in the repository about how to access a data source.

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.
ASG	executeIQL(ASG q, java.lang.String queryID) 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
static java.lang.Object[]	getDrivers() Returns all the drivers currently loaded into the system
java.lang.String	getOption(java.lang.String key) Return an option setting.
boolean[]	getOptionKeyProtection() Return the list of boolean values that indicate if the value associated with a key should be altered by a user application.
java.lang.String[]	getOptionKeys() Return the list of options keys that this wrapper understands.
Protocol	getProtocol() Returns the Protocol associated with the Wrapper.
abstract java.lang.String	getProtocolName() The name of the Protocol that this wrapper uses
static DefaultQueryCache	getQueryCache() Return a unique reference to the query cache
static DefaultQueryCache	getQueryCache(java.lang.String peerName, java.lang.String schemaName)
QueryParser	getQueryParser(ASG query) Return a parser that will accept queries for the wrapper.
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.
abstract void	getSODefinition(QuerySubGoal qsg) An abstract method used by #getSOQuality(String schemeDef).
QuerySubGoal	getSODefinition(java.lang.String schemeDef) Calculate the quality of a schema object.
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 AutoMedWrapper	newAutoMedWrapper(java.lang.String username, java.lang.String password, java.lang.String driver, java.lang.String url, java.lang.String schemaName, AutoMedWrapperFactory awf) Create an AutoMed Schema containing SchemaObjects that represent a database, in such a form that queries on that schema can be mapped by executeQuery in the query lanuage of the database.
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.
protected void	updateCache(java.lang.String queryID, ASG subQuery, ASG result) Update query cache as queries are executed over the data source.

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

emptyKeys

protected static final java.lang.String[] emptyKeys

emptyKeyProtection

protected static final boolean[] emptyKeyProtection

optionKeys

protected java.lang.String[] optionKeys

optionKeyProtection

protected boolean[] optionKeyProtection

Constructor Detail

AutoMedWrapper

protected AutoMedWrapper()

AutoMedWrapper

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

Generate a new wrapper instance from information held in the repository about how to access a data source. Note that a suitable access AccessMethod and Schema can be created using TransactSQLWrapperFactory#build

Throws:

DataSourceException

Method Detail

getQueryParser

public QueryParser getQueryParser(ASG query)

Return a parser that will accept queries for the wrapper. The default parser is Schemes, which accepts only single schemes, with no other IQL operators supported. The SimpleComp parser will allow simple list comprehensions to be passed to the wrapper.

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

Throws:

DataSourceException

newAutoMedWrapper

public static AutoMedWrapper newAutoMedWrapper(AccessMethod am)
                                        throws DataSourceException

Deprecated. use getAutoMedWrapper(am) instead

Throws:

DataSourceException

newAutoMedWrapper

public static AutoMedWrapper newAutoMedWrapper(java.lang.String username,
                                               java.lang.String password,
                                               java.lang.String driver,
                                               java.lang.String url,
                                               java.lang.String schemaName,
                                               AutoMedWrapperFactory awf)
                                        throws IntegrityException,
                                               DataSourceException

Create an AutoMed Schema containing SchemaObjects that represent a database, in such a form that queries on that schema can be mapped by executeQuery in the query lanuage of the database. This should be called once per data source, so as to configure the repository. Subsequent uses of the data source should call the constructor for AutoMedWrapper instance with the AccessMethod of the AutoMedWrapper returned here.

Parameters:

schemaName - is the name of the Schema to create in the repository to represent the data source. If this is left null then a connection is established to the data source, and the Schema may be created later using getSchema(String)

awf - is an AutoMedWrapperFactory instance configured to model the source schema in the desired manner.

Throws:

IntegrityException

DataSourceException

getAutoMedWrapper

public static AutoMedWrapper getAutoMedWrapper(AccessMethod am)
                                        throws DataSourceException

Equivalent to calling newAutoMedWrapper(am,null)

Throws:

DataSourceException

newAutoMedWrapper

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

Deprecated. use getAutoMedWrapper

Throws:

DataSourceException

getDrivers

public static java.lang.Object[] getDrivers()

Returns all the drivers currently loaded into the system

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.

Throws:

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.

Throws:

IntegrityException

DataSourceException

executeIQL

public abstract ASG executeIQL(ASG q)
                        throws DataSourceException,
                               NotFoundException

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

Throws:

DataSourceException

NotFoundException

executeIQL

public ASG executeIQL(ASG q,
                      java.lang.String queryID)
               throws DataSourceException,
                      NotFoundException

Execute an IQL query on the datasource. It differs from executeIQL(ASG q) in that it accepts an unique query ID argument which is used for updating query result to cache.

Parameters:

queryID - an unique query identifier (generated by the query cache)

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

Throws:

DataSourceException

NotFoundException

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.

Throws:

DataSourceException

deleteIQL

public boolean deleteIQL(ASG q)
                  throws DataSourceException

Throws:

DataSourceException

getSODefinition

public QuerySubGoal getSODefinition(java.lang.String schemeDef)
                             throws IntegrityException,
                                    DataSourceException

Calculate the quality of a schema object. Depending on the type of schema that this object is attached to, the wrapper class will decide whether to access its local database or to ask the remote peer for the object quality. This is a recursive process!
This method has the scope public so other classes can call it directly passing a scheme definition of the form schema_name:schema_object_name. For instance, a scheme definition would be uni_s1:<>. This method the parses this scheme definition into schema and scheme name and calls #getSOQuality(Schema s, String schemeName) method of the sub-class wrapper to do the job.
This method is typically used by the QueryMediator class and the query optimisation process.

Parameters:

quality - a List object of the aggregated quality values

schemeDef - the scheme definition of the schema object (e.g. uni_s1:<>)

Returns:

List an aggregated list of quality values

Throws:

IntegrityException

DataSourceException

getSODefinition

public abstract void getSODefinition(QuerySubGoal qsg)
                              throws DataSourceException

An abstract method used by #getSOQuality(String schemeDef). This method must be implemented by all sub-classes

Parameters:

List -

Throws:

DataSourceException

updateCache

protected void updateCache(java.lang.String queryID,
                           ASG subQuery,
                           ASG result)
                    throws AutoMedException

Update query cache as queries are executed over the data source. This method
is only available for wrapper classes so that individual wrappers may opt to
override it if needed.

Parameters:

queryID - the unique query identifier (generated by the query cache)

subQuery - the actual query that is being evaluated. It is a sub-set
of query identified by queryID

result - the ASG representation of query result

Throws:

AutoMedException

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.

getOptionKeys

public final java.lang.String[] getOptionKeys()

Return the list of options keys that this wrapper understands. You may set and get any key you wish, but only the ones returned by this method will alter the behaviour of the wrapper.

getOptionKeyProtection

public final boolean[] getOptionKeyProtection()

Return the list of boolean values that indicate if the value associated with a key should be altered by a user application. Some values are set to indicate the state of the wrapped data source, and altering those values will not change the state of the wrapper. Hence it is recommended not to change those values. A value of true in the array indidcates that the corresponding key from getOptionKeys() should not be used in setOption. At present this is not enforced, but that might change in the future.

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.

getQueryCache

public static DefaultQueryCache getQueryCache()
                                       throws CacheException

Return a unique reference to the query cache

Throws:

CacheException

getQueryCache

public static DefaultQueryCache getQueryCache(java.lang.String peerName,
                                              java.lang.String schemaName)
                                       throws CacheException

Throws:

CacheException