Package com.bea.adapter.spi

All J2EE Connector Architecture-compliant resource adapters must provide an implementation for the interfaces in the javax.resource.spi package.

See:
Description

Class Summary

AbstractBEAManagedConnectionFactory	Extends AbstractManagedConnectionFactory to provide BEA specific license verification.
AbstractConnectionMetaData
AbstractLocalTransaction	Reduces the effort in implementing a LocalTransaction, provides logging, event notification, etc.
AbstractManagedConnection	Provides functionality that is common across resource adapters for implementing the ManagedConnection interface.
AbstractManagedConnectionFactory	A ManagedConnectionFactory creates physical connections to the underlying EIS for the application server.
ConnectionEventLogger	Used to log connection events
ConnectionRequestInfoMap
NonManagedConnectionEventListener	Used by a NonManagedConnectionManager instance to react to notifications from a ManagedConnection instance.
NonManagedConnectionManager	A connection manager allows a resource adapter to leverage the connection management offered by a J2EE CA container.
ValidationResult	Encapsulates information about a validation check; such as checking if a license is valid.

Package com.bea.adapter.spi Description

All J2EE Connector Architecture-compliant resource adapters must provide an implementation for the interfaces in the javax.resource.spi package. Each interface is described below. Along with the description is a description of how the ADK helps the adapter developer implement the interface.

javax.resource.spi.ConnectionEventListener

The ConnectionEventListener interface provides an event callback mechanism to enable an application server to receive notifications from a ManagedConnection instance.

The ADK provides two concrete implementations of this interface. com.bea.adapter.spi.ConnectionEventLogger logs connection-related events to the adapter's log. com.bea.adapter.spi.NonManagedConnectionEventListener is responsible for destroying javax.resource.spi.ManagedConnection instances when the adapter is running in a non-managed environment. In most cases, the implementations provided by the ADK will be sufficient and an adapter developer will not need to provide their own implementation for this interface.

ConnectionEventLogger: concrete implementation of the javax.resource.spi.ConnectionEventListener interface that:

• Logs connection related events using the ADK logging framework.

NonManagedConnectionEventListener: concrete implementation of the javax.resource.spi.ConnectionEventListener interface that:

• Logs connection related events using the ADK logging framework.
• Destroys ManagedConnection instances when a connection related error occurs.

javax.resource.spi.ConnectionManager

ConnectionManager interface provides a hook for the resource adapter to pass a connection request to the application server.

The ADK provides a concrete implementation of this interface. om.bea.adapter.spi.NonManagedConnectionManager provides a basic connection manager for adapter's running in a non-managed environment. In a managed environment, this interface is provided by the application server. In most cases, an adapter developer can use the implementation provided by the ADK.

NonManagedConnectionManager: concrete implementation of the javax.resource.spi.ConnectionManager interface that:

· Serves as the ConnectionManager in the non-managed scenario for a resource adapter; does not provide any connection pooling or other quality of service.

javax.resource.spi.ConnectionRequestInfo

The ConnectionRequestInfo interface enables a resource adapter to pass its own request specific data structure across the connection request flow. A resource adapter extends the empty interface to supports its own data structures for a connection request.

The ADK provides a concrete implementation of this interface.

ConnectionRequestInfoMap: concrete implementation of the javax.resource.spi.ConnectionRequestInfo interface that:

• Provides a java.util.Map interface to connection request information, such as username and password.

javax.resource.spi.LocalTransaction

LocalTransaction interface provides support for transactions that are managed internal to an EIS resource manager, and do not require an external transaction manager. The ADK provides an abstract implementation of this interface. The ADK implementation allows adapter developers to focus on implementing the EIS specific aspects of a LocalTransaction.

AbstractLocalTransaction: abstract implementation of the javax.resource.spi.LocalTransaction and javax.resource.cci.LocalTransaction interfaces that:

• Simplifies exception handling for adapter developers.
• Allows resource adapter providers to focus on implementing EIS-specific transaction logic.

· Prevents adapter developers from having a separate metadata class for the CCI and SPI implementations.

javax.resource.spi.ManagedConnection

ManagedConnection instance represents a physical connection to the underlying EIS. ManagedConnection objects are pooled by the application server in a managed environment. The ADK provides an abstract implementation of this interface. The base class provides logic for managing connection event listeners and multiple application-level connection handles per ManagedConnection instance.

When implementing the ManagedConnection interface, adapter developers need to determine the transaction demarcation support provided by the underlying EIS. A transaction is an atomic unit of work that modifies data. Transaction demarcation determines which statements in a program are included in a single transaction. The J2EE Connector Architecture defines a transaction management contract between an application server and a resource adapter (and its underlying resource manager). The transaction management contract has two parts, depending of the type of transaction.

