+

Search Tips   |   Advanced Search

Develop a custom DataStoreHelper class


Apply the WebSphere extension, GenericDataStoreHelper class, to create our own data store helper for data sources that the application server does not support. With this helper class, the JDBC configuration can use database-specific functions during transactions.

For a configuration with a data source not supported by the appserver, we might want to create a custom data store helper. This helper will allow us 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 the custom data handler.

Deprecated feature: The CUSTOM_HELPER constant field in the com.ibm.websphere.rsadapter.DataStoreHelper class API is deprecated. If we create our 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.depfeat

 

  1. 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 extending a helper class, it is
        
// normally not necessary to issue 'getMetaData().setHelperType(...)'
        
// because the 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;
        }
}

  2. Create our 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);
    }
}

  3. Compile the newly created DataStoreHelper class or classes.

    You will need the following JAR files in the classpath to compile them:

    • APP_ROOT/dev/Java EE/j2ee.jar
    • APP_ROOT/dev/was_public.jar

      Avoid trouble: was_public.jar contains classes from APP_ROOT/lib/rsahelpers.jar that are needed to compile a custom DataStoreHelper class.

    • APP_ROOT/plugins/com.ibm.ws.runtime.jar

    • For a development environment, such as Eclipse, we need to set the above JAR files in the classpath to be able to compile. Then, create a JAR file of the project after we have finished editing the files (see the help documentation for the development environment for specific instructions).

    • If we do not have development environment, and we are using the javac compiler:

      1. Create the .java file that extends the GenericDataStoreHelper or any other data store helper, as shown in Step 1.

      2. Change to the home directory after we are done editing the file or files in the command line utility.

      3. Set the classpath using this command:

        (Windows) 

        set CLASSPATH=%CLASSPATH%;APP_ROOT\dev\Java EE\j2ee.jar;APP_ROOT\dev\was_public.jar;APP_ROOT\plugins\com.ibm.ws.runtime.jar

        [AIX] [HP-UX] [Linux] [Solaris] 

         set CLASSPATH=$CLASSPATH:APP_ROOT/dev/Java EE/j2ee.jar:APP_ROOT/dev/was_public.jar:APP_ROOT/plugins/com.ibm.ws.runtime.jar

      4. Compile the class or classes. For example, on Windows operating systems enter the following command (this will compile all the .java files in the directory specified): 

        C:\javac the_directory\*.java

      5. From the Java directory, create a JAR file of all the compiled class files in the directory. For example, enter the following command on Windows operating systems (change myFile to the name you want for the JAR file): 

         C:\Java > jar cf myFile.jar *.class

        See on using the javac compiler go to the website for the Java compiler at Sun Microsystems.

  4. Place the compiled JAR files in a directory, and update the class path for the JDBC provider to include that location. For example, if the JAR file is c:\myFile.jar, then make sure to modify the JDBC class path to include c:\myFile.jar.

    1. Click Resources > JDBC > JDBC Providers > JDBC_provider.

    2. 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

  5. Set the appserver to use the new custom DataStoreHelper class.

    1. From the admin console select Resources > JDBC > Data Sources.

    2. Select the data source to configure with the custom DataStoreHelper class.

    3. In the section labeled Data store helper class name, select Specify a user-defined data store helper.

    4. Enter the class name for the data store helper createdd.

    5. Apply the changes and select OK.


Relational resource adapters and JCA