Managing the connection

An instance of a WebSphere Access Resource Adapter handles the opening and closing of a connection to WebSphere Interchange Server (ICS). An application component can manage this connection through the CCI interfaces that WebSphere Server Access for J2EE provides for managing a connection (see Table 9).

Table 9. Server Access for J2EE CCI implementation for managing a connection

CCI Interface Description Supported Methods
ConnectionFactory Provides an interface for obtaining a connection to InterChange Server.

Server Access for J2EE returns an instance of the ConnectionFactory instance that obtains a connection to ICS.

getConnection(), getMetaData(), getRecordFactory(), equals(), getlogWriter(), setlogWriter(), hashCode()
Connection Represents an application-level handle to access the underlying physical connection to ICS.

The getConnection() method on a ConnectionFactory instance returns a Connection instance.

close(), createInteraction(), getMetaData()
ConnectionSpec , CwConnectionSpec Passes connection-specific properties to the ConnectionFactory.getConnection() method getUserName() , setUserName(), getUserPassword(), setUserPassword()
LocalTransaction Server Access for J2EE does not implement this interface.

In Table 9, the Supported Methods column lists those interface methods that Server Access for J2EE implements. Interface methods not listed there fall into one of the following categories:

The interfaces in Table 9 provide the following connection-management tasks:

Establishing a connection

To establish a connection, the application component must obtain a ConnectionFactory instance, which is capable of generating a connection to an underlying EIS. The CCI interface that represents a handle to the ICS connection is called Connection. The way to obtain this instance depends on whether the application component is running in the managed or non-managed environment.

In a managed environment

While an Access Resource Adapter is responsible for opening and closing ICS connections, the application server determines when such activities occur. The application server creates connection pools for different connection configurations. Connection management is not the responsibility of the Access Resource Adapter. In a managed environment, the application component takes the following steps to acquire a connection to ICS through an Access Resource Adapter:

  1. Look up the ConnectionFactory instance from the Java Naming and Directory Interface (JNDI) for IBM WebSphere InterChange Server.

    The JNDI name for an Access Resource Adapter is:

    eis/CWResourceAdapter
    

    This connection factory generates an application-level connection handle to the ICS connection.

  2. Establish a connection to ICS through an Access Resource Adapter with the ConnectionFactory.getConnection() method.

    The getConnection() method returns a Connection instance. If a connection already exists in one of the application server's connection pools that can satisfy the connection request, the getConnection() method returns a handle to that connection. Otherwise, the method requests a new connection from the Access Resource Adapter.

The following code fragment shows an application component establishing a connection to ICS in the managed environment:

InitialContext ic = new InitialContext();
 
// Look up the connection factory for an Access Resource Adapter
ConnectionFactory connFactory = (Connection Factory) ic.lookup(
  "eis/CWResourceAdapter");

// Establish a connection to ICS
myConnection = connFactory.getConnection();
 
// code to request execution of the collaboration goes here
.....

// Close the connection
myConnection.close();

The following sections provide additional information about connections within the managed environment:

Sharing connections

In a managed environment, Server Access for J2EE supports connection sharing. Connection sharing is usually configurable in the application server for EJB components. Other J2EE components might have their own mechanism for connection sharing. CCI provides the following connection interfaces that are involved in connection sharing:

When the application server supports connection sharing, the application server requests multiple connection handles (Connection instances) for the same physical connection (the ManagedConnection instance). Application components are unaware that the connection handle they receive is shared. The CwManagedConnection implementation ensures that concurrent requests to the same physical connection are handled in a thread-safe manner.

Providing a different Password

The ConnectionSpec interface provides access to connection-specific properties. The implementation of the ConnectionSpec interface that Server Access for J2EE provides is called CwConnectionSpec. The application component defines how it wants to interact with Interchange Server through a CwConnectionSpec instance.

The configuration properties used to connect to ICS (see Table 8) are located in the deployment descriptor for the Access Resource Adapter. Most of these properties are not configurable at run time. However, one property that is configurable is the user password used for authorizing access to the InterChange Server system. To establish a connection with a password other than the one defined in the deployment descriptor, pass a CwConnectionSpec instance when you request the connection.

