AutoMedWrapper
Keywords: uk.ac.ic.doc.automed.wrappers.AutoMedWrapper class

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

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

Direct Known Subclasses:
  HdmWrapper, HDMWrapper, P2PWrapper, SQLWrapper, XindiceWrapper, 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.
`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
`uk.ac.bbk.dcs.automed.qproc.annotate.grammars.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 `SchemaObject`s 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 `SchemaObject`s 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 `SchemaObject`s 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.

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 uk.ac.bbk.dcs.automed.qproc.annotate.grammars.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 `SchemaObject`s 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 `SchemaObject`s 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 `SchemaObject`s 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`

### 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`

### 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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD