gate.db
Class Database

java.lang.Object
  |
  +--gate.util.AbstractFeatureBearer
        |
        +--gate.persist.SerialDataStore
              |
              +--gate.db.Database
All Implemented Interfaces:
DataStore, FeatureBearer
Direct Known Subclasses:
OracleDataStore, PostgresDataStore

public class Database
extends SerialDataStore

Objects of type Database are used to connect to a database. They hold all the necessary information for accessing the database and provide services to client objects (i.e. persistent language resources).


Field Summary
static int TRANSACTION_LEVEL
           
 
Constructor Summary
Database(Driver driver, String url, String user, String password, String catalog, String schema)
          Constructs an object of type database.
 
Method Summary
 void deleteFeaturesOf(long ownerId, Connection con)
          Deletes from the Gate2 database all the features belonging to the object with the given id.
 String getCatalog()
          Returns the 'catalog' associated with this database object.
 Connection getConnection()
          This method is used by the clients of this Database object in order to gain access to the database.
 Map getDictionary()
           
 FeatureMap getFeatures()
          Gets the features of this datastore.
 String getSchema()
          Returns the 'schema' value associated with this database object.
 boolean isConnected()
          Used to find out if this Database object is actually connected to a database.
 void putObject(PreparedStatement ps, int place, Object value)
          Acts as a setBlob for the provided prepared statement on the position indicated by place.
 FeatureMap readFeaturesOf(long ownerId, Connection con)
          This method reads (from the Gate2 database) the features of the object bearing the given ID.
 Object readObjectBlob(ResultSet rs, Connection con, String columnName)
          Reads a Object from a BLOB on the current row in a result set.
 void release()
          Frees the allocated resources (closes all the open connections).
 void setFeatures(FeatureMap features)
          Sets the features of this datastore.
 void takeBackConnection(Connection con)
          Takes back a previously supplied connection and makes it available for other clients.
 void writeFeaturesOf(long ownerId, FeatureMap featuresToWrite, Connection con)
          This method writes the given FeatureMap as features belonging to the object with the given offset.
 
Methods inherited from class gate.persist.SerialDataStore
addDatastoreListener, adopt, close, create, delete, delete, equals, getLr, getLrIds, getLrName, getLrNames, getLrTypes, getStorageDir, getStorageUrl, hashCode, isAutoSaving, open, removeDatastoreListener, setAutoSaving, setStorageDir, setStorageUrl, sync, toString
 
Methods inherited from class gate.util.AbstractFeatureBearer
getName, setName
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface gate.util.FeatureBearer
getName, setName
 

Field Detail

TRANSACTION_LEVEL

public static int TRANSACTION_LEVEL
Constructor Detail

Database

public Database(Driver driver,
                String url,
                String user,
                String password,
                String catalog,
                String schema)
Constructs an object of type database.
Parameters:
driver - an object of type java.sql.Driver. The driver used for JDBC access to the database.
url - the JDBC url that identifies the database this object should connect to.
user - The user name for accessing the database.
password - The passwordfor accessing the database.
catalog - The catalog where the tables will be found.
schema - The schema where the tables will be found.
Method Detail

getConnection

public Connection getConnection()
This method is used by the clients of this Database object in order to gain access to the database.
Returns:
an object of type java.sql.Connection providing access to the Database that this Database object is associated to. If this object is not yet connected to the physical database, the first call of getConnection will also make the Jdbc connection to the database. All connections obtained via this method should be returned using takeBackConnection().

takeBackConnection

public void takeBackConnection(Connection con)
                        throws GateException
Takes back a previously supplied connection and makes it available for other clients.
Parameters:
con - the connection being returned. If the connection was not provided by this Database object, an exception will be raised.

setFeatures

public void setFeatures(FeatureMap features)
Sets the features of this datastore.
Overrides:
setFeatures in class AbstractFeatureBearer
Parameters:
features - a value of type 'FeatureMap'

getFeatures

public FeatureMap getFeatures()
Gets the features of this datastore.
Overrides:
getFeatures in class AbstractFeatureBearer
Returns:
a value of type 'FeatureMap'

isConnected

public boolean isConnected()
Used to find out if this Database object is actually connected to a database.
Returns:
true if it is connected, false otherwise.

release

public void release()
             throws OpenTransactionsException
Frees the allocated resources (closes all the open connections).
Throws:
OpenTransactionsException - if there are any connections that haven't been returned by the clients of this database.

readObjectBlob

public Object readObjectBlob(ResultSet rs,
                             Connection con,
                             String columnName)
                      throws SQLException,
                             IOException
Reads a Object from a BLOB on the current row in a result set. Note that the Blob must contain a java Object saved using serialisation. The implemetation at this level coresponds to a generic Jdbc source. More efficient implemetations for this action can be found in classes derived from this class taht are dedicated to sepecific types of Jdbc sources (e.g. gate.db.OracledataStore).
Parameters:
rs - a result set positioned on the row from which the BLOB is to be read
columnName - the name of the column containing the BLOB on the current row.
Returns:
an object containing the blob.
Throws:
SQLException - if an error occurs.

putObject

public void putObject(PreparedStatement ps,
                      int place,
                      Object value)
               throws SQLException,
                      IOException
Acts as a setBlob for the provided prepared statement on the position indicated by place.
Parameters:
ps - A prepared statement where the blob will be set.
place - The position on the prepared statement where the blob will be set.
value - The object that will be serialised and converted into a blob.

readFeaturesOf

public FeatureMap readFeaturesOf(long ownerId,
                                 Connection con)
                          throws SQLException,
                                 IOException
This method reads (from the Gate2 database) the features of the object bearing the given ID.
Parameters:
ownerId - a value of type 'long' representing the id of the object for which the features are to be retrieved.
con - a value of type 'Connection' which should be connceted to the database from which the features are to be read.
Returns:
a value of type 'FeatureMap'
Throws:
SQLException - if an error occurs

writeFeaturesOf

public void writeFeaturesOf(long ownerId,
                            FeatureMap featuresToWrite,
                            Connection con)
                     throws SQLException,
                            IOException
This method writes the given FeatureMap as features belonging to the object with the given offset.
Parameters:
ownerId - a value of type 'long' representing the offset of the owner of the feature map.
featuresToWrite - the FeatureMap to be written.
con - A connection to the Gate2 database.
Throws:
SQLException - if an error occurs

deleteFeaturesOf

public void deleteFeaturesOf(long ownerId,
                             Connection con)
                      throws SQLException
Deletes from the Gate2 database all the features belonging to the object with the given id.
Parameters:
ownerId - a value of type 'long' representing the database ID of the object for which the features are to be erased.
con - a connection to the Gate2 database.
Throws:
SQLException - if an error occurs

getCatalog

public String getCatalog()
Returns the 'catalog' associated with this database object.
Returns:
a value of type 'String'

getSchema

public String getSchema()
Returns the 'schema' value associated with this database object.
Returns:
a value of type 'String'

getDictionary

public Map getDictionary()