JCA's Infrastructure

Section overview

With a basic understanding of JCA under your belt, you're ready to begin thinking more about the elements working beneath the architecture. In this section you'll learn about the classes, interfaces, and libraries that work together to create and manage connections, fulfill complex transactions, and maintain security for JCA-compliant and -enabled systems.

Obtaining and closing a connection

An application component accesses the resource adapter through ConnectionFactory and Connection interfaces, which are provided by the resource adapter implementer. These interfaces can be CCI interfaces (javax.resource.cci.ConnectionFactory and javax.resource.cci.Connection) or they can be specific to the resource adapter. The classes that implement these interfaces are also provided with the resource adapter.

The connection factory is obtained through the Java Naming and Directory Interface (JNDI) so that the application need have no knowledge of the underlying implementation class. Once the connection factory is retrieved, a connection is obtained from the connection factory through the getConnection() method. At least one getConnection() method must be provided by the connection factory, though more may be provided. It is important to note that a Connection is an application-level handle to an underlying physical connection to the EIS, represented by a ManagedConnection, which we'll discuss later.

Once the application component is finished with the connection, it calls the close() method on the connection. A resource adapter is required to provide a method on the connection to close the connection. This method must delegate the close to the ManagedConnection that created the connection handle. Closing a connection handle should not close the physical connection to the EIS.

Connection management

The getConnection() method in the connection factory does not actually create a connection; it calls the allocateConnection() method on its associated ConnectionManager. The ConnectionManager interface is implemented by the application server. It is associated with a connection factory in an implementation-specific manner when the connection factory is instantiated. The call to the ConnectionManager allows the application server to "hook in" to the resource adapter functionality to provide pooling, transaction, and security services. A ConnectionRequestInfo object may be passed to allocateConnection() to pass connection request-specific information.

The ConnectionManager, in turn, calls on a ManagedConnection to obtain the connection handle. The connection handle is passed back through the ConnectionManager to the connection factory and on to the application component.

Connection pooling

To support connection pooling, the resource adapter provides a class that implements the ManagedConnectionFactory interface. The ManagedConnectionFactory class acts as a factory for both connection factory instances and ManagedConnection instances.

When the application server needs to create a connection factory, it calls the createConnectionFactory() method, passing in an instance of ConnectionManager; this is the instance that is called when the application component calls getConnection() on the connection factory, as discussed previously.

The application server uses one of two ManagedConnectionFactory methods to create or request managed connections. When the server requires a new instance of ManagedConnection, it calls the createManagedConnection() method. When the server wants to re-use an existing ManagedConnection, it calls the

matchManagedConnections() method. To find the right match, the server passes in a set of ManagedConnections that could possibly meet the criteria of the requested connection, along with information about the desired connection type. Internally, the

matchManagedConnection() method compares this information with the candidate set to determine if a match can be made. If so, it returns the matching ManagedConnection; if not, it returns null.


Additional connection pooling methods


The application server uses a number of additional ManagedConnection methods to facilitate connection pooling, as follows:

• The cleanup() method cleans up any client-specific state maintained by a given ManagedConnection, and invalidates all connection handles associated with that connection.
• The destroy() method is called when the server no longer needs the ManagedConnection in the pool; calling destroy() initiates the shutdown of the physical connection to the EIS.
• The addConnectionEventListener() method allows the application server to register a ConnectionEventListener with the ManagedConnection, so that the application server can be notified of close, error, and transaction occurrences. The ManagedConnection interface also provides a removeConnectionEventListener() method.

This figure shows the connection pooling process:

Transaction management

Two types of transaction management are available in JCA. The first type involves a transaction manager coordinating the activity of multiple resource managers across a single transaction. The second type involves a transaction with only a single resource manager, called a local transaction. A resource adapter can also indicate, through its deployment descriptor, that it does not support transactions.

Multiple resource managers participating in the same transaction are supported by the Java Transaction API (JTA) XAResource interface. This interface allows a transaction manager to manage transactions among multiple resources that support the interface. The ManagedConnection interface contains a method, getXAResource(), which returns an XAResource object. The application server's transaction manager uses this object to manage the transaction. For more information on XAResource, see the JTA specification.

Supporting local transactions

To support local transactions, the ManagedConnection interface provides a getLocalTransaction() method, which returns a LocalTransaction object. The LocalTransaction interface has methods on it to begin, commit, and roll back a transaction for the underlying EIS. In addition, the ManagedConnection must notify its registered ConnectionEventListeners when an application component begins, commits,

or rolls back a transaction. The ConnectionEventListener interface provides localTransactionStarted(), localTransactionCommitted(), and localTransactionRolledback() methods for this purpose. This figure shows this process:

While the getXAResource() and getLocalTransaction() methods, along with the ConnectionEventListener notifications, are all that is required for the resource adapter to support transactions, transaction management is complex, requiring considerable collaboration between the resource adapter and the application server. A detailed understanding of JTA, the Java Transaction Service (JTS), and JCA's

transaction-management contract is required to effectively provide transaction support to an EIS. See Resources on page 28 for further reading on these topics.

Security

JCA's security contract uses the Java Authentication and Authorization Service (JAAS) Subject class to provide security information. When a new ManagedConnection is created, the createManagedConnection() method is passed a Subject instance. The connection uses the Subject when it attempts to sign-on to the EIS. A Subject contains information about the Principal, or name, of the Subject, along with information about the security credentials held by the principal.

JCA defines two types of credentials. A GenericCredential is a Java wrapper, representing a specific security mechanism, such as a Kerberos credential. A

PasswordCredential holds username and password information. An application server must provide implementations of both of these interfaces.

The resource adapter's deployment descriptor lists the type of security supported, the authentication mechanism used, the interface of the credentials supported, and whether re-authentication is supported. The getConnection() method of ManagedConnection takes a Subject as a parameter to support re-authentication. The following figure shows the security management process.

Because only a couple of methods on the resource adapter are concerned with security, security management seems somewhat simple. Like transaction management, however, the complexity is in the collaboration between the application server and the resource adapter. A comprehensive understanding of JAAS and the JCA security contract is required to ensure effective security. See Resources on page 28 for more information on JAAS.

ManagedConnectionMetaData interface

While not specifically mentioned in JCA's three system contracts, the ManagedConnectionMetaData interface is an important component of JCA. It provides methods to retrieve information about the ManagedConnection and the connected EIS. This information includes:

• The product name of the EIS
• The product version of the EIS
• The maximum number of connections that the EIS can support
• The user name for the connection

---