The J2EETM Tutorial

About Resource Adapters

A resource adapter is a J2EE component that implements the J2EE Connector architecture for a specific EIS. It is through the resource adapter that a J2EE application communicates with an EIS (see Figure 17-1).

Stored in a Resource Adapter Archive (RAR) file, a resource adapter may be deployed on any J2EE server, much like the EAR file of a J2EE application. A RAR file may be contained in an EAR file or it may exist as a separate file.

A resource adapter is analogous to a JDBC driver. Both provide a standard API through which an application can access a resource that is outside the J2EE server. For a resource adapter, the outside resource is an EIS; for a JDBC driver, it is a DBMS. Resource adapters and JDBC drivers are rarely created by application developers. In most cases, both types of software are built by vendors who sell products such as tools, servers, or integration software.

Resource Adapter Contracts

Figure 17-1 shows the two types of contracts implemented by a resource adapter. The application contract defines the API through which a J2EE component such as an enterprise bean accesses the EIS. This API is the only view that the component has of the EIS. The resource adapter itself and its system contracts are transparent to the J2EE component.

The system contracts link the resource adapter to important services--connection, transaction, and security--that are managed by the J2EE server.

The connection management contract supports connection pooling, a technique that enhances application performance and scalability. Connection pooling is transparent to the application, which simply obtains a connection to the EIS.

Because of the transaction management contract, a call to the EIS may be enclosed in an XA transaction. XA transactions are global--they may contain calls to multiple EISs, databases, and enterprise bean business methods. Although often appropriate, XA transactions are not mandatory. Instead, an application may use local transactions, which are managed by the individual EIS, or it may use no transactions at all.

To protect the information in an EIS, the security management contract provides these mechanisms: authentication, authorization, and secure communication between the J2EE server and the EIS.

Figure 17-1 Accessing an EIS Through a Resource Adapter

Administering Resource Adapters

Installing a resource adapter is a two-step process:

  1. Deploy the RAR file containing the resource adapter onto a server.
    The following command, for example, deploys a sample black box resource adapter onto the local host. (For Windows, in the following commands omit the backslash character, change $J2EE_HOME to %J2EE_HOME%, and enter the entire command on a single line.)
    deploytool -deployConnector \	
       $J2EE_HOME/lib/connector/cciblackbox-tx.rar \	
  2. Add a connection factory for the resource adapter.
    Suppose that you wanted to add a connection factory for the resource adapter in the cciblackbox-tx.rar file. The JNDI name of the connection factory will be eis/MyCciBlackBoxTx. To override the default value of the property named ConnnectionURL, you specify the URL of a database. (A property is a name-value pair used to configure a connection factory.) To add the connection factory, you might enter the following j2eeadmin command:
    j2eeadmin -addConnectorFactory \	
       eis/MyCciBlackBoxTx \ 	
       cciblackbox-tx.rar \	
       -props \	

For the full syntax of the deploytool and j2eeadmin commands, see Appendix B. These commands also list and remove resource adapters and connection factories.

To list the resource adapters that have been deployed, use the following command:

deploytool -listConnectors localhost

To list the connection factories that have been added, use the following command:

j2eeadmin -listConnectorFactory

To uninstall the resource adapter deployed in step 1, use the following command:

deploytool -undeployConnector cciblackbox-tx.rar localhost

To remove the connection factory added in step 2, use the following command:

j2eeadmin -removeConnectorFactory eis/MyCciBlackBoxTx