Features

For Java developers, Java Database Connectivity (JDBC) is the only standard interface to Database Management Systems (DBMSs). As JDBC has evolved, the number of ways to connect have increased. JDBC 2 added capabilities for compatibility with J2EE. JDBC 3 generalized the structure to support Enterprise Information Systems (EISs) other than DBMSs, including messaging services.

JDBC 3 introduced J2EE Connector Architecture (JCA). The initial release of JCA (1.0) standardized interfaces to DBMSs for Application Servers. With JCA, Application Servers can access a variety of DBMSs without DBMS-specific coding. JCA also provides local and distributed transaction control, generic deployment capabilities and access outside of DBMSs to general EISs.

Sun released the final spec on JCA 1.5 in Nov., '03. While adoption of 1.5 has been slow, it does round out JCA to a complete facility. JCA 1.5 introduces Inbound Communication for compatibility with messaging and similar services. It also adds capabilities for control of Resource Adapter lifecycle and thread usage by Application Servers and improves deployment structure.

This article gives an overview of the improvements to connection structures for JDBC. It finds common threads to tie the various capabilities together into an evolutionary path. It then concentrates on a deeper examination of the J2EE Connector Architecture (JCA).

Preliminaries

Basic Client Connections
Connecting to a DBMS through JDBC uses a standard pattern for Clients. The Client Application utilizes a Connection Factory and retrieves an active JDBC Connection from it. The client performs all database access through the connection and closes it when done.

Since different classes can perform as a JDBC Connection Factory, we will use the general term of Client Connection Factory reflecting its use by the client application. We will also call the resulting connection the Client Connection, though for database access it will always be a JDBC Connection (java.sql.Connection). These are the components utilized by the client. Figure 1 shows the basic structure for the client.

For JDBC 1, the following classes implement these components:

	Basic	Standard Extension
Client Connection Factory	java.sql.DriverManager	javax.sql.DataSource
Client Connection	java.sql.Connection	java.sql.Connection

JDBC 2 Standard Extension extends DataSource with facilities for connection pooling and distributed transactions. These facilities work within Container Software, such as an Application Server.

Facilities for Application Servers
For connection pooling and distributed transactions in Application Servers, JDBC 2 introduced a second set of Connection Factory and Connection entities. The Application Server manages these entities rather than the Client Application. They are the Server Connection Factory and Server Connection. The portion of the Application Server that manages the Server Connection Factory and Server Connection is the Server Connection Manager. Figure 2 shows this structure for both the server and the client.

Unlike their client counterparts, Server Connection Factory and Server Connection interface directly with the Application Server. The server uses them to create and manage the underlying physical connection. The Server Connection Factory is a JavaBean that the Application Server configures with connection properties and retrieves the Server Connection. The resulting Server Connection object is an actual physical connection to the DBMS.

The Application Server uses the Server Connection object for storing in the connection pool and for managing distributed transactions. On client request, the Application Server retrieves a Client Connection from the Server Connection. This is a special connection object that is under control of the Application Server.

The server manages transactions for the Client Connection and the connection close. When the Client Application closes its connection, it does not actually close the physical connection. The Server Connection Manager for the server receives a notification from the Server Connection at close. It either returns the Server Connection to its pool of connections or physically closes the connection to the DBMS.

Connecting in an Application Server
The Client Application interacts with the Client Connection Factory to request a JDBC Connection with the getConnection() method. Instead of simply producing the Client Connection as before, the Client Connection factory interfaces with the Server Connection Manager, part of the Application Server. The Application Server retrieves the connection with the following steps:

1. The Client Connection Factory calls the Server Connection Manager to retrieve a Client Connection.
2. The Server Connection Manager looks in its pool for an associated Server Connection object.
3. If the pool does not contain an appropriate Server Connection, the Server Connection Manager requests a new Server Connection from the associated Server Connection Factory.
4. The Server Connection Manager uses the Server Connection to retrieve a Client Connection.
5. The Server Connection Manager passes the Client Connection back to the Client Connection Factory which returns it to the Client Application.

Figure 3 shows these steps.

