Extensions to data access APIs

Applications can access the backend data through the standard J2EE 1.4 defined application programming interfaces (APIs). The standard APIs, however, do not always provide a complete solution for an application that runs in an application server. In some cases the JDBC programming model does not completely integrate with the J2EE Connector Architecture (JCA) (even though full integration is a foundation of the JCA specification). These inconsistencies can limit data access options for an application that uses both APIs. WebSphere Application Server provides API extensions to resolve the compatibility issues.

For example:

Without the benefit of an extension, applications using both APIs cannot modify the properties of a shareable connection after making the connection request, if other handles exist for that connection. (If no other handles are associated with the connection, then the connection properties can be altered.) This limitation stems from an incompatibility between the connection-configuration policies of the APIs:

The J2EE Connector Architecture (JCA) specification supports relaying to the resource adapter the specific properties settings at the time you request the connection (using the getConnection() method) by passing in a ConnectionSpec object. The ConnectionSpec object contains the necessary connection properties used to get a connection. After you obtain a connection from this environment, your application does not need to alter the properties. The JDBC programming model, however, does not have the same interface to specify the connection properties. Instead, it gets the connection first, then sets the properties on the connection.

WebSphere Application Server provides the following extensions to fill in such gaps between the JDBC and JCA specifications:

WSDataSource interface - this interface extends the javax.sql.DataSource class, and enables a component or an application to specify the connection properties through the WebSphere Application Server JDBCConnectionSpec class to get a connection.
- getConnection(JDBCConnectionSpec) - this method returns a connection with the properties specified in the JDBCConnectionSpec class.
- For more information see the WSDataSource API documentation topic (as listed in the API documentation index).
JDBCConnectionSpec interface - this interface extends the com.ibm.websphere.rsadapter.WSConnectionSpec class, which extends the javax.resources.cci.ConnectionSpec class. The standard ConnectionSpec interface provides only the interface marker without any get() and set() methods. The WSConnectionSpec and the JDBCConnectionSpec interfaces define a set of get() and set() methods used by the WebSphere Application Server run time. This interface enables the application to specify all the essential connection properties in order to get an appropriate connection. You can create this class from the WebSphere WSRRAFactory class. For more information see the JDBCConnection API documentation topic (as listed in the API documentation index).
WSRRAFactory class - this is a factory class for the WebSphere Relational Resource Adapter, which allows the user to create a JDBCConnectionSpec object or other resource adapter related object. For more information see the WSRRAFactory API documentation topic (as listed in the API documentation index).
WSConnection interface - this is an interface that allows users to call WebSphere proprietary methods on SQL connections; those methods are:
- setClientInformation(Properties props) - See the Example: setClientInformation(Properties) API topic for more information and examples of setting client information.
- Properties getClientInformation() - This method returns the properties object that is set using setClientInformation(Properties). Note that the properties object returned is not affected by implicit settings of client information.
- WSSystemMonitor getSystemMonitor() - This method returns the SystemMonitor object from the backend database connection if the database supports System Monitors. The backend database will provide some connection statistics in the SystemMonitor object. The SystemMonitor object returned is wrapped in a WebSphere object (com.ibm.websphere.rsadapter.WSSystemMonitor) to shield applications from dependency on any database vendor code. See com.ibm.websphere.rsadapter.WSSystemMonitor Java documentation for more information. The following code is an example of using the WSSystemMonitor class:
```
import com.ibm.websphere.rsadapter.WSConnection;
...
try{
 InitialContext ctx=new InitialContext();
 // Perform a naming service lookup to get the DataSource object.
 DataSource ds=(javax.sql.DataSource]ctx.lookup("java:comp/jdbc/myDS");
} catch (Exception e) {;}

WSConnection conn=(WSConnection)ds.getConnection();
WSSystemMonitor sysMon=conn.getSystemMonitor();
if (sysMon!=null) // indicates that system monitoring is supported on the current backend database  {
  sysMon.enable(true);
  sysMon.start(WSSystemMonitor.RESET_TIMES);
  // interact with the database   sysMon.stop();
  // collect data from the sysMon object  }
conn.close();
```

Sub-topics
Example: Accessing data using IBM extended APIs for connections
Example: Accessing data using IBM extended APIs to share connections between container-managed and bean-managed persistence beans

Related concepts
Resource adapter