org.jasig.portal
Class RDBMServices

java.lang.Object
  extended by org.jasig.portal.RDBMServices

public class RDBMServices
extends java.lang.Object

Provides relational database access and helper methods. A static routine determines if the database/driver supports prepared statements and/or outer joins.

This class provides database access as a service. Via the class, uPortal code can obtain a connection to the core uPortal database as well as to other databases available via JNDI. (Doing that JNDI lookup directly allows your code to avoid dependence upon this class.) This class provides traditional getConnection() methods as well as static covers for getting a reference to the backing DataSource.

This class also provides helper methods for manipulating connections. Mostof the methods are wrappers around methods on the underlying Connection that handle (log and swallow) the SQLExceptions that the underlying methods declare to be thrown (these helpers also catch and log RuntimeExceptions encountered). They provide an alternative to trying and catching those methods using the JDBC APIs directly.

Version:
$Revision: 1.46.2.4 $ $Date: 2005/12/23 21:08:12 $
Author:
Ken Weiner, kweiner@unicon.net, George Lindholm, george.lindholm@ubc.ca, Eric Dalquist edalquist@unicon.net, Susan Bramhall susan.bramhall@yale.edu

Nested Class Summary
static class RDBMServices.GenericDataSource
          Inner class implementation of DataSource.
static class RDBMServices.PreparedStatement
          Deprecated. Instead of this class a wrapper around the DataSource, Connection and Prepared statement should be done in DatabaseMetaDataImpl
 
Field Summary
private static int activeConnections
           
private static IDatabaseMetadata dbMetaData
           
static java.lang.String DEFAULT_DATABASE
           
private static java.lang.String FLAG_FALSE
           
private static java.lang.String FLAG_TRUE
           
private static java.lang.String FLAG_TRUE_OTHER
           
private static boolean getDatasourceFromJndi
           
private static java.lang.String jdbcDriver
           
private static java.lang.String jdbcUrl
           
private static java.lang.String jdbcUser
           
private static int JNDI_RETRY_TIME
          Specifies how long to wait before trying to look a JNDI data source that previously failed
private static org.apache.commons.logging.Log LOG
           
private static java.util.Map namedDataSources
           
private static java.util.Map namedDbServerFailures
           
static java.lang.String PORTAL_DB
           
private static java.lang.Object SYNC_OBJECT
           
 
Constructor Summary
RDBMServices()
           
 
Method Summary
static void closePreparedStatement(java.sql.PreparedStatement pst)
          Deprecated. Use closeStatement(Statement).
static void closeResultSet(java.sql.ResultSet rs)
          Close a ResultSet
static void closeStatement(java.sql.Statement st)
          Close a Statement
static void commit(java.sql.Connection connection)
          Commit pending transactions.
static java.lang.String dbFlag(boolean flag)
          Return DB format of a boolean.
static boolean dbFlag(java.lang.String flag)
          Return boolean value of DB flag, "Y" or "N".
static int getActiveConnectionCount()
          Return the current number of active connections
static java.sql.Connection getConnection()
          Gets a database connection to the portal database.
static java.sql.Connection getConnection(java.lang.String dbName)
          Returns a connection produced by a DataSource found in the JNDI context.
static javax.sql.DataSource getDataSource()
          Gets the default DataSource.
static javax.sql.DataSource getDataSource(java.lang.String name)
          Gets a named DataSource from JNDI, with special handling for the PORTAL_DB datasource.
static IDatabaseMetadata getDbMetaData()
          Get metadata about the default DataSource.
static java.lang.String getJdbcDriver()
          Returns the name of the JDBC driver being used for the default uPortal database connections.
static java.lang.String getJdbcUrl()
          Gets the JDBC URL of the default uPortal database connections.
static java.lang.String getJdbcUser()
          Get the username under which we are connecting for the default uPortal database connections.
private static javax.sql.DataSource getJndiDataSource(java.lang.String name)
          Does the JNDI lookup and returns datasource
static boolean isGetDatasourceFromJndi()
           
static void releaseConnection(java.sql.Connection con)
          Releases database connection.
static void rollback(java.sql.Connection connection)
          rollback unwanted changes to the database
static void setAutoCommit(java.sql.Connection connection, boolean autocommit)
          Set auto commit state for the connection.
static void setGetDatasourceFromJndi(boolean getDatasourceFromJndi)
           
static java.lang.String sqlEscape(java.lang.String sql)
          Make a string SQL safe
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PORTAL_DB

public static final java.lang.String PORTAL_DB

DEFAULT_DATABASE

public static final java.lang.String DEFAULT_DATABASE
See Also:
Constant Field Values

getDatasourceFromJndi

private static boolean getDatasourceFromJndi

LOG

private static final org.apache.commons.logging.Log LOG

FLAG_TRUE

private static final java.lang.String FLAG_TRUE
See Also:
Constant Field Values

FLAG_TRUE_OTHER

private static final java.lang.String FLAG_TRUE_OTHER
See Also:
Constant Field Values

FLAG_FALSE

private static final java.lang.String FLAG_FALSE
See Also:
Constant Field Values

JNDI_RETRY_TIME

private static final int JNDI_RETRY_TIME
Specifies how long to wait before trying to look a JNDI data source that previously failed


namedDataSources

private static java.util.Map namedDataSources

namedDbServerFailures

private static java.util.Map namedDbServerFailures

jdbcUrl

private static java.lang.String jdbcUrl

jdbcUser

private static java.lang.String jdbcUser

jdbcDriver

private static java.lang.String jdbcDriver

