com.ibm.websphere.rsadapter
Class GenericDataStoreHelper

java.lang.Object
  |
  +--com.ibm.websphere.rsadapter.GenericDataStoreHelper
All Implemented Interfaces:
DataStoreHelper, java.io.Serializable
Direct Known Subclasses:
CloudscapeDataStoreHelper, DataDirectDataStoreHelper, DB2DataStoreHelper, InformixDataStoreHelper, MSSQLDataStoreHelper, OracleDataStoreHelper, SybaseDataStoreHelper

public class GenericDataStoreHelper
extends java.lang.Object
implements DataStoreHelper, java.io.Serializable

This class should be used for non supported Databases, the user has the option to override this class and make changes to the methods to make it fit the new database. values returned by the methods in this class are the default values defined by JDBC and/or X/OPEN

See Also:
Serialized Form

Field Summary
protected static java.lang.String EOLN
           
protected  java.util.HashMap genErrorMap
           
protected static java.lang.String 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, GENERIC_HELPER, INFORMIX_HELPER, MSSQL_HELPER, ORACLE_HELPER, POTENTIAL_DEADLOCK, POTENTIAL_LOST_UPDATE, SEQUELINK_HELPER, SYBASE_HELPER, SYBASE11_HELPER, TX_REPEATABLE_READ_FORUPDATE, TX_SERIALIZABLE_FORUPDATE, UPDATE_ON_READONLY, WSCONNECTJDBC_HELPER
 
Constructor Summary
GenericDataStoreHelper(java.util.Properties props)
           
 
Method Summary
 short calcPartitionNumber(java.lang.String fullTableName, java.util.Properties propPartKeys)
          d146350 This method allows the vendor to calculate the partition number based on the input table name and partition key properties.
 boolean doConnectionCleanup(java.sql.Connection conn)
          This method will do clean up on the connection.
 void doConnectionSetup(java.sql.Connection conn)
          This method allows the DataStoreHelper to set any special connection properties that are not obtained from the configuration.
 void doStatementCleanup(java.sql.PreparedStatement stmt)
          Clean up a statement before it is placed in the cache.
 java.lang.Class findMappingClass(java.sql.SQLException e)
          This method returns mapping for a given exception if one found in the GenericHelper HashMap the search is done in the following order: first the errorCode is searched
