org.apache.turbine.services.db
Class TurbineDB

java.lang.Object
  |
  +--org.apache.turbine.services.db.TurbineDB

public abstract class TurbineDB
extends java.lang.Object

This class provides a common front end to all database - related services in Turbine. Currently these are PoolBrokerService and MapBrokerService. This class contains static methods that you can call to access the methods of system's configured service implementations.

Assuming that your TurbineResources.properties file is setup correctly, the sample code below demonstrates the right way to get and release a database connection (exception handling is application dependent):

 DBConnection dbConn = null;
 try
 {
     dbConn = TurbineDB.getConnection();
     // Do something with the connection here...
 }
 catch (Exception e)
 {
     // Either from obtaining the connection or from your application code.
 }
 finally
 {
     try
     {
         TurbineDB.releaseConnection(dbConn);
     }
     catch (Exception e)
     {
         // Error releasing database connection back to pool.
     }
 }
 

Version:
$Id: TurbineDB.java,v 1.3 2001/09/27 06:02:39 jvanzyl Exp $
Author:
Rafal Krzewski

Constructor Summary
TurbineDB()
           
 
Method Summary
static DBConnection getConnection()
          This method returns a DBConnection from the default pool.
static DBConnection getConnection(java.lang.String name)
          This method returns a DBConnection from the pool with the specified name.
static 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.
static DatabaseMap getDatabaseMap()
          Returns the default database map information.
static DatabaseMap getDatabaseMap(java.lang.String name)
          Returns the database map information.
static DB getDB()
          Returns the database adapter for the default connection pool.
static DB getDB(java.lang.String name)
          Returns database adapter for a specific connection pool.
static java.lang.String getDefaultDB()
          Returns the pool name for the default database.
static java.lang.String getDefaultMap()
          Returns the map name for the default database.
private static MapBrokerService getMapBroker()
          Returns the system's configured MapBrokerService implementation.
private static PoolBrokerService getPoolBroker()
          Returns the system's configured PoolBrokerService implementation.
static 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.
static void releaseConnection(DBConnection dbconn)
          Release a connection back to the database pool.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Constructor Detail

TurbineDB

public TurbineDB()
Method Detail

getDefaultMap

public static java.lang.String getDefaultMap()
Returns the map name for the default database.
Returns:
the map name for the default database.

getDatabaseMap

public static DatabaseMap getDatabaseMap()
                                  throws TurbineException
Returns the default database map information.
Returns:
A DatabaseMap.
Throws:
TurbineException - Any exceptions caught during processing will be rethrown wrapped into a TurbineException.

getDatabaseMap

public static DatabaseMap getDatabaseMap(java.lang.String name)
                                  throws TurbineException
Returns the database map information. Name relates to the name of the connection pool to associate with the map.
Parameters:
name - The name of the DatabaseMap to retrieve.
Returns:
The named DatabaseMap.
Throws:
TurbineException - Any exceptions caught during processing will be rethrown wrapped into a TurbineException.

getDefaultDB

public static java.lang.String getDefaultDB()
Returns the pool name for the default database.
Returns:
the pool name for the default database.

getConnection

public static 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 static 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 static 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 static 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 static 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 static 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 static 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.

getMapBroker

private static MapBrokerService getMapBroker()
Returns the system's configured MapBrokerService implementation.
Returns:
a MapBrokerService

getPoolBroker

private static PoolBrokerService getPoolBroker()
Returns the system's configured PoolBrokerService implementation.
Returns:
a PoolBrokerService


Copyright © 2000-2002 Apache Software Foundation. All Rights Reserved.