org.noorm.jdbc

Class DataSourceProvider

java.lang.Object

org.noorm.jdbc.DataSourceProvider

public class DataSourceProvider
extends Object

DataSourceProvider manages data sources and controls transactions in the NoORM runtime engine. Data sources are typically configured in the NoORM configuration file ("noorm.xml" or "noorm.properties"). Alternatively, data sources can be added using static method addDataSource. Due to the complex nature of database resource handling in a running system, data sources, which have been added to the system cannot be removed. DataSourceProvider is a Java singleton, which takes over full control over the database connections. Direct usage of database connections is possible for dedicated purposes (e.g. integration with Oracle AQ), but discouraged for typical database access operations. The public API for DataSourceProvider is simple to use and primarily provides the required functionality for explicit transaction handling using the methods begin(), commit() and rollback(). Without explicit transaction handling, DataSourceProvider manages transactions automatically by issuing an auto-commit after every database call. Issuing a commit even for read-only database access imposes a little performance overhead. However, for most usage scenarios, this overhead is not significant. Explicit transaction handling (using begin(), commit(), rollback()) is managed by maintaining the JDBC connection in a ThreadLocal variable. This removes the burden of connection control from the application programmer, since DataSourceProvider will keep track of the current transaction beyond class and method boundaries in the application. Using explicit transaction control requires the application programmer to control transaction termination properly, i.e., the application must guarantee that a transaction started with begin() will always be terminated with commit() or rollback().

Author:

Ulf Pietruschka / ulf.pietruschka@etenso.com

Method Summary

Methods

Modifier and Type	Method and Description
static boolean	activeUserManagedTransaction() Verifies, whether an explicit (user managed) transaction is currently in progress, i.e., the application has explicitly issued a "begin", but has not yet terminated the transaction with "commit" or "rollback".
static void	addDataSource(DataSource pDataSource, String pDataSourceName, boolean pActivate) Adds and optionally activates a new data source to be controlled by the DataSourceProvider.
static void	begin() To control transactions in the calling application, the connection in use must not turned back to the connection pool, but should be preserved in a ThreadLocal variable.
static void	commit() Commits a user managed transaction.
static int	getBatchUpdateSize() Returns the currently size of JDBC update and insert batches.
static oracle.jdbc.OracleConnection	getConnection() Returns the Oracle database connection currently managed by the DataSourceProvider.
boolean	isDebugOn() Shows whether debug mode has been enabled.
static void	rollback() Issues a rollback on a user managed transaction.
static void	setActiveDataSource(String pDataSourceName) Activates the data source with the given name.
static void	setBatchUpdateSize(int pBatchUpdateSize) Sets the size of JDBC update and insert batches.
static void	setDebugMode(boolean pDebugMode) Debug mode is enabled by establishing a JPDA/JDWP connection to a listening source code debugger, which listens on the configured host and port for database session debugging.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setActiveDataSource

public static void setActiveDataSource(String pDataSourceName)

Activates the data source with the given name. The name of the data source is either the name provided for the data source in the NoORM configuration file (noorm.xml or noorm.properties) or the name provided, when the data source been added using method addDataSource.

Parameters:

pDataSourceName - the name of the data source to be activated.

addDataSource

public static void addDataSource(DataSource pDataSource,
                 String pDataSourceName,
                 boolean pActivate)

Adds and optionally activates a new data source to be controlled by the DataSourceProvider.

Parameters:

pDataSource - the pre-configured data source.

pDataSourceName - the name of the data source. Used by method setActiveDataSource.

pActivate - determines, whether the data source should be activated right after it has been added.

getConnection

public static oracle.jdbc.OracleConnection getConnection()
                                                  throws SQLException

Returns the Oracle database connection currently managed by the DataSourceProvider. Note that the life-cycle of the connection is managed by the DataSourceProvider, i.e. acquiring a connection, closing a connection, resp. returning a connection to the connection pool and managing transaction boundaries SHOULD NOT BE DONE in the application code. Providing the database connection directly by this method has the sole purpose to support additional Oracle Java client software, which requires access to the connection (e.g. Oracle Streams Advanced Queueing, which requires the Oracle connection to create an AQSession).

Returns:

the Oracle database connection currently managed by the DataSourceProvider.

Throws:

SQLException

activeUserManagedTransaction

public static boolean activeUserManagedTransaction()

Verifies, whether an explicit (user managed) transaction is currently in progress, i.e., the application has explicitly issued a "begin", but has not yet terminated the transaction with "commit" or "rollback".

Returns:

true, when a transaction is in progress

begin

public static void begin()

To control transactions in the calling application, the connection in use must not turned back to the connection pool, but should be preserved in a ThreadLocal variable. This method is used to indicate that the calling application intends to broaden the transaction boundaries beyond the scope of a single PL/SQL or DML call. Oracle does not know about the classical "begin" call, since an Oracle session has always an active transaction (after issuing a "commit" or "rollback", a new transaction is started implicitly).

commit

public static void commit()

Commits a user managed transaction. Connections are maintained in the connection pool. Note that using this method requires that a user managed transaction has been started using method begin(), other a DataAccessException is thrown. Transactions, which are not user managed are always committed automatically, when the connection is returned to the connection pool (restricting automated transaction management to transactions with a scope limited to a single call to PL/SQL, an insert, update or an delete operation.

rollback

public static void rollback()

Issues a rollback on a user managed transaction. See DataSourceProvider.commit();

getBatchUpdateSize

public static int getBatchUpdateSize()

Returns the currently size of JDBC update and insert batches. The default is 100.

Returns:

the batch size.

setBatchUpdateSize

public static void setBatchUpdateSize(int pBatchUpdateSize)

Sets the size of JDBC update and insert batches. The default is 100.

Parameters:

pBatchUpdateSize -

isDebugOn

public boolean isDebugOn()

Shows whether debug mode has been enabled.

Returns:

true, when debug mode has been enabled, false otherwise.

setDebugMode

public static void setDebugMode(boolean pDebugMode)

Debug mode is enabled by establishing a JPDA/JDWP connection to a listening source code debugger, which listens on the configured host and port for database session debugging. DO NOT enable debugging without an active listening source code debugger.

Parameters:

pDebugMode - debug mode toggle.