Show TOC Start of Content Area

Procedure documentation Implementing Connection Management  Locate the document in its SAP Library structure

Use

To provide connectivity to the underlying EIS, the resource adapter must implement connection management logic that enables it to receive the connection request from a client, create a physical connection to the EIS, and provide a handle to this connection back to the client.

Procedure

Client-Side API

The resource adapter should provide implementations of a connection factory and a connection handle interface.

·        Connection factory

This may be an implementation of the javax.resource.cci.ConnectionFactory interface or of any other connection factory interface specific to the EIS. For example, if the EIS is a relational database, the connection factory interface is javax.sql.DataSource. The implementation of this interface provides an object used by the application to get a connection to the EIS.

In a managed environment the ConnectionFactory is obtained using a lookup operation in the naming. Therefore, the connection factory should also implement javax.io.Serializable and javax.resource.Referenceable interfaces.

The connection factory provides getConnection() methods, by which the client requests a connection via the resource adapter. The javax.resource.cci.ConnectionFactory interface also enables the client to pass its specific properties to the connection using an instance of javax.resource.cci.ConnectionSpec. To support this option, the resource adapter must implement the ConnectionSpec interface as well.

·        Connection handle

The applications use connection handles to access a physical connection to the EIS provided by the resource adapter. The client obtains a connection handle and uses the underlying physical connection through this handle. The physical connection is an instance of the ManagedConnection interface implementation.

You may implement javax.resource.cci.Connection or another connection handle interface, which corresponds to the implemented connection factory interface. For example, if the connection factory interface is javax.sql.DataSource, you have to implement java.sql.Connectionas a connection handle interface.

System API

The system-level API enables the resource adapter to:

●      Interact with the application server, on which it is deployed

●      Connect to the underlying EIS and enable the client to work with it

To implement the connection management contract on a system level, the resource adapter has to provide the following modules:

·        ManagedConnectionFactory

You must provide an implementation of the javax.resource.spi.ManagedConnectionFactory interface. The class that implements this interface is also required to implement javax.io.Serializable.

The ManagedConnectionFactory interface provides methods for creating ConnectionFactory objects. The createConnectionFactory() method may be invoked without parameters. It is typically the case in a non-managed scenario, when the ConnectionFactory is initialized with the default ConnectionManager provided by the resource adapter. In a managed scenario the application server provides the ConnectionManager implementation, which is passed as a parameter in the createConnectionFactory() method.

The ManagedConnectionFactory is also a factory for physical connections to the EIS (ManagedConnection instances). Its method createManagedConnection() initializes a ManagedConnection with security information and other resource adapter specific properties. The security parameters are passed in a javax.security.auth.Subject instance. To pass the additional properties, the resource adapter uses a javax.resource.spi.ConnectionRequestInfo instance.

In the J2EE Engine environment the physical connections to the EIS are stored in a connection pool. The resource adapter might also implement connection pooling itself. The matchManagedConnection() method of the ManagedConnectionFactory is used to match a connection from the pool. The resource adapter decides if it can match a connection by the Subject and ConnectionRequestInfo instances passed as parameters to the method. It is not obligatory to match only a connection with exactly the same Subject and ConnectionRequestInfo – the matching mechanism of the adapter also depends on the re-authentication support, as well as the security-related mappings made at deployment type. If none of the connections in the pool match the criteria, a new ManagedConnection is created.

●      ManagedConnection

The implementation of the javax.resource.spi.ManagedConnection interface represents a physical connection to the relevant EIS. The application does not work directly with this object, but uses a connection handle – for example, of type javax.resource.cci.Connection.

The ManagedConnection instantiates a connection handle when its getConnection() method is invoked. The Subject and ConnectionRequestInfo instances for the ManagedConnection are passed as parameters in this method to ensure that the connection handle is consistent with the ManagedConnection. A ManagedConnection may be shared – that is, it may support multiple connection handles associated to it at the same time. In addition, a connection handle may be associated to a ManagedConnection, which is different from its creator, using the associateConnection() method of the interface.

The ManagedConnection interface enables the application server to register connection event listeners, which notify it for connection events – for example, closing a connection. In addition, the interface provides the methods getXAResource() and getLocalTransaction(), which enable the transaction management.

If the resource adapter also provides an implementation of the javax.resource.spi.ManagedConnectionMetaData interface, which provides information about a ManagedConnection and the underlying EIS instance, the getMetaData() method may be used to retrieve the metadata.

·        ConnectionManager

It is an implementation of the javax.resource.spi.ConnectionManager interface. It processes the request for connection through its allocateConnection() method. The method delegates the request to the ManagedConnectionFactory.

In a non-managed environment, the default implementation of the ConnectionManager is used to serve the requests. It can be provided either by the resource adapter developer or by the application developer.

In a managed environment such as the J2EE Engine, a server-side implementation of ConnectionManager is passed as a parameter to the createConnectionFactory() method. Through the ConnectionManager, the request is passed to the application server, where it shares a connection, or uses the ManagedConnectionFactory to match or create a connection.

Connection Management Logic

Since the AS Java provides a managed environment for resource adapters, the connection management process is as follows:

       1.      The client obtains a ConnectionFactory from the naming context and requests a connection using the ConnectionFactory.getConnection() method.

       2.      The ConnectionFactory invokes the ConnectionManager.allocateConnection() method.

       3.      The application server applies strategies for sharing a connection, or uses the ManagedConnectionFactory to either match or create a connection.

       4.      The application server uses the ConnectionEventListener interface to register listeners that enable it to receive connection events. It also uses the getXAResource() and getLocalTransaction() methods of the ManagedConnection for the transaction management.

       5.      The application server obtains a connection handle by invoking the ManagedConnection.getConnection() method.

       6.      The client then obtains a connection handle instance and uses it to communicate with the EIS.

       7.      Once the application finishes working with the connection, it should close the connection handle using its close() method.

End of Content Area