org.opensubsystems.core.persist.db
Interface DatabaseConnectionFactory

All Known Implementing Classes:
C3P0DatabaseConnectionFactoryImpl, DatabaseConnectionFactoryImpl, DBCPDatabaseConnectionFactoryImpl, J2EEDatabaseConnectionFactoryImpl, PooledDatabaseConnectionFactoryImpl, ProxoolDatabaseConnectionFactoryImpl, XAPoolDatabaseConnectionFactoryImpl

public interface DatabaseConnectionFactory

Interface to encapsulate retrieving and returning of database connections. Data connection factory is here to implement the Abstract Factory pattern as described in http://homepage.mac.com/loeffler/java/patterns/absfac.html by GoF95 http://homepage.mac.com/loeffler/java/patterns.html. The main reason is that database connections can be managed in different ways: they may be always opened when requested or pooled and retrieved from the pool, they might be created by the driver or retrieved from the data source. This interface provides unified way how to access the database connection regardless of implementation.

Version:
$Id: DatabaseConnectionFactory.java,v 1.15 2007/01/07 06:14:18 bastafidli Exp $
Author:
Miro Halas
Code reviewer:
Miro Halas
Code reviewed:
1.13 2006/05/21 03:40:47 bastafidli

Method Summary
 void addDataSource(java.lang.String strDataSourceName, java.lang.String strDriverName, java.lang.String strUrl, java.lang.String strUser, java.lang.String strPassword)
          Create new data source.
 java.lang.String debug()
          Create string representing state of the factory so we can user it to debug connection related problems.
 java.lang.String getDatabaseAdminPassword()
          Returns the database administration password.
 java.lang.String getDatabaseAdminUser()
          Returns the database administration user.
 java.lang.String getDatabaseDriver()
          Returns the database driver identification.
 java.lang.String getDatabasePassword()
          Returns the database password.
 java.lang.String getDatabaseURL()
          Returns the database URL.
 java.lang.String getDatabaseUser()
          Returns the database user.
 java.lang.String getDefaultDataSourceName()
          Get the name of the default data source.
 java.lang.String getRealDatabaseDriver()
          Get real driver name which is used to connect to database.
 int getRequestedConnectionCount()
          Get number for connections which are currently requested and were not returned for default data source.
 int getRequestedConnectionCount(java.lang.String strDataSourceName)
          Get number for connections which are currently requested and were not returned.
 int getTotalRequestedConnectionCount()
          Get total number for connections (for all data sources) which are currently requested and were not returned.
 boolean getUseAdminDataSource()
          Get the flag specifying if to use separate datasource instead just different creadentials to obtain administrator connection.
 boolean isDataSourceDefined(java.lang.String strDataSourceName)
          Check if the specified data has been already defined
 void loadDefaultDatabaseProperties()
          Load default database properties such as what driver, user name or password to use from configuration file.
 java.sql.Connection requestConnection(boolean bAutoCommit)
          Get connection to a database as configured by the default data source.
 java.sql.Connection requestConnection(boolean bAutoCommit, java.lang.String strDataSourceName)
          Get connection to a database as configured by the default data source.
 java.sql.Connection requestConnection(boolean bAutoCommit, java.lang.String strUser, java.lang.String strPassword)
          Get connection to a database as configured by the default data source but using explicit user credential.
 java.sql.Connection requestConnection(boolean bAutoCommit, java.lang.String strDataSourceName, java.lang.String strUser, java.lang.String strPassword)
          Get connection to a database as configured by the default data source but using explicit user credential.
 void returnConnection(java.sql.Connection cntDBConnection)
          Release connection to a database.
 void setDatabaseAdminPassword(java.lang.String strDatabasePassword)
          Sets the database administration password.
 void setDatabaseAdminUser(java.lang.String strDatabaseUser)
          Sets the database administration user.
 void setDatabaseDriver(java.lang.String strDatabaseDriver)
          Sets the database driver identification.
 void setDatabasePassword(java.lang.String strDatabasePassword)
          Sets the database password.
 void setDatabaseURL(java.lang.String strDatabaseURL)
          Sets the database URL.
 void setDatabaseUser(java.lang.String strDatabaseUser)
          Sets the database user.
 void setDefaultDataSourceName(java.lang.String strDataSourceName)
          Set the default data source.
 void setUseAdminDataSource(boolean bUseAdminDataSource)
          Sets the flag specifying if to use separate datasource instead just different creadentials to obtain administrator connection.
 void stop()
          Stop the connection factory.
 

Method Detail

requestConnection

java.sql.Connection requestConnection(boolean bAutoCommit)
                                      throws OSSDatabaseAccessException
Get connection to a database as configured by the default data source. The connection has to be explicitely returned using returnConnection most likely in finalize clause.

Parameters:
bAutoCommit - - The desired autocommit state of the connection. If this connection is invoked in global (JTA) transaction then the autocommit is false regardless of what value is specified here. Use true here if the client only reads the data and false if the client also modifies the data. Use DatabaseTransactionFactory.commitTransaction to commit the transaction.
Returns:
Connection - connection to a database, never null
Throws:
OSSDatabaseAccessException - - if connection cannot be established
See Also:
returnConnection(java.sql.Connection)

requestConnection

java.sql.Connection requestConnection(boolean bAutoCommit,
                                      java.lang.String strUser,
                                      java.lang.String strPassword)
                                      throws OSSDatabaseAccessException
Get connection to a database as configured by the default data source but using explicit user credential. The connection has to be explicitely returned using returnConnection most likely in finalize clause.

Parameters:
bAutoCommit - - The desired autocommit state of the connection. If this connection is invoked in global (JTA) transaction then the autocommit is false regardless of what value is specified here. Use true here if the client only reads the data and false if the client also modifies the data. Use DatabaseTransactionFactory.commitTransaction to commit the transaction.
strUser - - user name to connect to the database
strPassword - - password to the database
Returns:
Connection - connection to a database, never null
Throws:
OSSDatabaseAccessException - - if connection cannot be established
See Also:
returnConnection(java.sql.Connection)

requestConnection

java.sql.Connection requestConnection(boolean bAutoCommit,
                                      java.lang.String strDataSourceName)
                                      throws OSSDatabaseAccessException
Get connection to a database as configured by the default data source. The connection has to be explicitely returned using returnConnection most likely in finalize clause. This connection has autocommit set to true so if you do not want to autocommit you need to explicitely reset it. This is mainly because if selects are executed without transaction and transaction isolation is set to for example serializable, it can come to a deadlock since the select may block table when different connection tries to modify it.

Parameters:
bAutoCommit - - The desired autocommit state of the connection. If this connection is invoked in global (JTA) transaction then the autocommit is false regardless of what value is specified here. Use true here if the client only reads the data and false if the client also modifies the data. Use DatabaseTransactionFactory.commitTransaction to commit the transaction.
strDataSourceName - - data source which will be used to get connections
Returns:
Connection - connection to a database, never null
Throws:
OSSDatabaseAccessException - - if connection cannot be established
See Also:
returnConnection(java.sql.Connection)

requestConnection

java.sql.Connection requestConnection(boolean bAutoCommit,
                                      java.lang.String strDataSourceName,
                                      java.lang.String strUser,
                                      java.lang.String strPassword)
                                      throws OSSDatabaseAccessException
Get connection to a database as configured by the default data source but using explicit user credential. The connection has to be explicitely returned using returnConnection most likely in finalize clause. This connection has autocommit set to true so if you do not want to autocommit you need to explictely reset it. This is mainly because if selects are executed without transaction and transaction isolation is set to for example serializable, it can come to a deadlock since the select may block table when different connection tries to modify it.

Parameters:
bAutoCommit - - The desired autocommit state of the connection. If this connection is invoked in global (JTA) transaction then the autocommit is false regardless of what value is specified here. Use true here if the client only reads the data and false if the client also modifies the data. Use DatabaseTransactionFactory.commitTransaction to commit the transaction.
strDataSourceName - - data source which will be used to get connections
strUser - - user name to connect to the database
strPassword - - password to the database
Returns:
Connection - connection to a database, never null
Throws:
OSSDatabaseAccessException - - if connection cannot be established
See Also:
returnConnection(java.sql.Connection)

returnConnection

void returnConnection(java.sql.Connection cntDBConnection)
Release connection to a database.

Parameters:
cntDBConnection - - connection to a database to release, may be null
See Also:
requestConnection(boolean)

getDatabaseDriver

java.lang.String getDatabaseDriver()
Returns the database driver identification.

Returns:
String

setDatabaseDriver

void setDatabaseDriver(java.lang.String strDatabaseDriver)
Sets the database driver identification.

Parameters:
strDatabaseDriver - - The database driver to set

getRealDatabaseDriver

java.lang.String getRealDatabaseDriver()
Get real driver name which is used to connect to database. This can be wrapped for example in a spy driver.

Returns:
String - real JDBC driver name.

getDatabasePassword

