atg.service.jdbc
Class XAOnlyDataSource

java.lang.Object
  atg.nucleus.logging.VariableArgumentApplicationLoggingImpl
      atg.nucleus.GenericService
          atg.service.jdbc.XAOnlyDataSource

All Implemented Interfaces:

NameContextBindingListener, NameContextElement, NameResolver, AdminableService, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, ConnectionStats, java.util.EventListener, javax.sql.ConnectionEventListener, javax.sql.DataSource

public class XAOnlyDataSource
extends GenericService
implements javax.sql.DataSource, javax.sql.ConnectionEventListener, ConnectionStats

An application server tier DataSource that sits on top of an XADataSource and registers/unregisters XAConnections with the TransactionManager. This DataSource provides no pooling features of its own.

This DataSource is designed to only work on top of an XADataSource. Therefore, when used within the scope of a distributed transaction commit(), rollback(), and setAutoCommit() should never be called on Connections obtained from it. Those functions are executed by the TransactionManager. When used in local transaction mode, i.e. outside the scope of a distributed transaction, all of the Connections transactional methods are available for use.

Typical usage of this DataSource might look as follows:

   DataSource ds = ;
   Connection c = null;
   try {
     try {
       c = ds.getConnection();
       // Various work without calling c.commit() or c.rollback().
     } finally {
       // Closing of the Connection must always occur or else
       // Connections will not be returned to the pool properly!
       if (c != null)
         c.close();
     }
   } catch (SQLException sqle) {
     // If something went wrong, we might want to rollback
     // the transaction.
   }
 

Note this example assumes a distributed transaction is in place meaning transactioning is handled by JTA and no transactioning methods are called on the Connection itself.

All Connections produced by this DataSource are MonitoredConnections, i.e. they are normal Connections wrapped for the purpose of gathering statistics. Because of this, message logging is achievable at a finer granularity. The standard ApplicationLogging interface exists for messages generated by the DataSource proper and a variant of the interface is implemented for the logging of messages generated by Connections. Use the methods loggingSQLInfo(), loggingSQLDebug(), loggingSQLWarning(), and loggingSQLError() to turn off message logging for Connections created by this DataSource.

Nested Class Summary

class

XAOnlyDataSource.SQLLogging A utility class which builds a separate logging interface for SQL logging to have access to.

Field Summary

static java.lang.String

CLASS_VERSION Class version string

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

XAOnlyDataSource()
Constructs an uninitialized XAOnlyDataSource.

Method Summary