JDBC 2 Standard Extension includes two sets of Server Connection Factory and Server Connection components. One set for basic connection pooling and one for distributed transactions:

	Connection Pooling	Distributed Transactions
Server Connection Factory	javax.sql.ConnectionPoolDataSource	javax.sql.XADataSource
Server Connection	javax.sql.PooledConnection	javax.sql.XAConnection

XADataSource and XAConnection extend their connection pooling counterparts.

The Server Connection Facility and Server Connection component are often part of the individual JDBC Driver which also includes the Client (JDBC) Connection. The Application Server supplies the Server Connection Manager and the Client Connection Factory. It creates and configures the Client Connection Factory using information from the Server Connection Factory.

JDBC 3 Extensions for Application Servers
JDBC 3 introduced the connector architecture as a replacement for the JDBC 2 DataSources. J2EE generalized it into the J2EE Connector Architecture (JCA). JCA removes the need for Application Server coding specific to each JDBC Driver by standardizing the components and interconnections. JCA also includes extended capabilities.

JCA uses the component structure from Figure 2. The Application Server supplies just the Server Connection Manager component. The JDBC driver, known as the Resource Adapter in JCA parlance, provides the rest -- the Server Connection Factory, Server Connection, Client Connection Factory, Client Connection components. The corresponding component to Server Connection Factory and Server Connection in JCA are:

	JCA
Server Connection Factory	javax.resource.spi.ManagedConnectionFactory
Server Connection	javax.resource.spi.ManagedConnection

JCA does not specify interfaces for Client Connection Factory and Client Connection, because the Resource Adapter need not encapsulate a JDBC Driver. The only requirement is the Client Connection Factory must be a JavaBean. When the Resource Adapter does encapsulate a JDBC Driver, the standard components are normally:

	JCA
Client Connection Factory	javax.sql.DataSource
Client Connection	java.sql.Connection

In JDBC 2, the Application Server used information from the Server Connection Factory to create a special Client Connection Factory for each JDBC Driver. JCA relieves the Application Server of this work by specifying methods in the Server Connection Factory for creation of Client Connection Factories. These are the createConnectionFactory() methods in ManagedConnectionFactory, which is the JCA version of the Server Connection Factory.

The Application Server retrieves the Client Connection Factory from createConnectionFactory() and makes it available to Client Applications through JNDI. Client Applications retrieve the Client Connection Factory with normal JNDI lookup. For JDBC access, the Client Connection Factory is a javax.sql.DataSource. The Client Application uses getConnection() method in DataSource to retrieve a JDBC connection.

Figure 3 shows the processing inside a Client Connection Factory in response to a getConnection(). The Client Connection Factory packages the connection properties and related information in a special connection request object and calls the Server Connection Manager to retrieve a new Client Connection. The Application server supplies the Server Connection Manager. For JCA, the Server Connection Manager must implement the javax.resource.spi.ConnectionManager interface.

The Client Connection Factory receives a reference to the javax.resource.spi.ConnectionManager instance when created via createConnectionFactory() in javax.resource.spi.ManagedConnectionFactory. Client Connection Factory uses that instance to call allocateConnection() in ConnectionManager. It passes the connection request object to allocateConnection() and receives a Client Connection. The connection request object is an instance of javax.resource.spi.ConnectionRequestInfo implemented by the Resource Adapter (JDBC Driver).

A Closer Look at JCA

This section will examine JCA 1.0, the initial release of the J2EE Connector Architecture. The subsequent version, JCA 1.5, though more complete, is not yet widely used. The next section will discuss the enhancements introduced by JCA 1.5

JCA 1.0 standardizes the components and their interconnections for both the Client Application and the Application Server (see Figure 2.) The scheme allows the Application Server to support connection pooling and distributed transactions. The Application Server only needs to supply the Server Connection Manager object. The Resource Adapter provides the remaining components.

For RDBMS interface, the Resource Adapter replaces (subsumes) the JDBC Driver. In JCA 1.0, Resource Adapter is a conceptual entity. JCA 1.5 defines Resource Adapter as a class implementing javax.resource.spi.ResourceAdapter. The JCA 1.5 Resource Adapter provides extended features.

