AutoMedWrapper
Keywords: uk.ac.ic.doc.automed.wrappers.AutoMedWrapper,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, 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 `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 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 `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

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

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