com.ca.idms.was
Class IdmsJdbcDataStoreHelper

java.lang.Object
  com.ibm.websphere.rsadapter.GenericDataStoreHelper
      com.ca.idms.was.IdmsJdbcDataStoreHelper

All Implemented Interfaces:

com.ibm.websphere.rsadapter.DataStoreHelper

public class IdmsJdbcDataStoreHelper
extends com.ibm.websphere.rsadapter.GenericDataStoreHelper

WebSphere DataStoreHelper Class for CA IDMS. WebSphere Application Server 5.0, and later, includes a Relational Resource Adapter. This is a JCA-compliant interface used for JDBC access by J2EE 1.3-compliant applications. The Relational Resource Adapter uses a DataStoreHelper class at runtime to determine the characteristics of a database or other source of data and optimize code generated for EJBs using container managed persistence.

DataStoreHelper is an interface. IBM supplies an implementation class for each “supported” datastore provider, and a GenericDataStoreHelper class for “unsupported” providers. This class extends GenericDataStoreHelper as permitted by IBM to provide the data source-specific support for CA IDMS. Clients may write their own helper classes which extend this class. Then they may either code methods which are present in GenericDataStoreHelper but not referenced here, or override methods which are referenced here.

This version of the WebSphere DataStoreHelper Class for CA IDMS is for WebSphere version 7 or later. This helper class contains a number of trace points which are helpful for debugging and can be activated by setting property trace=true in the caidms.properties file. The trace records will be written to the file specified by trace.file. See the CA IDMS Server Javadoc for the TraceObject class for more detailed information about tracing.

The following WebSphere jar files must be in the classpath to compile or run this class:

• j2ee.jar
• utils.jar
• was_public.jar

These files are found in the WebSphere distribution.

Version:

2.00, 03/24/2009

Author:

Dave Hearn

Field Summary

Fields inherited from class com.ibm.websphere.rsadapter.GenericDataStoreHelper

customDefinedWasDefaultIsoLevel, EOLN, genErrorMap, resBundle

Fields inherited from interface com.ibm.websphere.rsadapter.DataStoreHelper

CLOUDSCAPE_HELPER, CLOUDSCAPE_NETWORK_SERVER_HELPER, CONNECTJDBC_HELPER, CUSTOM_HELPER, DATADIRECT_HELPER, DB2_390_HELPER, DB2_390_LOCAL_HELPER, DB2_400_HELPER, DB2_HELPER, DB2_UNIVERSAL_HELPER, DERBY_HELPER, DERBY_NETWORK_SERVER_HELPER, FIRST_TIME_CALLED, GENERIC_HELPER, INFORMIX_HELPER, INFORMIX_JCC_HELPER, MSSQL_HELPER, ORACLE_10G_HELPER, ORACLE_11G_HELPER, ORACLE_HELPER, POTENTIAL_DEADLOCK, POTENTIAL_LOST_UPDATE, PROXY_DS_HELPER, SEQUELINK_HELPER, SYBASE_HELPER, SYBASE11_HELPER, TX_REPEATABLE_READ_FORUPDATE, TX_SERIALIZABLE_FORUPDATE, UNDEFINED_HELPER, UNDEFINED_ISOLATOIN_LEVEL, UPDATE_ON_READONLY

Constructor Summary

IdmsJdbcDataStoreHelper(java.util.Properties props)
Creates an instance of the CA IDMS Helper Class.

Method Summary

boolean	doConnectionCleanup(java.sql.Connection conn) Called by WebSphere whenever a connection is released by the application and placed back into the connection pool.
boolean	doConnectionCleanupPerCloseConnection(java.sql.Connection conn, boolean isCMP, java.lang.Object props) Called by WebSphere immediately after a connection handle is closed by the application, or implicitly by WebSphere run-time.
void	doConnectionSetup(java.sql.Connection conn) Called by WebSphere whenever a new connection to the data source is created.
boolean	doConnectionSetupPerGetConnection(java.sql.Connection conn, boolean isCMP, java.lang.Object props) Called by WebSphere before a connection handle is provided to the application.
void	doStatementCleanup(java.sql.PreparedStatement stmt) Called by WebSphere if certain statement properties, like cursor name, have been changed prior to placing the statement object into a cache.
java.lang.String	getXAExceptionContents(javax.transaction.xa.XAException xae) This method provides additional information for an XAException.
boolean	isConnectionError(java.sql.SQLException ex) Called by WebSphere to determine whether a particular SQLException constitutes a connection error.

Methods inherited from class com.ibm.websphere.rsadapter.GenericDataStoreHelper

calcPartitionNumber, doConnectionSetupPerTransaction, findMappingClass, getIsolationLevel, getLockType, getMetaData, getPasswordForUseWithTrustedContextWithAuthentication, getPrintWriter, getResultSetConcurrency, getResultSetType, hasLostUpdateOrDeadLockOccurred, isBatchUpdateSupportedWithAccessIntent, isDuplicateKey, mapException, modifyXAFlag, setUserDefinedMap, showLockInfo

Methods inherited from class java.lang.Object

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

Constructor Detail

IdmsJdbcDataStoreHelper

public IdmsJdbcDataStoreHelper(java.util.Properties props)

Creates an instance of the CA IDMS Helper Class. This constructor sets metadata properties so that they are appropriate for CA IDMS. This includes providing error code mappings which cause specified SQLState values to be returned to the application program or the container as SQL Exceptions such as DuplicateKeyException, thereby giving the program or container an opportunity to take corrective action.

