Data access portability features

These interfaces work with the relational resource adapter (RRA) to make database-specific functions operable on connections between the application server and that database.

In other words, the applications can access data from different databases, and use functions that are specific to the database, without any code changes. Additionally, WebSphere Application Server enables you to plug in a data source that is not supported by WebSphere persistence. However, the data source must be implemented as either the XADataSource type or the ConnectionPoolDataSource type, and it must be in compliance with the JDBC 2.x specification.

We can achieve application portability through the following:

DataStoreHelper interface

With this interface, each data store platform can plug in its own private datastore specific functions that the relational resource adapter runtime uses. WebSphere Application Server provides an implementation for each supported JDBC provider.

The interface also provides a GenericDataStoreHelper class for unsupported data sources to use. We can subclass the GenericDataStoreHelper class or other WebSphere provided helpers to support any new data source.

If we are configuring data access through a user-defined JDBC provider, do not implement the DataStoreHelper interface directly. Either subclass the GenericDataStoreHelper class or subclass one of the DataStoreHelper implementation classes provided by IBM (if the database behavior or SQL syntax is similar to one of these provided classes).

For more information, see the API documentation DataStoreHelper topic (as listed in the API documentation index).

The following code segment shows how a new data store helper is created to add new error mappings for an unsupported data source.

public class NewDSHelper extends GenericDataStoreHelper
{
  public NewDSHelper(java.util.Properties dataStoreHelperProperties)   
  {
    super(dataStoreHelperProperties); 
    java.util.Hashtable myErrorMap = null;
    myErrorMap = new java.util.Hashtable();
    myErrorMap.put(new Integer(-803), myDuplicateKeyException.class);
    myErrorMap.put(new Integer(-1015), myStaleConnectionException.class);
    myErrorMap.put("S1000", MyTableNotFoundException.class);
    setUserDefinedMap(myErrorMap);
    ...
  }
}

WSCallHelper class

This class provides two methods that enable you to use vendor-specific methods and classes that do not conform to the standard JDBC APIs (and are not part of WAS extension packages).

• jdbcCall() method

  By using the static jdbcCall() method, we can invoke vendor-specific, nonstandard JDBC methods on the JDBC objects. (For more information, see the API documentation WSCallHelper topic.) The following code segment illustrates using this method with a DB2 data source:

   
  Connection conn = ds.getConnection();
  // get connection attribute String connectionAttribute =(String) WSCallHelper.jdbcCall(DataSource.class, ds, "getConnectionAttribute", null, null);
  // setAutoClose to false WSCallHelper.jdbcCall(java.sql.Connection.class, conn, "setAutoClose", new Object[] { new Boolean(false)}, new Class[] { boolean.class });
  // get data store helper DataStoreHelper dshelper = WSCallHelper.getDataStoreHelper(ds);
  

• jdbcPass() method

  Use this method to exploit the nonstandard JDBC classes that some database vendors provide. These classes contain methods that require vendors' proprietary JDBC objects to be passed as parameters.

  In particular, implementations of Oracle can involve use of nonstandard classes furnished by the vendor. Methods contained within these classes include:

  oracle.sql.ArrayDescriptor ArrayDescriptor.createDescriptor(java.lang.String, java.sql.Connection)
  oracle.sql.ARRAY new ARRAY(oracle.sql.ArrayDescriptor, java.sql.Connection, java.lang.Object)
  oracle.xml.sql.query.OracleXMLQuery(java.sql.Connection, java.lang.String)
  oracle.sql.BLOB.createTemporary(java.sql.Connection, boolean, int)
  oracle.sql.CLOB.createTemporary(java.sql.Connection, boolean, int)
  oracle.xdb.XMLType.createXML(java.sql.Connection, java.lang.String)

  The following code sample demonstrates how to use jdbcPass to call the Oracle method XMLType.createXML on a connection. This Oracle function creates an XML type object out of the XML data that the database passes to the application.

  XMLType poXML = (XMLType)(WSCallHelper.jdbcPass(XMLType.class, 
  "createXML", new Object[]{conn,poString}, new Class[]{java.sql.Connection.class, java.lang.String.class}, new int[]{WSCallHelper.CONNECTION,WSCallHelper.IGNORE}));

  For more examples of using jdbcPass and a complete list of method parameters, see the API documentation for the WSCallHelper class. In this information center, access the API documentation with the following steps:

  1. Click Reference > Developer API documentation > Application programming interfaces

  2. Click com.ibm.websphere.rsadapter

  3. Under the Class Summary heading, click WSCallHelper
  The first section on jdbcPass discusses using the method to call database static methods. The second section on jdbcPass addresses database non-static methods.

  CAUTION: Use of the jdbcPass() method causes the JDBC object to be used outside of the protective mechanisms of WAS. Performing certain operations (such as setting autoCommit, or transaction isolation settings, etc.) outside of these protective mechanisms will cause problems with the future use of these pooled connections. IBM does not guarantee stability of the object after invocation of this method; it is the user's responsibility to ensure that invocation of this method does not perform operations that harm the object. Use at our own risk.

  Because of these potential problems, WebSphere Application Server strictly controls which methods are allowed to be invoked using the jdbcPass() method support. If we require support for a method that is not listed previously in this document, contact WebSphere Application Server Support with information on the method you require.

Related concepts

Relational resource adapters and JCA

JDBC providers

Data sources