Writing J2EE Connector Architecture- Compliant Resource Adapters

 

The following sections identify the requirements for developing a compliant Resource Adapter, as identified in the J2EE Platform Specification, Version 1.3, Proposed Final Draft 3—http://java.sun.com/j2ee. The following sections correspond to the System Contract requirements identified in this specification:

• Connection Management

• Security Management

• Transaction Management

• Packaging and Deployment

In addition, any Weblogic specific limitations/restrictions are identified.

Note: For instructions on building a resource adapter, see the BEA WebLogic Application Integration documentation at: http://download.oracle.com/docs/cd/E13214_01/wlintegration/v2_0/applicationintegration/devel/index.htm

 

---

Connection Management

The connection management contract requirements for a resource adapter are as follows:

• A resource adapter must provide implementations of the following interfaces:

  • javax.resource.spi.ManagedConnectionFactory

  • javax.resource.spi.ManagedConnection

  • javax.resource.spi.ManagedConnectionMetaData

• The ManagedConnection implementation provided by a resource adapter must use the following interface and classes to provide support to an application server for connection management (and transaction management, as explained later):

  • javax.resource.spi.ConnectionEvent

  • javax.resource.spi.ConnectionEventListener

    To support non-managed environments, a resource adapter is not required to use the above two interfaces to drive its internal object interactions.

• A resource adapter is required to provide support for basic error logging and tracing by implementing the following methods:

  • ManagedConnectionFactory.set/getLogWriter

  • ManagedConnnection.set/getLogWriter

• A resource adapter is required to provide a default implementation of the javax.resource.spi.ConnectionManager interface. The implementation class comes into play when a resource adapter is used in a non-managed two-tier application scenario. In an application server-managed environment, the resource adapter should not use the default ConnectionManager implementation class.

  A default implementation of ConnectionManager enables the resource adapter to provide services specific to itself. These services can include connection pooling, error logging and tracing, and security management. The default ConnectionManager delegates to the ManagedConnectionFactory the creation of physical connections to the underlying EIS.

• In a managed environment, a resource adapter is not allowed to support its own internal connection pooling. In this case, the application server is responsible for connection pooling. However, a resource adapter may multiplex connections (one or more ConnectionManager instances per physical connection) over a single physical pipe transparent to the application server and components.

  In a non-managed two-tier application scenario, a resource adapter is allowed to support connection pooling internal to the resource adapter.

 

---

Security Management

The security management contract requirements for a resource adapter are as follows:

• The resource adapter is required to support the security contract by implementing the method ManagedConnectionFactory.createManagedConnection.

• The resource adapter is not required to support re-authentication as part of its ManagedConnection.getConnection method implementation.

• The resource adapter is required to specify its support for the security contract as part of its deployment descriptor. The relevant deployment descriptor elements are: authentication-mechanism, authentication-mechanism-type, reauthentication-support and credential-interface. Refer to section 10.6, "Resource Adapter XML DTD," of the J2EE Connector Specification, Version 1.0, Proposed Final Draft 2 (http://java.sun.com/j2ee/download.html#connectorspec).

 

---

Transaction Management

This section outlines the transaction management contract requirements for a resource adapter. A resource adapter can be classified based on the level of transaction support, as follows:

• Level NoTransaction—The resource adapter supports neither resource manager local nor JTA transactions. It implements neither XAResource nor LocalTransaction interfaces.

• Level LocalTransaction—The resource adapter supports resource manager local transactions by implementing the LocalTransaction interface. The local transaction management contract is specified in section 6.7 of the J2EE Connector Specification, Version 1.0, Proposed Final Draft 2 (http://java.sun.com/j2ee/download.html#connectorspec).

• Level XATransaction—The resource adapter supports both resource manager local and JTA transactions by implementing LocalTransaction and XAResource interfaces respectively. The requirements for support XAResource-based contract are specified in section 6.6 of the J2EE Connector Specification, Version 1.0, Proposed Final Draft 2 (http://java.sun.com/j2ee/download.html#connectorspec).

Note: Other levels of support (includes any transaction optimizations supported by an underlying resource manager) are outside the scope of the Connector Architecture.

The above levels reflect the major steps of transaction support that a resource adapter needs to make to allow external transaction coordination. Depending on its transaction capabilities and requirements of its underlying EIS, a resource adapter can choose to support any one of the above transaction support levels.

 

---

Packaging and Deployment

The following sections discuss packaging and deployment requirements for resource adapters.

Restrictions

At present, the WebLogic J2EE Connector Architecture supports only serializable ConnectionFactory implementations. (Referenceable-only ConnectionFactory implementations are not supported.)

In addition, the WebLogic J2EE Connector Architecture does not support the javax.resource.spi.security.GenericCredential credential-interface or the Kerbv5 authentication-mechanism-type. Specification of either of these values for the <authentication-mechanism> in the ra.xml file for the resource adapter being deployed will result in a failed deployment.

Packaging

The file format for a packaged resource adapter module defines the contract between a resource adapter provider and deployer. A packaged resource adapter includes the following elements:

• Java classes and interfaces that are required for the implementation of both the Connector Architecture contracts and the functionality of the resource adapter

• Utility Java classes for the resource adapter

• Platform-dependent native libraries required by the resource adapter

• Help files and documentation

• Descriptive meta information that ties the above elements together

Deployment

For information on packaging requirements, refer to section 10.3.1, "Resource Adapter Provider," and section 10.5.1, "Responsibilities," of the J2EE Connector Specification, Version 1.0, Proposed Final Draft 2 (http://java.sun.com/j2ee/download.html#connectorspec). Section 10.3.1 discusses deployment requirements, while section 10.5.1 discusses how to support JNDI Configuration and Lookup.