Client Considerations

The following sections discuss J2EE Connector Architecture client considerations:

• Common Client Interface (CCI)
• ConnectionFactory and Connection
• Obtaining the ConnectionFactory (Client-JNDI Interaction)

 

---

Common Client Interface (CCI)

The client API used by application components for EIS access can be defined as follows:

• The standard common client interface (CCI) discussed in chapter 9, "Common Client Interface," of the J2EE Connector Specification, Version 1.0 Final Release at: http://java.sun.com/j2ee/download.html#connectorspec.
• A client API specific to the type of a resource adapter and its underlying EIS. An example of such EIS-specific client APIs is JDBC for relational databases.

The CCI is a common client API for accessing EISes. The CCI is targeted towards Enterprise Application Integration (EAI) and enterprise tool vendors.

The J2EE Connector Architecture defines a Common Client Interface (CCI) for EIS access. The CCI defines a standard client API for application components that enables application components and EAI frameworks to drive interactions across heterogeneous EISes.

 

---

ConnectionFactory and Connection

A connection factory is a public interface that enables connection to an EIS instance; a ConnectionFactory interface is provided by a resource adapter. An application looks up a ConnectionFactory instance in the JNDI namespace and uses it to obtain EIS connections.

One goal of the J2EE Connector Architecture is to support a consistent application programming model across both CCI and EIS-specific client APIs. This model is achieved through use of a design pattern - specified as an interface template - for both the ConnectionFactory and Connection interfaces.

For more information on this design pattern, see section 5.5.1, "ConnectionFactory and Connection" of the J2EE Connector Specification, Version 1.0 Final Release at: http://java.sun.com/j2ee/download.html#connectorspec

 

---

Obtaining the ConnectionFactory (Client-JNDI Interaction)

This section discusses how a connection to an EIS instance is obtained from a ConnectionFactory. For further information, refer to section 5.4.1, "Managed Application Scenario," of the J2EE Connector Specification, Version 1.0 Final Release at: http://java.sun.com/j2ee/download.html#connectorspec

 

Obtaining a Connection in a Managed Application

The following tasks are performed when a managed application obtains a connection to an EIS instance from a ConnectionFactory, as specified in the res-type variable:

1. The application assembler or component provider specifies the connection factory requirements for an application component by using a deployment descriptor mechanism. For example:
   • res-ref-name: eis/myEIS
   • res-type: javax.resource.cci.ConnectionFactory
   • res-auth: Application or Container
2. The person deploying the resource adapter sets the configuration information for the resource adapter.
3. The application server uses a configured resource adapter to create physical connections to the underlying EIS. Refer to Chapter 10 of the J2EE Connector Specification, Version 1.0 Final Release for more information on packaging and deployment of resource adapters at: http://java.sun.com/j2ee/download.html#connectorspec
4. The application component looks up a connection factory instance in the component's environment by using the JNDI interface.

Listing 7-1 JNDI Lookup

//obtain the initial JNDI Naming context

Context initctc = new InitialContext();

// perform JNDI lookup to obtain the connection factory

javax.resource.cci.ConnectionFactory cxf = 

 (javax.resource.cci.ConnectionFactory)

  initctx.lookup("java:comp/env/eis/MyEIS");

The JNDI name passed in the method NamingContext.lookup is the same as that specified in the res-ref-name element of the deployment descriptor. The JNDI lookup results in a connection factory instance of type java.resource.cci.ConnectionFactory as specified in the res-type element.

1. The application component invokes the getConnection method on the connection factory to obtain an EIS connection. The returned connection instance represents an application level handle to an underlying physical connection. An application component obtains multiple connections by calling the method getConnection on the connection factory multiple times.

 javax.resource.cci.Connection cx = cxf.getConnection();

1. The application component uses the returned connection to access the underlying EIS.
2. After the component finishes with the connection, it closes the connection using the close method on the Connection interface.

 cx.close();

1. If an application component fails to close an allocated connection after its use, that connection is considered an unused connection. The application server manages the cleanup of unused connections.

 

Obtaining a Connection in a Non-Managed Application

In a non-managed application scenario, the application developer must follow a similar programming model to that of a managed application. Non-management involves lookup of a connection factory instance, obtaining an EIS connection, using the connection for EIS access, and finally closing the connection.

The following tasks are performed when a non-managed application obtains a connection to an EIS instance from a ConnectionFactory:

1. The application client calls a method on the javax.resource.cci.ConnectionFactory instance (returned from the JNDI lookup) to get a connection to the underlying EIS instance.
2. The ConnectionFactory instance delegates the connection request from the application to the default ConnectionManager instance. The resource adapter provides the default ConnectionManager implementation.
3. The ConnectionManager instance creates a new physical connection to the underlying EIS instance by calling the ManagedConnectionFactory.createManagedConnection method.
4. The ManagedConnectionFactory instance handles the createManagedConnection method by creating a new physical connection to the underlying EIS, represented by a ManagedConnection instance. The ManagedConnectionFactory uses the security information (passed as a Subject instance), any ConnectionRequestInfo, and its configured set of properties (such as port number, server name) to create a new ManagedConnection instance.
5. The ConnectionManager instance calls the ManagedConnection.getConnection method to get an application-level connection handle. Calling the getConnection method does not necessarily create a new physical connection to the EIS instance. Calling getConnection produces a temporary handle that is used by an application to access the underlying physical connection. The actual underlying physical connection is represented by a ManagedConnection instance.
6. The ConnectionManager instance returns the connection handle to the ConnectionFactory instance, which then returns the connection to the application that initiated the connection request.