void	connectionClosed(javax.sql.ConnectionEvent pEvent) Invoked when the application calls close() on its representation of the connection.
void	connectionErrorOccurred(javax.sql.ConnectionEvent pEvent) Invoked when a fatal connection error occurs, just before an SQLException is thrown to the application.
void	doStartService() Things to do when the service starts up.
int	getCommitCount() Returns the number of times commit() has been called
java.sql.Connection	getConnection() Returns a Connection that is participating in the current Transaction using the default username and password.
java.sql.Connection	getConnection(java.lang.String pUsername, java.lang.String pPassword) Returns a Connection that is participating in the current Transaction using the given username and password.
int	getCreateStatementCount() Returns the number of times createStatement() has been called
javax.sql.XADataSource	getDataSource() Returns property dataSource.
java.util.Properties	getDataSourceJNDIEnvironment() Returns property dataSourceJNDIEnvironment.
java.lang.String	getDataSourceJNDIName() Returns property dataSourceJNDIName.
int	getErrorCount() Returns the number of times a SQLException resulted from calls.
int	getExecuteCount() Returns the number of times Statement.execute() has been called
int	getExecuteQueryCount() Returns the number of times Statement.executeQuery() has been called
int	getExecuteUpdateCount() Returns the number of times Statement.executeUpdate() has been called
int	getGetMoreResultsCount() Returns the number of times Statement.getMoreResults() has been called
java.lang.String[]	getInitializingSQL() Returns property initializingSQL.
int	getLoginTimeout() Returns property loginTimeout.
java.io.PrintWriter	getLogWriter() This property from the DataSource interface is ignored.
java.lang.Integer	getMaxFieldSize() Returns the size of the data that can be returned for any column.
java.lang.Integer	getMaxRows() Returns the maximum number of rows that can be returned for any query.
int	getPrepareCallCount() Returns the number of times prepareCall() has been called
int	getPrepareStatementCount() Returns the number of times prepareStatement() has been called
java.lang.Integer	getQueryTimeout() Returns the maximum number of seconds that the driver will wait for a Statement to execute.
int	getResultSetRowCount() Returns the number of times ResultSet.next() has been called
int	getRollbackCount() Returns the number of times rollback() has been called
javax.transaction.TransactionManager	getTransactionManager() Returns property transactionManager.
void	incrementCommitCount() Increments the number of times commit() has been called
void	incrementCreateStatementCount() Increments the number of times createStatement() has been called
void	incrementErrorCount() Increments the number of times a SQLException resulted from calls.
void	incrementExecuteCount() Increments the number of times Statement.execute() has been called
void	incrementExecuteQueryCount() Increments the number of times Statement.executeQuery() has been called
void	incrementExecuteUpdateCount() Increments the number of times Statement.executeUpdate() has been called
void	incrementGetMoreResultsCount() Increments the number of times Statement.getMoreResults() has been called
void	incrementPrepareCallCount() Increments the number of times prepareCall() has been called
void	incrementPrepareStatementCount() Increments the number of times prepareStatement() has been called
void	incrementResultSetRowCount() Increments the number of times ResultSet.next() has been called
void	incrementRollbackCount() Increments the number of times rollback() has been called
boolean	isAssociativeFakeXA() Returns property associativeFakeXA.
boolean	isEnlistBeforeGet() Returns property enlistBeforeGet.
boolean	isLoggingSQLDebug() This method returns whether or not an debug log event should be broadcast for MonitoredConnections.
boolean	isLoggingSQLError() This method returns whether or not an error log event should be broadcast for MonitoredConnections.
boolean	isLoggingSQLInfo() This method returns whether or not an info log event should be broadcast for MonitoredConnections.
boolean	isLoggingSQLWarning() This method returns whether or not an warning log event should be broadcast for MonitoredConnections.
boolean	isWrapperFor(java.lang.Class<?> iface) Returns true if this either implements the interface argument or is directly or indirectly a wrapper for an object that does.
void	setAssociativeFakeXA(boolean pAssociativeFakeXA) Sets property associativeFakeXA.
void	setDataSource(javax.sql.XADataSource pXADataSource) Sets the property dataSource.
void	setDataSourceJNDIEnvironment(java.util.Properties pDataSourceJNDIEnvironment) Sets property dataSourceJNDIEnvironment.
void	setDataSourceJNDIName(java.lang.String pDataSourceJNDIName) Sets property dataSourceJNDIName.
void	setEnlistBeforeGet(boolean pEnlistBeforeGet) Sets property enlistBeforeGet.
void	setInitializingSQL(java.lang.String[] pInitializingSQL) Sets property initializingSQL.
void	setLoggingSQLDebug(boolean pLogging) Sets whether or not error log events should be logged for MonitoredConnections.
void	setLoggingSQLError(boolean pLogging) Sets whether or not error log events should be logged for MonitoredConnections.
void	setLoggingSQLInfo(boolean pLogging) Sets whether or not info log events should be logged for MonitoredConnections.
void	setLoggingSQLWarning(boolean pLogging) Sets whether or not warning log events should be logged for MonitoredConnections.
void	setLoginTimeout(int pLoginTimeout) Sets property loginTimeout.
void	setLogWriter(java.io.PrintWriter pLogWriter) This property from the DataSource interface is ignored.
void	setMaxFieldSize(java.lang.Integer pMaxFieldSize) Sets the size of the data that can be returned for any column.
void	setMaxRows(java.lang.Integer pMaxRows) Sets the maximum number of rows that can be returned for any query.
void	setQueryTimeout(java.lang.Integer pQueryTimeout) Sets the maximum number of seconds that the driver will wait for a Statement to execute.
void	setTransactionManager(javax.transaction.TransactionManager pValue)
<T> T	unwrap(java.lang.Class<T> iface) Returns an object that implements the given interface to allow access to non-standard methods, or standard methods not exposed by the proxy.

Methods inherited from class atg.nucleus.GenericService

addLogListener, createAdminServlet, doStopService, getAbsoluteName, getAdminServlet, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

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

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Class version string

Constructor Detail

XAOnlyDataSource

public XAOnlyDataSource()

Constructs an uninitialized XAOnlyDataSource.

Method Detail

setDataSourceJNDIName

public void setDataSourceJNDIName(java.lang.String pDataSourceJNDIName)

Sets property dataSourceJNDIName.
JNDI name of the XADataSource to get Connections from.

Parameters:

pDataSourceJNDIName - new value to set

getDataSourceJNDIName

public java.lang.String getDataSourceJNDIName()

