Apply the WebSphere® extension, GenericDataStoreHelper
class, to create your own data store helper for data sources that
the application server does not support. With this helper class, your
JDBC configuration can use database-specific functions during transactions.
Before you begin
If you are using a configuration with a data source that is
not supported by the application server, you might want to create
a custom data store helper. This helper will allow you to leverage
the database to perform functions during a transaction that would
not otherwise be available. You will need to create a user-defined
DataStoreHelper class, and there is information for creating a new
exception handler to catch any exceptions that might be created with
the use of your custom data handler.
About this task
Deprecated feature: The CUSTOM_HELPER constant field
in the com.ibm.websphere.rsadapter.DataStoreHelper class API is deprecated.
If you create your own DataStoreHelper implementation class, do not
invoke setHelperType(DataStoreHelper.CUSTOM_HELPER). Instead, let
the HelperType value be set by the implementation class from which
it inherits.
Procedure
- Create a class that extends the existing data
store helpers.
Use the following code as an example;
this type of data source is based on a user-defined JDBC provider:
package com.ibm.websphere.examples.adapter;
import java.sql.SQLException;
import javax.resource.ResourceException;
import com.ibm.websphere.appprofile.accessintent.AccessIntent;
import com.ibm.websphere.ce.cm.*;
import com.ibm.websphere.rsadapter.WSInteractionSpec;
/**
* Example DataStoreHelper class, demonstrating how to create a user-defined DataStoreHelper.
* The implementation for each method is provided only as an example. More detail is probably
* required for any custom DataStoreHelper that is created for use by a real application.
* In this example, we will override the doStatementCleanup(),getIsolationLevel(), and set userDefined
* exception map.
*/
public class ExampleDataStoreHelper extends com.ibm.websphere.rsadapter.GenericDataStoreHelper
{
public ExampleDataStoreHelper(java.util.Properties props)
{
super(props);
// Update the DataStoreHelperMetaData values for this helper.
getMetaData().setGetTypeMapSupport(false);
// Update the exception mappings for this helper.
java.util.Map xMap = new java.util.HashMap();
// Add an Error Code mapping to StaleConnectionException.
xMap.put(new Integer(2310), StaleConnectionException.class);
// Add an Error Code mapping to DuplicateKeyException.
xMap.put(new Integer(1062), DuplicateKeyException.class);
// Add a SQL State mapping to the user-defined ColumnNotFoundException
xMap.put("S0022", ColumnNotFoundException.class);
// Undo an inherited StaleConnection SQL State mapping.
xMap.put("S1000", Void.class);
setUserDefinedMap(xMap);
// If you are extending a helper class, it is
// normally not necessary to issue 'getMetaData().setHelperType(...)'
// because your custom helper will inherit the helper type from its
// parent class.
}
public void doStatementCleanup(java.sql.PreparedStatement stmt) throws SQLException
{
// Clean up the statement so it may be cached and reused.
stmt.setCursorName("");
stmt.setEscapeProcessing(true);
stmt.setFetchDirection(java.sql.ResultSet.FETCH_FORWARD);
stmt.setMaxFieldSize(0);
stmt.setMaxRows(0);
stmt.setQueryTimeout(0);
}
public int getIsolationLevel(AccessIntent intent) throws ResourceException
{
// Determine an isolation level based on the AccessIntent.
// set WebSphere default isolation level to TRANSACTION_SERIALIZABLE.
if (intent == null) return java.sql.Connection.TRANSACTION_SERIALIZABLE;
return intent.getConcurrencyControl() == AccessIntent.CONCURRENCY_CONTROL_OPTIMISTIC ?
java.sql.Connection.TRANSACTION_READ_COMMITTED :
java.sql.Connection.TRANSACTION_REPEATABLE_READ;
}
public int getLockType(AccessIntent intent) {
if ( intent.getConcurrencyControl() == AccessIntent.CONCURRENCY_CONTROL_PESSIMISTIC) {
if ( intent.getAccessType() == AccessIntent.ACCESS_TYPE_READ ) {
return WSInteractionSpec.LOCKTYPE_SELECT;
}
else {
return WSInteractionSpec.LOCKTYPE_SELECT_FOR_UPDATE;
}
}
return WSInteractionSpec.LOCKTYPE_SELECT;
}
}
- Optional: Create your own exception handler
class.
Use the following code as a guide:
package com.ibm.websphere.examples.adapter;
import java.sql.SQLException;
import com.ibm.websphere.ce.cm.PortableSQLException;
/**
* Example PortableSQLException subclass, which demonstrates how to create a user-defined
* exception for exception mapping.
*/
public class ColumnNotFoundException extends PortableSQLException
{
public ColumnNotFoundException(SQLException sqlX)
{
super(sqlX);
}
}
- Compile the newly created DataStoreHelper class or classes.
You will need the following JAR files in your classpath to compile
them:
- If you are using a development environment, such as Eclipse, you need to set the previously
mentioned JAR files in your classpath to be able to compile. Then, create a JAR file of the project
after you have finished editing your files (see the help documentation for your development
environment for specific instructions).
- If you do not have development environment, and you are using
the javac compiler:
- Create your .java file that extends the GenericDataStoreHelper
or any other data store helper, as shown in Step 1.
- Change to your home directory after you are done editing your
file or files in the command line utility.
- Set the classpath using this command:
- Compile your class or classes. For example, on Windows operating
systems enter the following command (this will compile all the .java
files in the directory that you specify):
C:\javac your_directory\*.java
- From the Java directory, create a JAR file
of all the compiled class files in your directory. For example, enter
the following command on Windows operating
systems (change myFile to the name you want for
your JAR file):
C:\Java> jar cf myFile.jar *.class
For more information on using the javac compiler go to the Oracle
website for the Java™ compiler.
- Place your compiled JAR files in a directory, and update
the class path for the JDBC provider to include that location.
For example, if your JAR file is c:\myFile.jar,
then make sure to modify the JDBC class path to include c:\myFile.jar.
- Click .
- In the Class path field, add
the location of the JAR files that you compiled.
For
example, press ENTER in the field and add a new line:
c:\myFile.jar
- Configure the application server to use your new custom
DataStoreHelper class.
- From the administrative console select Resources > JDBC > Data
Sources.
- Select the data source that you want to configure with
your custom DataStoreHelper class.
- In the section labeled Data store helper
class name, select Specify a user-defined data
store helper.
- Enter the class name for the data store helper that
you created.
- Apply your changes and select OK.