org.apache.turbine.services.db
Interface PoolBrokerService

All Superinterfaces:
Initable, Service
All Known Implementing Classes:
TurbinePoolBrokerService

public interface PoolBrokerService
extends Service

This service provides database connection pooling to Turbine applications. The service can manage a number of connection pools. Each pool is related to a specific database, identified by it's driver class name, url, username and password. The pools may be defined in TurbineResources.properties file, or created at runtime using registerPool(String,String,String,String,String) method.

You can use getConnection(String) to acquire a DBConnection object, which in turn can be used to create java.sql.Statement objects.

When you are done using the DBConnection you must return it to the pool using releaseConnection(DBConnection) method. This method call is often placed in finally clause of a try / catch statement, to ensure that the connection is always returned to the pool.

Version:
$Id$
Author:
Rafal Krzewski

Field Summary
static java.lang.String DEFAULT
          the name of the default pool
static java.lang.String SERVICE_NAME
          the name of the service
 
Method Summary
 DBConnection getConnection()
          This method returns a DBConnection from the default pool.
 DBConnection getConnection(java.lang.String name)
          This method returns a DBConnection from the pool with the specified name.
 DBConnection getConnection(java.lang.String driver, java.lang.String url, java.lang.String username, java.lang.String password)
          Deprecated. Database parameters should not be specified each time a DBConnection is fetched from the service.
 DB getDB()
          Returns the database adapter for the default connection pool.
 DB getDB(java.lang.String name)
          Returns database adapter for a specific connection pool.
 void registerPool(java.lang.String name, java.lang.String driver, java.lang.String url, java.lang.String username, java.lang.String password)
          This method registers a new pool using the given parameters.
 void releaseConnection(DBConnection dbconn)
          Release a connection back to the database pool.
 
Methods inherited from interface org.apache.turbine.services.Service
getConfiguration, getProperties, setName, setServiceBroker
 
Methods inherited from interface org.apache.turbine.services.Initable
getInit, init, init, setInitableBroker, shutdown
 

Field Detail

SERVICE_NAME

public static final java.lang.String SERVICE_NAME
the name of the service

DEFAULT

public static final java.lang.String DEFAULT
the name of the default pool
Method Detail

getConnection

public DBConnection getConnection()
                           throws java.lang.Exception
This method returns a DBConnection from the default pool.
Returns:
The requested connection.
Throws:
TurbineException - Any exceptions caught during processing will be rethrown wrapped into a TurbineException.

getConnection

public DBConnection getConnection(java.lang.String name)
                           throws java.lang.Exception
This method returns a DBConnection from the pool with the specified name. The pool must either have been registered with the registerPool(String,String,String,String,String) method, or be specified in the property file using the following syntax:
 database.[name].driver
 database.[name].url
 database.[name].username
 database.[name].password
 
Parameters:
name - The name of the pool to get a connection from.
Returns:
The requested connection.
Throws:
TurbineException - Any exceptions caught during processing will be rethrown wrapped into a TurbineException.

getConnection

public DBConnection getConnection(java.lang.String driver,
                                  java.lang.String url,
                                  java.lang.String username,
                                  java.lang.String password)
                           throws java.lang.Exception
Deprecated. Database parameters should not be specified each time a DBConnection is fetched from the service.

This method returns a DBConnecton using the given parameters.
Parameters:
driver - The fully-qualified name of the JDBC driver to use.
url - The URL of the database from which the connection is desired.
username - The name of the database user.
password - The password of the database user.
Returns:
A DBConnection.
Throws:
TurbineException - Any exceptions caught during processing will be rethrown wrapped into a TurbineException.

releaseConnection

public void releaseConnection(DBConnection dbconn)
                       throws java.lang.Exception
Release a connection back to the database pool.
Throws:
TurbineException - Any exceptions caught during processing will be rethrown wrapped into a TurbineException.
java.lang.Exception - A generic exception.

registerPool

public void registerPool(java.lang.String name,
                         java.lang.String driver,
                         java.lang.String url,
                         java.lang.String username,
                         java.lang.String password)
                  throws java.lang.Exception
This method registers a new pool using the given parameters.
Parameters:
name - The name of the pool to register.
driver - The fully-qualified name of the JDBC driver to use.
url - The URL of the database to use.
username - The name of the database user.
password - The password of the database user.
Throws:
TurbineException - Any exceptions caught during processing will be rethrown wrapped into a TurbineException.

getDB

public DB getDB()
         throws java.lang.Exception
Returns the database adapter for the default connection pool.
Returns:
The database adapter.
Throws:
TurbineException - Any exceptions caught during processing will be rethrown wrapped into a TurbineException.

getDB

public DB getDB(java.lang.String name)
         throws java.lang.Exception
Returns database adapter for a specific connection pool.
Parameters:
name - A pool name.
Returns:
The corresponding database adapter.
Throws:
TurbineException - Any exceptions caught during processing will be rethrown wrapped into a TurbineException.


Copyright © 1999-2001 Apache Software Foundation. All Rights Reserved.