JCA 1.0 is not limited to RDBMSs and JDBC Drivers. Other types of Enterprise Information Systems can use the JCA connection structure, allowing integration with Application Servers. Enterprise Information System (EIS) is the general term for any sub-system supplying information to Client Applications. Examples of non-JDBC EISs include:

• Application Sub-systems, such as ERP, CRM
• Report Servers
• Administrative Interfaces, like for a database server.

The ManagedConnectionFactory in JCA is a JavaBean. The Container configures it with connection properties relating to the target EIS. ManagedConnectionFactory normally has hostname and port number properties, for instance. Properties for the actual user login, such as user name and password, are passed to the associated Client Connection Factory. JCA separates the connection properties so that the ManagedConnectionFactory can provide ManagedConnections for a variety of users and logins, all accessing the same EIS instance.

JCA provides basic password capabilities for connections plus extended authentication and authorization. JCA accepts JAAS (Java Authentication and Authorization Services) objects. The getManagedConnection() method in ManagedConnectionFactory receives an optional javax.security.auth.Subject object. A JAAS Subject represents an authentication entity, such as a person or device.

Client Application interface to a DBMS Resource Adapter running in an Application Server is identical to JDBC DataSources. The application uses a javax.sql.DataSource object as a Connection Factory to retrieve a JDBC Connection. It looks up the DataSource using JNDI and can configure it as a JavaBean. JCA 1.0 also supports direct client use of a Resource Adapter outside of an Application Server.

Client Application Interface
With JCA, client applications access a database connection in the same manner as JDBC 2 DataSources (javax.sql.DataSource). The DataSource is a JavaBean configured and deployed by the application server. The client application retrieves a deployed DataSource with JNDI. The DataSource serves as the connection factory for JDBC Connections.

JCA uses a DataSource as its Client Connection Factory. The getConnection() methods in javax.sql.DataSource return a JDBC Connection (java.sql.Connection). Internally, the Application Server often retrieves the JDBC Connection from a connection pool in response to a getConnection(). When the Client Application calls the close() method in java.sql.Connection, the JDBC Connection returns to the pool.

Following retrieval of the JDBC Connection and before closing the connection, the client application can perform JDBC operations, communicating with the database server. In JCA, the application server normally controls transactions, so the client application cannot issue commits or rollbacks.

Example application access to JDBC driver through JCA:

// Step 1: obtain the initial JNDI naming context

Context initctx = new InitialContext();


// Step 2: perform JNDI lookup to obtain connection factory (DataSource)

javax.sql.DataSource ds = (javax.sql.DataSource)
 initctx.lookup("java:com/env/eis/FirstSQL");


// Step 3: retrieve connection from connection factory with username, password

java.sql.Connection conn = ds.getConnection("tiger", "bright");

  ~

  ~ // access database server through JDBC without commits or rollbacks

  ~

conn.close(); // close connection

Transactions: Distributed and Local
JCA gives the Application Server capabilities to control transactions for Client Applications. The Application Server can start and commit/rollback transactions for a single Resource Adapter (JDBC Driver), or it can coordinate transactions between multiple Resource Adapters for a Client Application. The ManagedConnection interface provides methods for transaction control. When transactions are under Application Server control, the Resource Adapter must block commits and rollback issued by the Client Application.

When Client Applications are only accessing a single Resource Adapter, the Application Server can choose local transaction control. It uses the getLocalTransaction() method in the ManagedConnection interface to retrieve a Local Transaction object (javax.resource.spi.LocalTransaction). LocalTransaction contains methods to start and commit or rollback transactions for the associated physical connection. The Resource Adapter implements LocalTransaction.

When more than one Resource Adapter needs to participate in a single, global transaction, the Application Server uses distributed transaction control. The participants in a distributed transaction may be heterogeneous DBMSs and/or distinct instances of the same database server. Distributed transactions use the XA standard (see References).

XA is a language-neutral architecture for distributed transactions. A distributed transaction may encompass multiple data resources (such as, database servers). XA uses Two-phase Commit to coordinate transactions among data resources.

Java Transaction Architecture (JTA) is the Java specification for XA. JTA defines an Xid interface for identifying a distributed transaction and an XAResource interface for communicating with a data resource. XAResource contains methods for enlisting a resource session into a global transaction, for performing Two-phase Commit and for recovering global transactions after a server failure.

