Data access exceptions

JDBC applications receive a standard SQLException if any JDBC operation fails.

The product provides special exceptions for its relational resource adapter (RRA), to indicate that the connection currently held is no longer valid:

• ConnectionWaitTimeoutException
  This exception indicates that the application timed out trying to get a connection.

• StaleConnectionException
  This exception indicates that the connection is no longer valid.

Error mapping

Error mapping is necessary because various database vendors can provide differing SQL errors and codes that might mean the same things. For example, the StaleConnectionException has different codes in different databases. The DB2 SQLCODEs of 1015, 1034, 1036 and so on, indicate that the connection is no longer available because of a temporary database problem. Other database products use other SQLCODEs to indicate the same situation.

To provide portability for applications, WebSphere Application Server - Express provides a DataStoreHelper interface to enable mapping of these codes to the WebSphere Application Server - Express exceptions. In addition, WebSphere Application Server - Express 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 or the ConnectionPoolDataSource, and it must be in compliance with the JDBC 2.0 specification.

You can achieve application portability through the following:

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

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

  For more information, see Interface DataStoreHelper in the Javadoc.

  The following code segment illustrates how to add two error codes into the error map:

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

  See the Code example disclaimer for legal information about this code example.

• WSCallHelper class
  With this class, applications can invoke any JDBC object proprietary methods that are not defined through the administrative console or standard APIs. This helper also enables applications to invoke many non-JDBC object methods.

  All methods are static. For more information, see Class WSCallHelper in the Javadoc.

  The following code segment illustrates using this helper class (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);
  

  See the Code example disclaimer for legal information about this code example.