dbMetaData

private static IDatabaseMetadata dbMetaData

SYNC_OBJECT

private static final java.lang.Object SYNC_OBJECT

activeConnections

private static int activeConnections
Constructor Detail

RDBMServices

public RDBMServices()
Method Detail

getDataSource

public static javax.sql.DataSource getDataSource()
Gets the default DataSource. If no server is found a runtime exception will be thrown. This method will never return null.

Returns:
the core uPortal DataSource
Throws:
java.lang.RuntimeException - on failure

getDataSource

public static javax.sql.DataSource getDataSource(java.lang.String name)
Gets a named DataSource from JNDI, with special handling for the PORTAL_DB datasource. Successful lookups are cached and not done again. Lookup failure is remembered and blocks retry for a number of milliseconds specified by JNDI_RETRY_TIME to reduce JNDI overhead and log spam. There are two ways in which we handle the core uPortal DataSource specially. We determine and remember metadata in an DbMetaData object for the core uPortal DataSource. We do not compute this DbMetaData for any other DataSource. We fall back on using rdbm.properties to construct our core uPortal DataSource in the case where we cannot find it from JNDI. If the portal property org.jasig.portal.RDBMServices.getDatasourceFromJNDI is true, we first first try to get the connection by looking in the JNDI context for the name defined by the portal property org.jasig.portal.RDBMServices.PortalDatasourceJndiName . If we were not configured to check JNDI or we didn't find it in JNDI having checked, we then fall back on rdbm.properties.

Parameters:
name - The name of the DataSource to get.
Returns:
A named DataSource or null if one cannot be found.

getJndiDataSource

private static javax.sql.DataSource getJndiDataSource(java.lang.String name)
Does the JNDI lookup and returns datasource

Parameters:
name -
Returns:

getActiveConnectionCount

public static int getActiveConnectionCount()
Return the current number of active connections

Returns:
int

getConnection

public static java.sql.Connection getConnection()
Gets a database connection to the portal database. If datasource not available a runtime exception is thrown

Returns:
a database Connection object
Throws:
DataAccessException - if unable to return a connection

getConnection

public static java.sql.Connection getConnection(java.lang.String dbName)
Returns a connection produced by a DataSource found in the JNDI context. The DataSource should be configured and loaded into JNDI by the J2EE container or may be the portal default database.

Parameters:
dbName - the database name which will be retrieved from the JNDI context relative to "jdbc/"
Returns:
a database Connection object or null if no Connection

releaseConnection

public static void releaseConnection(java.sql.Connection con)
Releases database connection. Unlike the underlying connection.close(), this method does not throw SQLException or any other exception. It will fail silently from the perspective of calling code, logging errors using Commons Logging.

Parameters:
con - a database Connection object

closeResultSet

public static void closeResultSet(java.sql.ResultSet rs)
Close a ResultSet

Parameters:
rs - a database ResultSet object

closeStatement

public static void closeStatement(java.sql.Statement st)
Close a Statement

Parameters:
st - a database Statement object

closePreparedStatement

public static void closePreparedStatement(java.sql.PreparedStatement pst)
Deprecated. Use closeStatement(Statement).

Close a PreparedStatement. Simply delegates the call to closeStatement(Statement)

Parameters:
pst - a database PreparedStatement object

commit

public static final void commit(java.sql.Connection connection)
Commit pending transactions. Unlike the underlying commit(), this method does not throw SQLException or any other exception. It will fail silently from the perspective of calling code, logging any errors using Commons Logging.

Parameters:
connection -

setAutoCommit

public static final void setAutoCommit(java.sql.Connection connection,
                                       boolean autocommit)
Set auto commit state for the connection. Unlike the underlying connection.setAutoCommit(), this method does not throw SQLException or any other Exception. It fails silently from the perspective of calling code, logging any errors encountered using Commons Logging.

Parameters:
connection -
autocommit -

rollback

public static final void rollback(java.sql.Connection connection)
                           throws java.sql.SQLException
rollback unwanted changes to the database

Parameters:
connection -
Throws:
java.sql.SQLException

getJdbcDriver

public static java.lang.String getJdbcDriver()
Returns the name of the JDBC driver being used for the default uPortal database connections.

Returns:
the name of the JDBC Driver.

getJdbcUrl

public static java.lang.String getJdbcUrl()
Gets the JDBC URL of the default uPortal database connections.


getJdbcUser

public static java.lang.String getJdbcUser()
Get the username under which we are connecting for the default uPortal database connections.


dbFlag

public static final java.lang.String dbFlag(boolean flag)
Return DB format of a boolean. "Y" for true and "N" for false.

Parameters:
flag - true or false
Returns:
either "Y" or "N"

dbFlag

public static final boolean dbFlag(java.lang.String flag)
Return boolean value of DB flag, "Y" or "N".

Parameters:
flag - either "Y" or "N"
Returns:
boolean true or false

sqlEscape

public static final java.lang.String sqlEscape(java.lang.String sql)
Make a string SQL safe

Parameters:
sql -
Returns:
SQL safe string

getDbMetaData

public static IDatabaseMetadata getDbMetaData()
Get metadata about the default DataSource.

Returns:
metadata about the default DataSource.

isGetDatasourceFromJndi

public static boolean isGetDatasourceFromJndi()
Returns:
Returns the getDatasourceFromJndi.

setGetDatasourceFromJndi

public static void setGetDatasourceFromJndi(boolean getDatasourceFromJndi)
Parameters:
getDatasourceFromJndi - The getDatasourceFromJndi to set.