JCA supports JTA and XA by providing access to the XAResource object associated with a Resource Adapter connection. The ManagedConnection interface contains the getXAResource() method. The Resource Adapter implements ManagedConnection and XAResource.

Non-JDBC Connections
JCA generalizes the connection architecture to include access to other Enterprise Information Systems (EISs) besides JDBC connections to DBMSs. Support for non-JDBC EISs does not require any changes to JCA processing in the Application Server. The Application Server uses the same server components as Figure 2:

	JCA
Server Connection Manager	javax.resource.spi.ConnectionManager
Server Connection Factory	javax.resource.spi.ManagedConnectionFactory
Server Connection	javax.resource.spi.ManagedConnection

The client components on the other hand do not have defined interfaces. The only requirement is that the Client Connection Factory is a JavaBean and provides a method for retrieving a Client Connection. Otherwise, the Client Connection Factory and Client Connection can take any form convenient to the EIS.

JCA does define a generic form for client components but does not require EISs to use it. This is the Common Client Interface (CCI). CCI defines specific interfaces for Client Components:

	JCA CCI
Client Connection Factory	javax.resource.cci.ConnectionFactory
Client Connection	javax.resource.cci.Connection

The CCI Connection Factory contains a getConnection() method for retrieving a CCI Connection. The CCI Connection provides a varied set of capabilities for communicating with an EIS. While capable, the CCI facilities are insufficient for complex interfaces like JDBC. CCI is also limited to Client/Server, request/response communications.

Using JCA outside of an Application Server
When an Application Server or Container utilizes a Resource Adapter, the adapter operates in a managed environment, controlled by the Container Software. In non-managed environments, Client Applications use JCA without an Application Server or Container. They directly access the Resource Adapter to retrieve Client Connections.

The Client Application retrieves a Client Connection by first creating a javax.resource.spi.ManagedConnectionFactory instance. The Resource Adapter includes a class that implements ManagedConnectionFactory. After instantiating that class, the Client Application configures it for the target EIS instance. Normally, the ManagedConnectionFactory will have setServerName() and setPortNumber() methods to set the EIS configuration.

The Client Application uses the createConnectionFactory() method in ManagedConnectionFactory to create a Client Connection Factory. For JDBC, the Client Connection Factory will be an instance of javax.sql.DataSource. The Client Application then retrieves the Client Connection (JDBC Connection) from the DataSource.

Example of Client Application retrieval of JDBC Connection directly through JCA:

// create ManagedConnectionFactory for specific Resource Adapter

ManagedConnectionFactory mcf = new EisManagedConnectionFactory();


// set configuration info

mcf.setServerName("mercury");

mcf.setPortNumber("8000");


// get DataSource (Client Connection Factory)

javax.sql.DataSource ds = (javax.sql.DataSource) mcf.createConnectionFactory();


// retrieve connection from connection factory with username, password

java.sql.Connection conn = ds.getConnection("tiger", "bright");

  ~

  ~ // access database server through JDBC

  ~

conn.close(); // close connection

The code snippet above uses the no-args form of ManagedConnectionFactory.createConnectionFactory(). With this form, the Resource Adapter supplies a default version of Server Connection Manager (javax.resource.spi.ConnectionManager) that it passes to the Client Connection Factory. When getConnection() in Client Connection Factory is called, it retrieves the Client Connection through the default Connection Manager (see Figure 3).

Client Applications can also provide their own implementation of javax.resource.spi.ConnectionManager. In this case, they call the form of ManagedConnectionFactory.createConnectionFactory() that receives a ConnectionManager instance.

Example of basic implementation of javax.resource.spi.ConnectionManager:

public class BasicConnectionManager implements ConnectionManager

{

  public Object allocateConnection(ManagedConnectionFactory mcf,
                   ConnectionRequestInfo info)

    throws ResourceException