Returns property dataSourceJNDIName.
JNDI name of the XADataSource to get Connections from.

Returns:

String

setDataSourceJNDIEnvironment

public void setDataSourceJNDIEnvironment(java.util.Properties pDataSourceJNDIEnvironment)

Sets property dataSourceJNDIEnvironment.
An optional set of properties needed by JNDI to resolve the DataSource.

Parameters:

pDataSourceJNDIEnvironment - new value to set

getDataSourceJNDIEnvironment

public java.util.Properties getDataSourceJNDIEnvironment()

Returns property dataSourceJNDIEnvironment.
An optional set of properties needed by JNDI to resolve the DataSource.

Returns:

Properties

setDataSource

public void setDataSource(javax.sql.XADataSource pXADataSource)

Sets the property dataSource.
The XADataSource to get new Connections for the pool from. This method is used to set the property directly. Alternatively, the properties dataSourceJNDIName and dataSourceJNDIEnvironment can be used.

Parameters:

pXADataSource - new value to set

getDataSource

public javax.sql.XADataSource getDataSource()

Returns property dataSource.
The XADataSource to get new Connections for the pool from. This property is either the DataSource set via the setDataSource() method or resolved via JNDI from the setDataSourceJNDIName property.

Returns:

XADataSource

setTransactionManager

public void setTransactionManager(javax.transaction.TransactionManager pValue)

getTransactionManager

public javax.transaction.TransactionManager getTransactionManager()

Returns property transactionManager.
The TransactionManager handling distributed transactions.

Returns:

TransactionManager

isLoggingSQLInfo

public boolean isLoggingSQLInfo()

This method returns whether or not an info log event should be broadcast for MonitoredConnections.

Returns:

boolean true if info log events should be logged
false if info log events should not be logged

setLoggingSQLInfo

public void setLoggingSQLInfo(boolean pLogging)

Sets whether or not info log events should be logged for MonitoredConnections.

isLoggingSQLWarning

public boolean isLoggingSQLWarning()

This method returns whether or not an warning log event should be broadcast for MonitoredConnections.

Returns:

boolean true if warning log events should be logged
false if warning log events should not be logged

setLoggingSQLWarning

public void setLoggingSQLWarning(boolean pLogging)

Sets whether or not warning log events should be logged for MonitoredConnections.

isLoggingSQLError

public boolean isLoggingSQLError()

This method returns whether or not an error log event should be broadcast for MonitoredConnections.

Returns:

boolean true if error log events should be logged
false if error log events should not be logged

setLoggingSQLError

public void setLoggingSQLError(boolean pLogging)

Sets whether or not error log events should be logged for MonitoredConnections.

isLoggingSQLDebug

public boolean isLoggingSQLDebug()

This method returns whether or not an debug log event should be broadcast for MonitoredConnections.

Returns:

boolean true if debug log events should be logged
false if debug log events should not be logged

setLoggingSQLDebug

public void setLoggingSQLDebug(boolean pLogging)

Sets whether or not error log events should be logged for MonitoredConnections.

getMaxFieldSize

public java.lang.Integer getMaxFieldSize()

Returns the size of the data that can be returned for any column. Passed to every MonitoredConnection for use with MonitoredStatements

setMaxFieldSize

public void setMaxFieldSize(java.lang.Integer pMaxFieldSize)

Sets the size of the data that can be returned for any column. Setting this to a -1 value is equivalent to disabling it.

getMaxRows

public java.lang.Integer getMaxRows()

Returns the maximum number of rows that can be returned for any query. Passed to every MonitoredConnection for use with MonitoredStatements

setMaxRows

public void setMaxRows(java.lang.Integer pMaxRows)

Sets the maximum number of rows that can be returned for any query.

getQueryTimeout

public java.lang.Integer getQueryTimeout()

Returns the maximum number of seconds that the driver will wait for a Statement to execute. Passed to every MonitoredConnection for use with MonitoredStatements

setQueryTimeout

public void setQueryTimeout(java.lang.Integer pQueryTimeout)

Sets the maximum number of seconds that the driver will wait for a Statement to execute.

setInitializingSQL

public void setInitializingSQL(java.lang.String[] pInitializingSQL)

Sets property initializingSQL.
An array of SQL commands to be executed on newly created Connections before inserted into the pool.

Parameters:

pInitializingSQL - new value to set

getInitializingSQL

public java.lang.String[] getInitializingSQL()

Returns property initializingSQL.
An array of SQL commands to be executed on newly created Connections before inserted into the pool.

Returns:

String[]

setEnlistBeforeGet

