org.opennms.core.resource.db
Interface DbConnectionFactory

All Known Implementing Classes:

DataSourceDbConnectionFactory, SimpleDbConnectionFactory

public interface DbConnectionFactory

A DbConnectionFactory allocates and deallocates connections from a database. The concrete implementations of this interface specify a particular allocation/deallocation policy.

For example, an implementation might use and reuse connections from a persistent pool of connections, while another might dynamically allocate and deallocate connections for each request.

Version:

$Id: $

Author:

Lawrence Karnowski , OpenNMS , Lawrence Karnowski , OpenNMS

Method Summary

void	destroy() Deallocate all the resources that may have been allocated to this database connection factory.
Connection	getConnection() Retrieve a connection from the given database connection pool.
void	init(String dbUrl, String dbDriver, String username, String password) Initialize a database factory with the given URL, driver classname, and database credentials.
void	releaseConnection(Connection connection) Replace a database connection back in the pool of available connections for its parent pool.

Method Detail

init

void init(String dbUrl,
          String dbDriver,
          String username,
          String password)
          throws ClassNotFoundException,
                 SQLException

Initialize a database factory with the given URL, driver classname, and database credentials. Will guarantee that the JDBC driver is loaded and that connections will be available.

Only one init method should be called.

Parameters:

dbUrl - the JDBC URL used to retrieve connections

dbDriver - a fully qualified class name for the JDBC driver that will handle this JDBC URL

username - the name to use to authenticate us with the database

password - the credentials use to authenticate the username

Throws:

ClassNotFoundException - if any.

SQLException - if any.

destroy

void destroy()
             throws SQLException

Deallocate all the resources that may have been allocated to this database connection factory. Makes this factory unavailable for new connection requests.

Throws:

SQLException - if any.

getConnection

Connection getConnection()
                         throws SQLException

Retrieve a connection from the given database connection pool.

Returns:

a Connection object.

Throws:

IllegalStateException - If the factory has not been initialized or has been destroyed.

SQLException - if any.

releaseConnection

void releaseConnection(Connection connection)
                       throws SQLException

Replace a database connection back in the pool of available connections for its parent pool.

Parameters:

connection - the connection to release

Throws:

IllegalStateException - If the factory has not been initialized or has been destroyed.

SQLException - if any.