java.lang.String getDatabasePassword()
Returns the database password.

Returns:
String

setDatabasePassword

void setDatabasePassword(java.lang.String strDatabasePassword)
Sets the database password.

Parameters:
strDatabasePassword - - The database password to set

getDatabaseURL

java.lang.String getDatabaseURL()
Returns the database URL.

Returns:
String

setDatabaseURL

void setDatabaseURL(java.lang.String strDatabaseURL)
Sets the database URL.

Parameters:
strDatabaseURL - - The database URL to set

getDatabaseUser

java.lang.String getDatabaseUser()
Returns the database user.

Returns:
String

setDatabaseUser

void setDatabaseUser(java.lang.String strDatabaseUser)
Sets the database user.

Parameters:
strDatabaseUser - - The database user to set

getDatabaseAdminUser

java.lang.String getDatabaseAdminUser()
Returns the database administration user.

Returns:
String

setDatabaseAdminUser

void setDatabaseAdminUser(java.lang.String strDatabaseUser)
Sets the database administration user.

Parameters:
strDatabaseUser - - The database user to set

getDatabaseAdminPassword

java.lang.String getDatabaseAdminPassword()
Returns the database administration password.

Returns:
String

setDatabaseAdminPassword

void setDatabaseAdminPassword(java.lang.String strDatabasePassword)
Sets the database administration password.

Parameters:
strDatabasePassword - - The database password to set

getUseAdminDataSource

boolean getUseAdminDataSource()
Get the flag specifying if to use separate datasource instead just different creadentials to obtain administrator connection.

Returns:
boolean - if true then separate datasource shoud be used for administration connection

setUseAdminDataSource

void setUseAdminDataSource(boolean bUseAdminDataSource)
Sets the flag specifying if to use separate datasource instead just different creadentials to obtain administrator connection.

Parameters:
bUseAdminDataSource - - if true then separate datasource shoud be used for administration connection

loadDefaultDatabaseProperties

void loadDefaultDatabaseProperties()
                                   throws OSSConfigException,
                                          OSSDatabaseAccessException
Load default database properties such as what driver, user name or password to use from configuration file.

Throws:
OSSConfigException - - problem locating or accessing config file
OSSDatabaseAccessException - - problem accessing the database

addDataSource

void addDataSource(java.lang.String strDataSourceName,
                   java.lang.String strDriverName,
                   java.lang.String strUrl,
                   java.lang.String strUser,
                   java.lang.String strPassword)
                   throws OSSDatabaseAccessException
Create new data source. If it doesn't exist, it will be created.

Parameters:
strDataSourceName - - data source name
strDriverName - - name of the JDBC driver
strUrl - - url by which data source connects to the database
strUser - - user name to connects to the database
strPassword - - password to connects to the database
Throws:
OSSDatabaseAccessException - - data source with the same name already exists

setDefaultDataSourceName

void setDefaultDataSourceName(java.lang.String strDataSourceName)
Set the default data source.

Parameters:
strDataSourceName - - data source which will be used to get connections

getDefaultDataSourceName

java.lang.String getDefaultDataSourceName()
Get the name of the default data source.

Returns:
String

isDataSourceDefined

boolean isDataSourceDefined(java.lang.String strDataSourceName)
Check if the specified data has been already defined

Parameters:
strDataSourceName - - name of the data source to check for
Returns:
boolean - true if the data source is already defined, false otherwise

stop

void stop()
          throws OSSException
Stop the connection factory. After the connection factory is stopped all the connections should be released and they cannot be retrieved unless the connection factory is reinitialized in some way.

Throws:
OSSException - - problem stopping connection factory.

getTotalRequestedConnectionCount

int getTotalRequestedConnectionCount()
Get total number for connections (for all data sources) which are currently requested and were not returned.

Returns:
int - how many connections were currently requested from pool and were not returned yet.

getRequestedConnectionCount

int getRequestedConnectionCount()
Get number for connections which are currently requested and were not returned for default data source.

Returns:
int - how many connections were currently requested from pool and were not returned yet.

getRequestedConnectionCount

int getRequestedConnectionCount(java.lang.String strDataSourceName)
Get number for connections which are currently requested and were not returned.

Parameters:
strDataSourceName - - data source which will be used to get connections
Returns:
int - how many connections were currently requested from pool and were not returned yet.

debug

java.lang.String debug()
Create string representing state of the factory so we can user it to debug connection related problems.

Returns:
String - state of the connection factory.


Copyright © 2003 - 2006 OpenSubsystems s.r.o.