Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.jasig.portal
Class RDBMServices

    java.lang.Object
      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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD