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.