  {

    ManagedConnection mc = mcf.createManagedConnection(null, info);

    mc.addConnectionEventListener(new ConnectionEventListener()

        { public void connectionClosed(ConnectionEvent e) { close(e); }

          public void connectionErrorOccurred(ConnectionEvent e) { close(e); }

          public void localTransactionStarted(ConnectionEvent e) { }

          public void localTransactionCommitted(ConnectionEvent e) { }

          public void localTransactionRolledback(ConnectionEvent e) { }

          protected synchronized void close(ConnectionEvent e)

          {

            if (e.getSource() instanceof ManagedConnection)

              try

              {

                ((ManagedConnection) e.getSource()).destroy();

              }

              catch (ResourceException ex) {}

          }

        }) ;

    return mc.getConnection(null, info) ;

  }

}

JCA 1.5 Improvements

JCA 1.5 introduces several enhancements to the original 1.0 release. The final spec on JCA 1.5 came out in November, 2003. JCA 1.5 defines a Resource Adapter object to give the Application Server more direct control. It also defines Inbound Communication for compatibility with messaging services and other similar services.

In JCA 1.0, the Resource Adapter is an abstract entity, not represented by any concrete class. JCA 1.5 defines an interface for the Resource Adapter, javax.resource.spi.ResourceAdapter. A JCA 1.5 Resource Adapter must include an implementation of this interface. The start() method initiates the Resource Adapter, and the stop() method terminates its processing. These methods give the Application Server control over the lifecycle of the Resource Adapter.

The start() method in javax.resource.spi.ResourceAdapter passes a javax.resource.spi.BootstrapContext instance. BootstrapContext supports Work Management by the Application Server. Work Management gives the Application Server control over any worker threads required by the Resource Adapter. This allows the Application Server to restrict thread use by the Client Application without inhibiting any Resource Adapter threads. The Resource Adapter uses Work Management to start any threads it may need.

javax.resource.spi.ResourceAdapter is a JavaBean that the Application Server sets with configuration information about the target EIS instance. When the Application Server creates a Server Connection Factory (javax.resource.spi.ManagedConnectionFactory instance), it attaches it to a started ResourceAdapter, using the setResourceAdapter() method in ManagedConnectionFactory. The ManagedConnectionFactory instance uses the configuration information from the ResourceAdapter as its defaults.

Inbound Communication
In JCA 1.0, connections are always initiated external to the Resource Adapter, either by the Application server or through direct use by the Client Application. This is known as Outbound Communication. JCA 1.5 adds Inbound Communication as a new facility. Control flows in the opposite direction with Inbound Communication. The Resource Adapter initiates the connection. JCA 1.5 Inbound Communications provides:

• Message Inflow -- the Resource Adapter asynchronously delivers messages to message endpoints (message-driven beans) residing in the Application Server.
• EJB Invocation -- the Resource Adapter calls session and entity beans residing in the Application Server.
• Transaction Inflow -- the Resource Adapter imports an external transaction into the Application Server. The Resource Adapter can treat the Application Server as a Resource Manager participating in a distributed transaction initiated by the EIS.

An example of an EIS using Inbound Communication would be a messaging server. A more complete example would be administrative (non-JDBC) services for a database server. The database server would provide Outbound Communication for administrative control of the external server. It would use Inbound Communication for logging server status.

JCA Classes

JCA 1.0
javax.resource.spi.ConnectionManager	(Server Connection Manager) A component that manages connection creation, close and pooling. Implemented in Container Software (Application Server).
javax.resource.spi.ManagedConnectionFactory	(Server Connection Factory) A JavaBean used for creating a Managed Connection, configured with server connection properties (host, port, ...). Implemented in Resource Adapter.
javax.resource.spi.ManagedConnection	(Server Connection) A JavaBean used to represent a physical connection to an EIS and used to retrieve a Client Connection and Local/Distributed Transactions. Implemented in Resource Adapter.
javax.resource.spi.LocalTransaction	A component used to control local transactions (not distributed) for a Managed Connection. Implemented in Resource Adapter.
javax.resource.spi.ConnectionRequestInfo	An object encapsulating connection properties, passed internally between various components (Managed Connection Factory, Managed Connection, Connection Manager, ...). Implemented in Resource Adapter.
javax.resource.spi.ConnectionEvent	An event object for connection events produced by Managed Connection to Connection Event Listener registrants. Implemented in Resource Adapter.
javax.resource.spi.ConnectionEventListener	A listener interface for Connection Events, registered with a Managed Connection. Implemented in Resource Adapter.
javax.resource.cci.ConnectionFactory	(Client Connection Factory) A generic Connection Factory for non-JDBC access. Optionally implemented in Resource Adapter.
javax.resource.cci.Connection	(Client Connection) A generic Connection for non-JDBC access. Optionally implemented in Resource Adapter.
JCA 1.5 Additions
javax.resource.spi.ResourceAdapter	A JavaBean to provide lifecycle control and work management. Implemented in Resource Adapter.
javax.resource.spi.BootStrapContext	A component supplying work management to Resource Adapter. Implemented in Container Software (Application Server).