then the SQLState.
 int getIsolationLevel(com.ibm.websphere.appprofile.accessintent.AccessIntent intent)
          This method returns the isolation level given the Intent object.
 int getLockType(com.ibm.websphere.appprofile.accessintent.AccessIntent intent)
          This method returns a locktype based on the input AccessIntent update hint value.
 DataStoreHelperMetaData getMetaData()
          This method returns the DataStore helper metadata object associated with the helper
 java.io.PrintWriter getPrintWriter()
          This method is used to get the printWriter to be used to output jdbc logging when database logging is enabled (e.g.
 int getResultSetConcurrency(com.ibm.websphere.appprofile.accessintent.AccessIntent intent)
          This method returns the resultSet concurrency given the Intent Object.
 int getResultSetType(com.ibm.websphere.appprofile.accessintent.AccessIntent intent)
          This method returns the resultSet type given the Intent object.
 java.lang.String getXAExceptionContents(javax.transaction.xa.XAException x)
          This method will be used to display in the trace file the contents of the XAException.
 java.lang.String hasLostUpdateOrDeadLockOccurred(int isoLevel, boolean loadedForUpdate)
          Should be called when storing a CMP EntityBean and pessismistic concurrency control is used.
 boolean isBatchUpdateSupportedWithAccessIntent(com.ibm.websphere.appprofile.accessintent.AccessIntent accessIntent)
          This method is used to determine if Batch is supported with the given accessIntent object.
 boolean isConnectionError(java.sql.SQLException ex)
          This method checks if the given exception is one that caused a StaleConnectionException (connection error)
 com.ibm.ws.rsadapter.exceptions.DataStoreAdapterException mapException(com.ibm.ws.rsadapter.exceptions.DataStoreAdapterException e)
          This method maps the SQLException contained in the input DataStoreAdapterException to a matching WebSphere sqlException if any.
If there is no matched exception, the original exception is returned.
If no mapping is desired, user could override this method and just return any original exception as is(without mapping)
 java.sql.SQLException mapException(java.sql.SQLException e)
          This method maps the input SQLException to a matching WebSphere sqlException if any.
If there is no matched exception, the original exception is returned.
If no mapping is desired, user could override this method and just return any original exception as is(without mapping)
 int modifyXAFlag(int xaflag)
          This method will be used modify given flag which is passed on the XA start method.
 void processGenericCredentials(javax.resource.spi.security.GenericCredential credential)
          This method processes the Generic Credentials authentication for a specific database.
 void setUserDefinedMap(java.util.Map newmap)
          This method is used to add user defined error maps.
 java.lang.String showLockInfo(java.util.Properties props)
          This method returns the lock info for use by the RAS subsystem.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

resBundle

protected static final java.lang.String resBundle

EOLN

protected static final java.lang.String EOLN

genErrorMap

protected java.util.HashMap genErrorMap
Constructor Detail

GenericDataStoreHelper

public GenericDataStoreHelper(java.util.Properties props)
Method Detail

getMetaData

public DataStoreHelperMetaData getMetaData()
This method returns the DataStore helper metadata object associated with the helper
Specified by:
getMetaData in interface DataStoreHelper
Returns:
DataStoreHelperMetaData

getIsolationLevel

public int getIsolationLevel(com.ibm.websphere.appprofile.accessintent.AccessIntent intent)
                      throws javax.resource.ResourceException
This method returns the isolation level given the Intent object. If the intent Object passed is null, the websphere default is returned. The websphere default is dependent on the backend database. In this case it will be TRANSACTION_READ_COMMITTED If this value is not desired one could override it in a subclass.
Specified by:
getIsolationLevel in interface DataStoreHelper
Parameters:
intent - AccessIntent
Returns:
int - An isolation level. The value is based on the isolation level that is defined in the java.sql.Connection.
Throws:
javax.resource.ResourceException -  
See Also:
Intent

getResultSetType

public int getResultSetType(com.ibm.websphere.appprofile.accessintent.AccessIntent intent)
                     throws javax.resource.ResourceException
This method returns the resultSet type given the Intent object. If the intent Object passed is null, the JDBC Default FETCH_FORWARD is returned If this value is not desired one could override it in a subclass.
Specified by:
getResultSetType in interface DataStoreHelper
Parameters:
intent - AccessIntent
Returns:
int - A resultType
Throws:
javax.resource.ResourceException -  
See Also:
AccessIntent

getResultSetConcurrency

public int getResultSetConcurrency(com.ibm.websphere.appprofile.accessintent.AccessIntent intent)
                            throws javax.resource.ResourceException
This method returns the resultSet concurrency given the Intent Object. If the intent Object passed is null, then JDBC default CONCUR_READ_ONLY is returned If this value is not desired one could override it in a subclass.
Specified by:
getResultSetConcurrency in interface DataStoreHelper
Parameters:
intent - AccessIntent
Returns:
int - A resultSet concurrency.
Throws:
javax.resource.ResourceException -  
See Also:
AccessIntent

processGenericCredentials

public void processGenericCredentials(javax.resource.spi.security.GenericCredential credential)
                               throws javax.resource.ResourceException
This method processes the Generic Credentials authentication for a specific database. This method is a no-op here, and is overridden in a subclass. for unsupported Database, user must subclass this class and do thier own credential processing.
Specified by:
processGenericCredentials in interface DataStoreHelper
Parameters:
credential -  
Throws:
javax.resource.ResourceException -  

isConnectionError

public final boolean isConnectionError(java.sql.SQLException ex)
This method checks if the given exception is one that caused a StaleConnectionException (connection error)
Specified by:
isConnectionError in interface DataStoreHelper
Parameters:
ex - - SQLException
Returns:
boolean - true=> yes the given exception caused the StaleConnectionException.

hasLostUpdateOrDeadLockOccurred

public java.lang.String hasLostUpdateOrDeadLockOccurred(int isoLevel,
                                                        boolean loadedForUpdate)
Should be called when storing a CMP EntityBean and pessismistic concurrency control is used. This method determines if a potential lost update or deadlock scenario has occured. If so, this method returns true else it returns false. Info must get passed on to bean provider via a warning or something similar so that they make changes to avoid these potential problems.

pre-conditions

Specified by:
hasLostUpdateOrDeadLockOccurred in interface DataStoreHelper
Parameters:
isoLevel - the isolation level used.
loadedForUpdate - true if the CMP EntityBean was loaded for update (eg. FOR UPDATE keywords used on SELECT).
Returns:
a String of message id. Note that for some db vendors where the bahaviour is different this method is over-ridden

findMappingClass

public java.lang.Class findMappingClass(java.sql.SQLException e)
This method returns mapping for a given exception if one found in the GenericHelper HashMap the search is done in the following order:
  1. first the errorCode is searched
  2. then the SQLState.

Note that in the subclasses the search will be in the same order, however if non is found then the GenericHelper HashMap will be searched also.

If a user wants to override the mapping of a specific Exception, they can override this method and either return the same exception class or return null, in the mapexception which calls this method if the map found is null then the original exception is returned.

For unsupported datastores, the GenericHelper hashtabe will be the only one to be searched unless a subclass of genericDataStoreHelper is defined for the unsupported DataStore.

Parameters:
e - The SQLException we need to find a mapping class for
Returns:
java.lang.Class - The mapped class

mapException

public final java.sql.SQLException mapException(java.sql.SQLException e)
This method maps the input SQLException to a matching WebSphere sqlException if any.
If there is no matched exception, the original exception is returned.
If no mapping is desired, user could override this method and just return any original exception as is(without mapping)
Specified by:
mapException in interface DataStoreHelper
Parameters:
e - SQLException
Returns:
SQLException mapped one For example, StaleConnectionException.

mapException

public final com.ibm.ws.rsadapter.exceptions.DataStoreAdapterException mapException(com.ibm.ws.rsadapter.exceptions.DataStoreAdapterException e)
This method maps the SQLException contained in the input DataStoreAdapterException to a matching WebSphere sqlException if any.
If there is no matched exception, the original exception is returned.
If no mapping is desired, user could override this method and just return any original exception as is(without mapping)
Specified by:
mapException in interface DataStoreHelper
Parameters:
SQLException - to be mapped.
Returns:
DataStoreAdapterException that contains the new mapped one For example, StaleConnectionException, DuplicateKeyException.

doConnectionSetup

public void doConnectionSetup(java.sql.Connection conn)
                       throws java.sql.SQLException
This method allows the DataStoreHelper to set any special connection properties that are not obtained from the configuration.
Specified by:
doConnectionSetup in interface DataStoreHelper
Parameters:
conn -  
Throws:
java.sql.SQLException -  

doConnectionCleanup

public boolean doConnectionCleanup(java.sql.Connection conn)
                            throws java.sql.SQLException
This method will do clean up on the connection. This method was added here for Informix. It supports the call natively. Subclasses should implement cleanup code here.
Specified by:
doConnectionCleanup in interface DataStoreHelper
Parameters:
conn - java.sql.Connection
Returns:
boolean - true => cleanup was done.
Throws:
java.sql.SQLException -  

doStatementCleanup

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

Clean up a statement before it is placed in the cache. This method is called only for statements which are being cached. It is called only if at least one of the following statement properties has changed,

The GenericDataStoreHelper implementation for this method resets all six of the properties listed above.

The following operations do not need to be included in the statement cleanup since they are automatically performed by WebSphere when caching statements,

A helper class implementing this method may choose to do additional cleanup for the statement. However, this should never include closing the statement, since the statement is intended to be cached.

Specified by:
doStatementCleanup in interface DataStoreHelper
Parameters:
stmt - the PreparedStatement.
Throws:
java.sql.SQLException - if an error occurs cleaning up the statement.

showLockInfo

public java.lang.String showLockInfo(java.util.Properties props)
                              throws java.lang.Exception
This method returns the lock info for use by the RAS subsystem. The subclasses will need to actually implement something here to collect the lock information from the database.
Parameters:
props - properties - contains the information to connect to a database
Returns:
String - containing the lock information
Throws:
java.lang.Exception -  

setUserDefinedMap

public void setUserDefinedMap(java.util.Map newmap)
This method is used to add user defined error maps. It is useful when the user wants a slight tweaking of the map. For a comprehensive change it might be advisable to extend this object.
Specified by:
setUserDefinedMap in interface DataStoreHelper
Parameters:
newmap - Map - a list of SQL error codes / states and the Exception class

getLockType

public int getLockType(com.ibm.websphere.appprofile.accessintent.AccessIntent intent)
This method returns a locktype based on the input AccessIntent update hint value. The locktype is used by the perssitence manager to determine whether this select statement is a normal Select, a Select for Update, Select for Update with RS or RR lock.
Specified by:
getLockType in interface DataStoreHelper
Parameters:
intent - An AccessIntent
Returns:
the locktype. The possible values are defined in com.ibm.websphere.rsadaper.WSInteractionSpec:
  • LOCKTYPE_SELECT
  • LOCKTYPE_SELECT_FOR_UPDATE

calcPartitionNumber

public short calcPartitionNumber(java.lang.String fullTableName,
                                 java.util.Properties propPartKeys)
                          throws javax.resource.ResourceException
d146350 This method allows the vendor to calculate the partition number based on the input table name and partition key properties.

Note: the subclass must implement this method if a custom data source is used.

Specified by:
calcPartitionNumber in interface DataStoreHelper
Parameters:
fullTableName - - the fully qualified table name.
propPartKeys - - the partition key properties
Returns:
a partition number. Default is -1.
Throws:
- - any exception occurs during the calculation of a partition key will result in a ResourceException

getPrintWriter

public java.io.PrintWriter getPrintWriter()
This method is used to get the printWriter to be used to output jdbc logging when database logging is enabled (e.g. WAS.database=all=enabled). by default, a null is returned and a WAS printWriter is used. Users could overwrite this method to return a different PrintWriter, and it will be used instead of the default.
Specified by:
getPrintWriter in interface DataStoreHelper
Returns:
java.io.PrintWriter.

getXAExceptionContents

public java.lang.String getXAExceptionContents(javax.transaction.xa.XAException x)
This method will be used to display in the trace file the contents of the XAException. Some backend allow for proprietary ways to display the exception contents. This method will be used for that purpose the method is a no op here
Specified by:
getXAExceptionContents in interface DataStoreHelper
Parameters:
XAException -  

modifyXAFlag

public int modifyXAFlag(int xaflag)
This method will be used modify given flag which is passed on the XA start method. Some databases (Oracle) requires a proprietary flag OracleXAResource.ORATRANSLOOSE. This method will be a no-op for all databases except Oracle
Specified by:
modifyXAFlag in interface DataStoreHelper
Parameters:
xaflag -  
Returns:
int The method will return a modified xaflag. in this case the same flag is returned

isBatchUpdateSupportedWithAccessIntent

public boolean isBatchUpdateSupportedWithAccessIntent(com.ibm.websphere.appprofile.accessintent.AccessIntent accessIntent)
This method is used to determine if Batch is supported with the given accessIntent object. there are some cases e.g. occ where some database e.g Oracle and DB2 legacy don't support occ since they don't return the actual number of records updated, rather they return -2 all the time. in those cases, we will not support batchupdate and will ignore the batchupdate setting. This method will be called indirectly by PMs code before they do the batching
Specified by:
isBatchUpdateSupportedWithAccessIntent in interface DataStoreHelper
Parameters:
accessIntent - AccessIntent
Returns:
boolean true if batching is allowd, false otherwise