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
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:
In the Connection interface:
All other methods in this interface are not implemented; that is, a call to one of these interface methods not listed does not generate a compile error but the method has no functionality.
The interfaces in Table 9 provide the following connection-management tasks:
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.
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:
The JNDI name for an Access Resource Adapter is:
eis/CWResourceAdapter
This connection factory generates an application-level connection handle to the ICS connection.
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:
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:
This interface is internal to the application server and the resource adapter. It is not available to the application component. In a managed environment, these physical connections are opened and closed under the control of the application server. Server Access for J2EE implements the CwManagedConnection interface to represent a connection to InterChange Server.
Upon receipt of a request by the application server, an Access Resource Adapter generates a connection handle for its physical connection to ICS. The application server then distributes these connection handles to application components as needed.
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"));
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.
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:
The CwManagedConnectionFactory interface is a factory for instances of the InterChange Server connection factory.
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.
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.
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();
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.
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.