Deployment

JCA provides a complete package for automatic deployment of a Resource Adapter into an Application Server. It defines the Resource Adapter Archive (RAR). The RAR contains everything needed to deploy the Resource Adapter. This includes JAR files with code for the Resource Adapter, deployment description XML, documentation and other required subsidiary files. JCA defines the following content for the RAR file:

Description	File Name	Required
Deployment descriptor	ra.xml	Yes
JAR files	*.jar	No
Documentation	howto.html	No
Auxiliary - image, locale, etc. files	varied	No
Platform-specific native libraries	varied	No

The ra.xml file contains configuration information for deploying the Resource Adapter:

• General Information -- Resource Adapter name and version, EIS type, JCA version
• Resource Adapter (1.5) -- name of Java class implementing javax.resource.spi.ResourceAdapter, list of configuration parameters
• Managed Connection Factory -- name of Java class implementing javax.resource.spi.ManagedConnectionFactory, list of configuration parameters
• Client Connection Factory -- name of Java interface and implementing class
• Connection Factory -- name of Java interface and implementing class
• Transaction Support -- none, local, distributed
• Authentication Support -- basic password, JAAS
• External Security Permissions -- list of required security permissions, e. g. tcp/ip sockets.
• Inbound Communication (1.5) -- Message Inflow, EJB Invocation, Transaction Inflow

The RAR file enables automatic deployment of a Resource Adapter into an Application Server. The deployer performs the following steps:

1. Deploy RAR into Application Server
2. Configure Resource Adapter JavaBean (JCA 1.5)
3. Configure Managed Connection Factory JavaBean

Summary

J2EE Connector Architecture (JCA) standardizes the interface between container software, such as Application Servers, and Enterprise Information Systems (EISs). An Application Server doesn't need custom code to support connectivity with a wide variety of EISs -- Database Servers, ERP Systems, Messaging Services. An EIS providing a standard Resource Adapter can plug into any container software supporting JCA.

Client Applications normally use EIS-specific interfaces. For database servers, this is JDBC. ERP systems on the other hand would provide proprietary interfaces for clients. The Connector Architecture also supports a standardized client with the Common Client Interface (CCI).

Like JDBC 2 DataSources, JCA supports connection pooling and distributed transactions (XA) for container software. It enhances this capability with:

• Resource Adapter component, standardizing the interface between the container software (Application Server) and a full variety of EISs.
• Managed environments under control of container software and non-managed environments under control of Client Applications.
• Local transactions for efficient container control of transactions that are not distributed.
• Authentication facilities, using JAAS.
• Separation of server connection information from user connection information.
• Standard packaging (RAR file) and deployment.

  JCA 1.5 adds:

• Inbound Communication, connectivity to messaging servers.
• Lifecycle and work management of Resource Adapter.

References

J2EE Connector Architecture (JCA) Specification, v 1.0: j2ee_connector-1.0-fr-spec.pdf

J2EE Connector Architecture (JCA) Specification, v 1.5: j2ee_connector-1.5-fr-spec.pdf

Java Transaction API (JTA) Specification. v 1.0.1: http://java.sun.com/products/jta/

X/Open CAE Specification -- Distributed Transaction Processing: The XA Specification: www.opengroup.org/public/pubs/catalog/c193.htm

JAAS Reference Guide for Java 2 SDK, Standard Edition, v 1.4: http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/