Only SQLState values need to be mapped for CA IDMS. The pertinent ones are:

• 08001 - wrong host name, CCI receiver not online
• 08002 - Qcli State Exception
• 08003 - checkConnect fails
• 08004 - unknown DBname, or CV SQL server rejected connection
• 08006 - getSqlState session fails, Qcli I/O exception
• 08007 - abended task on CV
• 23501 - duplicate key exception

Of these, 08001, 08003, and 08006 are already in the error mapping provided by IBM's GenericDataStoreHelper class. This class provides mapping for all of the others.

Clients may override these mappings or provide additional mappings in their own helper classes as shown below:
java.util.Map xMap = new java.util.HashMap();
// for SQLCodes:
xMap.put(new Integer(nnnn), StaleConnectionException.class);
// for SQLStates:
xMap.put("nnnnn",DuplicateKeyException.class);
setUserDefinedMap(xMap);

Parameters:

props - - DataStoreHelper properties passed from WebSphere. These properties are for future extensibility and are not currently used.

Method Detail

doConnectionCleanup

public boolean doConnectionCleanup(java.sql.Connection conn)
                            throws java.sql.SQLException

Called by WebSphere whenever a connection is released by the application and placed back into the connection pool. It is also called when either the "unused" or "aged" timeout expires and the physical connection is released, or after a connection has been verified by sending a "pre-test" string to the back-end. This method is used to invoke a WebSphere-specific close method in CA IDMS Server which causes the back-end task in CA IDMS to end, and any outstanding work to be committed.

Specified by:

doConnectionCleanup in interface com.ibm.websphere.rsadapter.DataStoreHelper

Overrides:

doConnectionCleanup in class com.ibm.websphere.rsadapter.GenericDataStoreHelper

Throws:

java.sql.SQLException

doConnectionCleanupPerCloseConnection

public boolean doConnectionCleanupPerCloseConnection(java.sql.Connection conn,
                                                     boolean isCMP,
                                                     java.lang.Object props)
                                              throws java.sql.SQLException

Called by WebSphere immediately after a connection handle is closed by the application, or implicitly by WebSphere run-time. The connection handle in question is the last active handle for the associated ManagedConnection. Thus, if connection sharing is in effect, this method will not be called when additional connection handles are still open. This method is used by this helper class merely to provide a tracing mechanism for debugging connection pool-related problems.

Specified by:

doConnectionCleanupPerCloseConnection in interface com.ibm.websphere.rsadapter.DataStoreHelper

Overrides:

doConnectionCleanupPerCloseConnection in class com.ibm.websphere.rsadapter.GenericDataStoreHelper

Throws:

java.sql.SQLException

doConnectionSetup

public void doConnectionSetup(java.sql.Connection conn)
                       throws java.sql.SQLException

Called by WebSphere whenever a new connection to the data source is created. It is not called when an existing connection is reused from the connection pool. It is used by this helper class merely to provide a tracing mechanism for debugging connection pool-related problems.

Specified by:

doConnectionSetup in interface com.ibm.websphere.rsadapter.DataStoreHelper

Overrides:

doConnectionSetup in class com.ibm.websphere.rsadapter.GenericDataStoreHelper

Throws:

java.sql.SQLException

doConnectionSetupPerGetConnection

public boolean doConnectionSetupPerGetConnection(java.sql.Connection conn,
                                                 boolean isCMP,
                                                 java.lang.Object props)
                                          throws java.sql.SQLException

Called by WebSphere before a connection handle is provided to the application. The connection handle in question is the first active handle for the associated ManagedConnection. Thus, if connection sharing is in effect, this method will not be called when additional connection handles are provided to the application for the same ManagedConnection. This method is used by this helper class merely to provide a tracing mechanism for debugging connection pool-related problems.

Specified by:

doConnectionSetupPerGetConnection in interface com.ibm.websphere.rsadapter.DataStoreHelper

Overrides:

doConnectionSetupPerGetConnection in class com.ibm.websphere.rsadapter.GenericDataStoreHelper

Throws:

java.sql.SQLException

doStatementCleanup

public void doStatementCleanup(java.sql.PreparedStatement stmt)
                        throws java.sql.SQLException

Called by WebSphere if certain statement properties, like cursor name, have been changed prior to placing the statement object into a cache.

Specified by:

doStatementCleanup in interface com.ibm.websphere.rsadapter.DataStoreHelper

Overrides:

doStatementCleanup in class com.ibm.websphere.rsadapter.GenericDataStoreHelper

Throws:

java.sql.SQLException

isConnectionError

public boolean isConnectionError(java.sql.SQLException ex)

Called by WebSphere to determine whether a particular SQLException constitutes a connection error. If SQLCODE = -6, this method returns true.

Specified by:

isConnectionError in interface com.ibm.websphere.rsadapter.DataStoreHelper

Overrides:

isConnectionError in class com.ibm.websphere.rsadapter.GenericDataStoreHelper

getXAExceptionContents

public java.lang.String getXAExceptionContents(javax.transaction.xa.XAException xae)

This method provides additional information for an XAException. WebSphere uses this method to obtain trace information for XAExceptions to include in WebSphere trace.

Specified by:

getXAExceptionContents in interface com.ibm.websphere.rsadapter.DataStoreHelper

Overrides:

getXAExceptionContents in class com.ibm.websphere.rsadapter.GenericDataStoreHelper