public void setEnlistBeforeGet(boolean pEnlistBeforeGet)

Sets property enlistBeforeGet.
Do resource enlistment before calling getConnection() on XAConnection. Unfortunately JDBC has a loose specification allowing vendors to do things differently from each other. This property addresses such a problem. Some drivers do not allow you to call XAConnection.getConnection() before enlisting the connection's XAResource with the TransactionManager. Some drivers do not allow the exact opposite. The default for this property accommodates Oracle and Sybase. Set this property to true for Merant drivers.

Parameters:

pEnlistBeforeGet - new value to set

isEnlistBeforeGet

public boolean isEnlistBeforeGet()

Returns property enlistBeforeGet.
Do resource enlistment before calling getConnection() on XAConnection. Unfortunately JDBC has a loose specification allowing vendors to do things differently from each other. This property addresses such a problem. Some drivers do not allow you to call XAConnection.getConnection() before enlisting the connection's XAResource with the TransactionManager. Some drivers do not allow the exact opposite. The default for this property accommodates Oracle and Sybase. Set this property to true for Merant drivers.

Returns:

boolean

setAssociativeFakeXA

public void setAssociativeFakeXA(boolean pAssociativeFakeXA)

Sets property associativeFakeXA.
Whether or not to associate FakeXA connections with transactions.

Parameters:

pAssociativeFakeXA - new value to set

isAssociativeFakeXA

public boolean isAssociativeFakeXA()

Returns property associativeFakeXA.
Whether or not to associate FakeXA connections with transactions.

Returns:

boolean

setLoginTimeout

public void setLoginTimeout(int pLoginTimeout)

Sets property loginTimeout.
The maximum time in seconds to wait attempting to connect to a database. This DataSource property has been translated into ResourcePool.checkoutBlockTime. Setting loginTimeout will be the same as setting ResourcePool.checkoutBlockTime.

Specified by:

setLoginTimeout in interface javax.sql.DataSource

Parameters:

pLoginTimeout - new value to set

getLoginTimeout

public int getLoginTimeout()

Returns property loginTimeout.
The maximum time in seconds to wait attempting to connect to a database. This DataSource property has been translated into ResourcePool.checkoutBlockTime. Setting loginTimeout will be the same as setting ResourcePool.checkoutBlockTime.

Specified by:

getLoginTimeout in interface javax.sql.DataSource

Returns:

int

setLogWriter

public void setLogWriter(java.io.PrintWriter pLogWriter)

This property from the DataSource interface is ignored. All of the pool and objects generated by the pool write log messages to the ApplicationLogging interfaces.

Specified by:

setLogWriter in interface javax.sql.DataSource

getLogWriter

public java.io.PrintWriter getLogWriter()

This property from the DataSource interface is ignored. All of the pool and objects generated by the pool write log messages to the ApplicationLogging interfaces.

Specified by:

getLogWriter in interface javax.sql.DataSource

doStartService

public void doStartService()
                    throws ServiceException

Things to do when the service starts up.

Overrides:

doStartService in class GenericService

Throws:

ServiceException - if the Service had a problem starting up

getConnection

public java.sql.Connection getConnection()
                                  throws java.sql.SQLException

Returns a Connection that is participating in the current Transaction using the default username and password.

Specified by:

getConnection in interface javax.sql.DataSource

Throws:

java.sql.SQLException

getConnection

public java.sql.Connection getConnection(java.lang.String pUsername,
                                         java.lang.String pPassword)
                                  throws java.sql.SQLException

Returns a Connection that is participating in the current Transaction using the given username and password.

Specified by:

getConnection in interface javax.sql.DataSource

Throws:

java.sql.SQLException

connectionClosed

public void connectionClosed(javax.sql.ConnectionEvent pEvent)

Invoked when the application calls close() on its representation of the connection.

Specified by:

connectionClosed in interface javax.sql.ConnectionEventListener

Parameters:

pEvent - an event object describing the source of the event

connectionErrorOccurred

public void connectionErrorOccurred(javax.sql.ConnectionEvent pEvent)

Invoked when a fatal connection error occurs, just before an SQLException is thrown to the application.

Specified by:

connectionErrorOccurred in interface javax.sql.ConnectionEventListener

Parameters:

pEvent - an event object describing the source of the event

incrementErrorCount

public void incrementErrorCount()

Increments the number of times a SQLException resulted from calls.

Specified by:

incrementErrorCount in interface ConnectionStats

getErrorCount

public int getErrorCount()

Returns the number of times a SQLException resulted from calls.

