The following sections identify the requirements for developing a compliant Resource Adapter, as identified in the J2EE Platform Specification, Version 1.3 Final Release—http://java.sun.com/j2ee. The following sections correspond to the System Contract requirements identified in this specification:
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 Final Release (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 Final Release (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 Final Release (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.