A javax.transaction.xa.XAResource based contract between a transaction manager and a resource manager. The XA interface defines the contract between a Resource Manager and a Transaction Manager in a distributed transaction processing (DTP) environment. A JDBC driver or a JMS provider implements this interface to support association between a global transaction and a database or message service connection.

The XAResource interface can be supported by any transactional resource that is intended to be used by application programs in an environment where transactions are controlled by an external transaction manager. An example of such a resource is a database management system. An application may access data through multiple database connections. Each database connection is enlisted with the transaction manager as a transactional resource. The transaction manager obtains an XAResource for each connection participating in a global transaction. The transaction manager uses the start method to associate the global transaction with the resource, and it uses the end method to disassociate the transaction from the resource. The resource manager is responsible for associating the global transaction to all work performed on its data between the start and end method invocation.

At transaction commit time, the resource managers are informed by the transaction manager to prepare, commit, or rollback a transaction according to the two-phase commit protocol.

A local transaction management contract where a resource adapter implements the javax.resource.spi.LocalTransaction interface to provide support for local transactions that are performed on the underlying resource manager.

These contracts enable an application server to provide the infrastructure and runtime environment for transaction management. Application components rely on this transaction infrastructure to support their component-level transaction model.

The ADK provides AbstractManagedConnection, an abstract implementation for the javax.resource.spi.ManagedConnection interface that:

• Provides access to the ADK logging framework.
• Manages a collection connection event listeners.
• Provides convenience methods for notifying all connection event listeners of connection related events.

· Simplifies clean-up and destruction of a ManagedConnection instance.

javax.resource.spi.ManagedConnectionFactory

ManagedConnectionFactory instance is a factory of both ManagedConnection and EIS-specific connection factory instances. This interface supports connection pooling by providing methods for matching and creation of a ManagedConnection instance. The ADK provides an abstract implementation of this interface: AbstractManagedConnectionFactory. This abstract base class provides the following features for adapter developers:

• Provides basic support for internationalization/localization of exception and log messages for a resource adapter.
• Provides hooks into the ADK logging framework.
• Provides getter and setter methods for standard connection properties (username, password, server, connectionURL, port)
• Provides access to resource adapter metadata gathered from a java.util.ResourceBundle for an adapter.
• Allows adapter providers to plug-in license checking into the initialization process for the factory. If the license verification fails, then client applications cannot get a connection to the underlying EIS. Thus making the adapter useless.

· Provides state verification checking to support JavaBeans-style post-constructor initialization.

To use the base implementation, adapter developers must provide the following properties at deployment time:

Property Name	Property Type	Applicable Values	Description	Default
LogLevel	java.lang.String	ERROR, WARN, INFO, DEBUG	Log verbosity level.	WARN
LanguageCode	java.lang.String	valid ISO Language Code, see http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt	Used to determine desired locale for log messages	en
CountryCode	java.lang.String	valid ISO Country Code, see http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html	Used to determine desired locale for log messages	US
MessageBundleBase	java.lang.String	Any valid Java Class name or file name	Used to determine the message bundle for log messages	none, required
LogConfigFile	java.lang.String	Any valid file name	Used to configured the LOG4J system	none, required
RootLogContext	java.lang.String	Any valid Java String	Used to categorize log messages from this connection factory.	none, required
AdditionalLogContext	java.lang.String	Any valid Java String	Used to add additional information to uniquely identify messages from this factory.	none, optional

Additionally, the ADK provides AbstractBEAManagedConnectionFactory, an abstract extension of the AbstractManagedConnectionFactory class that checks for a valid BEA license (i.e. license.bea) during factory initialization. Internal BEA developers should extend com.bea.adapter.spi.AbstractBEAManagedConnectionFactory to inherit BEA license verification logic.

Lastly, the ADK contains a sample implementation sample.spi.ManagedConnectionFactoryImpl that extends AbstractManagedConnectionFactory. Adapter developers can use this class as an example of how to extend the ADK's base class.

javax.resource.spi.ManagedConnectionMetaData

The ManagedConnectionMetaData interface provides information about the underlying EIS instance associated with a ManagedConnection instance. An application server uses this information to get runtime information about a connected EIS instance.

The ADK provides AbstractManagedConnectionMetaData, an abstract implementation of the javax.resource.spi.ManagedConnectionMetaData and javax.resource.cci.ConnectionMetaData interfaces that:

• Simplifies exception handling for adapter developers.
• Provides access to an AbstractManagedConnection instance.
• Allows adapter developers to focus on implementing EIS-specific logic.

Prevents adapter developers from having a separate metadata class for the CCI and SPI implementations.

Author:

Copyright © 2000, 2001 BEA Systems, Inc. All Rights Reserved.