incrementCommitCount

public void incrementCommitCount()

Increments the number of times commit() has been called

Specified by:

incrementCommitCount in interface ConnectionStats

getCommitCount

public int getCommitCount()

Returns the number of times commit() has been called

incrementRollbackCount

public void incrementRollbackCount()

Increments the number of times rollback() has been called

Specified by:

incrementRollbackCount in interface ConnectionStats

getRollbackCount

public int getRollbackCount()

Returns the number of times rollback() has been called

incrementCreateStatementCount

public void incrementCreateStatementCount()

Increments the number of times createStatement() has been called

Specified by:

incrementCreateStatementCount in interface ConnectionStats

getCreateStatementCount

public int getCreateStatementCount()

Returns the number of times createStatement() has been called

incrementPrepareStatementCount

public void incrementPrepareStatementCount()

Increments the number of times prepareStatement() has been called

Specified by:

incrementPrepareStatementCount in interface ConnectionStats

getPrepareStatementCount

public int getPrepareStatementCount()

Returns the number of times prepareStatement() has been called

incrementPrepareCallCount

public void incrementPrepareCallCount()

Increments the number of times prepareCall() has been called

Specified by:

incrementPrepareCallCount in interface ConnectionStats

getPrepareCallCount

public int getPrepareCallCount()

Returns the number of times prepareCall() has been called

incrementExecuteQueryCount

public void incrementExecuteQueryCount()

Increments the number of times Statement.executeQuery() has been called

Specified by:

incrementExecuteQueryCount in interface ConnectionStats

getExecuteQueryCount

public int getExecuteQueryCount()

Returns the number of times Statement.executeQuery() has been called

incrementExecuteUpdateCount

public void incrementExecuteUpdateCount()

Increments the number of times Statement.executeUpdate() has been called

Specified by:

incrementExecuteUpdateCount in interface ConnectionStats

getExecuteUpdateCount

public int getExecuteUpdateCount()

Returns the number of times Statement.executeUpdate() has been called

incrementExecuteCount

public void incrementExecuteCount()

Increments the number of times Statement.execute() has been called

Specified by:

incrementExecuteCount in interface ConnectionStats

getExecuteCount

public int getExecuteCount()

Returns the number of times Statement.execute() has been called

incrementGetMoreResultsCount

public void incrementGetMoreResultsCount()

Increments the number of times Statement.getMoreResults() has been called

Specified by:

incrementGetMoreResultsCount in interface ConnectionStats

getGetMoreResultsCount

public int getGetMoreResultsCount()

Returns the number of times Statement.getMoreResults() has been called

incrementResultSetRowCount

public void incrementResultSetRowCount()

Increments the number of times ResultSet.next() has been called

Specified by:

incrementResultSetRowCount in interface ConnectionStats

getResultSetRowCount

public int getResultSetRowCount()

Returns the number of times ResultSet.next() has been called

isWrapperFor

public boolean isWrapperFor(java.lang.Class<?> iface)
                     throws java.sql.SQLException

Returns true if this either implements the interface argument or is directly or indirectly a wrapper for an object that does. Returns false otherwise. If this implements the interface then return true, else if this is a wrapper then return the result of recursively calling isWrapperFor on the wrapped object. If this does not implement the interface and is not a wrapper, return false. This method should be implemented as a low-cost operation compared to unwrap so that callers can use this method to avoid expensive unwrap calls that may fail. If this method returns true then calling unwrap with the same argument should succeed.

Currently not implemented.

Parameters:

iface - a Class defining an interface.

Returns:

true if this implements the interface or directly or indirectly wraps an object that does.

Throws:

java.sql.SQLException - if an error occurs while determining whether this is a wrapper for an object with the given interface.

Since:

1.6

unwrap

public <T> T unwrap(java.lang.Class<T> iface)
         throws java.sql.SQLException

Returns an object that implements the given interface to allow access to non-standard methods, or standard methods not exposed by the proxy. If the receiver implements the interface then the result is the receiver or a proxy for the receiver. If the receiver is a wrapper and the wrapped object implements the interface then the result is the wrapped object or a proxy for the wrapped object. Otherwise return the the result of calling unwrap recursively on the wrapped object or a proxy for that result. If the receiver is not a wrapper and does not implement the interface, then an SQLException is thrown.

Currently not implemented.

Parameters:

iface - A Class defining an interface that the result must implement.

Returns:

an object that implements the interface. May be a proxy for the actual implementing object.

Throws:

java.sql.SQLException - If no object found that implements the interface

Since:

1.6