The following line of code provides the password of cwaccess3 for the admin user when it requests a connection through getConnection():

 InitialContext ic = new InitialContext();
    // Look up the connection factory for
    // IBM WebSphere InterChange Server for J2EE
    CwConnectionFactory connFactory = (CwConnection Factory) ic.lookup(
       "eis/CWConnectionFactor");
    myConnection = connFactory.getConnection(
        new CwConnectionSpec("admin", "waccess3"));

Important:
To reference the CwConnectionSpec class within an application component, you must ensure that the InterChange Server specs.jar file gets loaded. This jar file contains the CwConnectionSpec class, for which the application component needs to explicitly create instances to pass parameters to an Access Resource Adapter. Some possible ways to provide the application component with access to the specs.jar file are: adding the specs.jar file to the application component's J2EE Enterprise Archive (EAR) file, or specifying this jar file in the CLASSPATH of your application server.

In a non-managed environment

In a non-managed environment, an application component is a client application; it cannot look up a pre-existing ConnectionFactory from a JNDI service. Therefore, the client application is responsible for creating its own ConnectionFactory instance. To enable the client application to create a connection factory, CCI provides the ManagedConnectionFactory interface. The implementation of this interface that Server Access for J2EE provides is called CwManagedConnectionFactory.

Note:
In a managed environment, the application server handles the creation of the CwManagedConnectionFactory instance. Therefore, the application component does not need to use it.

The Server Access for J2EE jar file ( CWResourceAdapter.jar) contains the connection-management classes and the CCI implementation. The InterChange Server product provides a sample ConnectionManager class as part of the CWResourceAdapter.jar file. The application developer can use this default implementation. However, the ConnectionManager implementation for run time must be provided by either the application developer or third-party software. Therefore, the application developer must replace this sample with the site-specific implementation of the ConnectionManager class for run time.

In a non-managed environment, the application component takes the following steps to acquire a connection to InterChange Server through an Access Resource Adapter:

  1. Create an instance of the Server Access for J2EE's implementation of the ManagedConnectionFactory interface.

    The CwManagedConnectionFactory interface is a factory for instances of the InterChange Server connection factory.

  2. Specify the location of the Interoperable Object Reference (.ior) file with the setIorFilename() method.

    The CwManagedConnectionFactory interface provides setIorFilename() so that the client application can specify the location of the resource adapter's .ior file. The Access Resource Adapter needs the .ior file to establish a connection to ICS.

  3. Create an InterChange Server connection factory with the createConnectionFactory() method.

    The ManagedConnectionFactory interface provides the createConnectionFactory() method to create a ConnectionFactory instance. The Server Access for J2EE's implementation of createConnectionFactory() returns an InterChange Server connection factory.

  4. Establish a connection to ICS through an Access Resource Adapter with the ConnectionFactory.getConnection() method.

    The getConnection() method returns a Connection instance. If a connection already exists that can satisfy the connection request, the getConnection() method returns a handle to that connection. Otherwise, the method requests a new connection from the Access Resource Adapter. The CCI interface that represents a handle to the ICS connection is called Connection.

The following code fragment shows a client application establishing a connection to ICS:

// Obtain a CwManagedConnectionFactory instance and specify the
// location of the .ior file
CwManagedConnectionFactory mcf = new CwManagedConnectionFactory();
mcf.setIorFilename("/crossworlds/MyServer.ior");
 
// Obtain a WebSphere business integration system connection factory 
connFactory = (ConnectionFactory) mcf.createConnectionFactory();
 
// Establish a connection to ICS
myConnection = connFactory.getConnection();

Important:
As in the managed environment, the Access Resource Adapter is responsible only for opening and closing ICS connections. Connection management is not the responsibility of this resource adapter. However, in a non-managed environment, there is no application server. Therefore, the client application must handle connection management, including security strategies and connection pools.

Closing the connection

The WebSphere Access Resource Adapter does not monitor its connection to ICS. It checks for a connection only when it receives a request. If the connection is invalid, the Access Resource Adapter attempts to establish a new one. It it cannot, the resource adapter throws an appropriate ResourceException exception to notify the application component.

Note:
In a managed environment, the Access Resource Adapter also sends a CONNECTION_ERROR_OCCURRED status to the application server when it cannot reestablish a connection.

When the application component is finished using a Connection instance, it should explicitly close it. A call to the close() method does not close the underlying physical connection to the InterChange Server instance; it just notifies the application server that the physical connection can be closed if no other client applications are currently using it.

Copyright IBM Corp. 1997, 2004