org.jasig.portal
Class RDBMServices

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

public class RDBMServices
extends 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: 21155 $ $Date: 2010-07-19 15:38:57 -0500 (Mon, 19 Jul 2010) $

Author:

Ken Weiner, kweiner@unicon.net, George Lindholm, george.lindholm@ubc.ca, Eric Dalquist edalquist@unicon.net, Susan Bramhall susan.bramhall@yale.edu

Field Summary

static String	PORTAL_DB Name of the default portal database expected in the Spring application context
static String	PORTAL_DB_METADATA Name of the IDatabaseMetadata expected in the Spring application context

Constructor Summary

RDBMServices()

Method Summary

static void	closeResultSet(ResultSet rs) Close a ResultSet
static void	closeStatement(Statement st) Close a Statement
static void	commit(Connection connection) Commit pending transactions.
static String	dbFlag(boolean flag) Return DB format of a boolean.
static boolean	dbFlag(String flag) Return boolean value of DB flag, "Y" or "N".
static int	getActiveConnectionCount()
static Connection	getConnection() Deprecated. Where possible code should be injected with a DataSource object via the Spring application context
static Connection	getConnection(String dbName) Deprecated. Where possible code should be injected with a DataSource object via the Spring application context
static DataSource	getDataSource() Deprecated. Where possible code should be injected with a DataSource object via the Spring application context
static DataSource	getDataSource(String name) Deprecated. Where possible code should be injected with a DataSource object via the Spring application context
static IDatabaseMetadata	getDbMetaData() Deprecated. Use the bean named PortalDB.metadata instead
static String	getJdbcDriver() Returns the name of the JDBC driver being used for the default uPortal database connections.
static String	getJdbcUrl() Gets the JDBC URL of the default uPortal database connections.
static String	getJdbcUser() Get the username under which we are connecting for the default uPortal database connections.
static MovingAverageSample	getLastDatabase()
static int	getMaxConnectionCount()
static void	releaseConnection(Connection con) Deprecated. Where possible code should be injected with a DataSource object via the Spring application context
static void	rollback(Connection connection) rollback unwanted changes to the database
static void	setAutoCommit(Connection connection, boolean autocommit) Set auto commit state for the connection.
static String	sqlEscape(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 String PORTAL_DB

Name of the default portal database expected in the Spring application context

See Also:

Constant Field Values

PORTAL_DB_METADATA

public static final String PORTAL_DB_METADATA

Name of the IDatabaseMetadata expected in the Spring application context

See Also:

Constant Field Values

Constructor Detail

RDBMServices

public RDBMServices()

Method Detail

getDataSource

@Deprecated
public static DataSource getDataSource()

Deprecated. Where possible code should be injected with a DataSource object via the Spring application context

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:

RuntimeException - on failure

getDataSource

@Deprecated
public static DataSource getDataSource(String name)

Deprecated. Where possible code should be injected with a DataSource object via the Spring application context

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.

getActiveConnectionCount

public static int getActiveConnectionCount()

Returns:

Return the current number of active connections

getMaxConnectionCount

public static int getMaxConnectionCount()

Returns:

Return the maximum number of connections

getLastDatabase

public static MovingAverageSample getLastDatabase()

getConnection

@Deprecated
public static Connection getConnection()

Deprecated. Where possible code should be injected with a DataSource object via the Spring application context

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

@Deprecated
public static Connection getConnection(String dbName)

Deprecated. Where possible code should be injected with a DataSource object via the Spring application context

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

@Deprecated
public static void releaseConnection(Connection con)

Deprecated. Where possible code should be injected with a DataSource object via the Spring application context

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(ResultSet rs)

Close a ResultSet

Parameters:

rs - a database ResultSet object

closeStatement

public static void closeStatement(Statement st)

Close a Statement

Parameters:

st - a database Statement object

commit

public static final void commit(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(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(Connection connection)
                           throws SQLException

rollback unwanted changes to the database

Parameters:

connection -

Throws:

SQLException

getJdbcDriver

public static 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 String getJdbcUrl()

Gets the JDBC URL of the default uPortal database connections.

getJdbcUser

public static String getJdbcUser()

Get the username under which we are connecting for the default uPortal database connections.

dbFlag

public static final 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(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 String sqlEscape(String sql)

Make a string SQL safe

Parameters:

sql -

Returns:

SQL safe string

getDbMetaData

@Deprecated
public static IDatabaseMetadata getDbMetaData()

Deprecated. Use the bean named PortalDB.metadata instead

Get metadata about the default DataSource.

Returns:

metadata about the default DataSource.