If a single data access API does not provide a complete
solution for your applications, use WebSphere Application Server extensions
to achieve interoperability between both the JCA and JDBC APIs.
Applications that draw from diverse and complex resource management
configurations might require use of both the J2EE Connector Architecture
(JCA) API and the Java Database Connectivity (JDBC) API. However,
in some cases the JDBC programming model does not completely integrate
with the 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: Setting client information with the 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();
The WSConnection
interface is part of the plugins_root/com.ibm.ws.runtime_6.1.0.jar file.