Programming WebLogic Resource Adapters

Understanding Resource Adapters

The following sections introduce WebLogic resource adapters, the BEA WebLogic Server implementation of the J2EE Connector Architecture:

Overview of Resource Adapters

A resource adapter is a system library specific to an Enterprise Information System (EIS) and provides connectivity to an EIS; a resource adapter is analogous to a JDBC driver, which provides connectivity to a database management system. The interface between a resource adapter and the EIS is specific to the underlying EIS; it can be a native interface. The resource adapter plugs into an application server, such as WebLogic Server, and provides seamless connectivity between the EIS, application server, and enterprise application.

Multiple resource adapters can plug in to an application server. This capability enables application components deployed on the application server to access the underlying EISes. An application server and an EIS collaborate to keep all system-level mechanisms—transactions, security, and connection management—transparent to the application components. As a result, an application component provider can focus on the development of business and presentation logic for application components and need not get involved in the system-level issues related to EIS integration. This leads to an easier and faster cycle for the development of scalable, secure, and transactional enterprise applications that require connectivity with multiple EISes.

Comparing WebLogic Server and WebLogic Integration Resource Adapters

It is important to note the difference between BEA WebLogic Integration (WLI) resource adapters and BEA WebLogic Server resource adapters. WebLogic Integration resource adapters are written to be specific to WebLogic Server and, in general, are not deployable to other application servers. However, WebLogic Server resource adapters written without WLI extensions are deployable in any J2EE-compliant application server. This document discusses the design and implementation of non-WLI resource adapters. For more information on WebLogic Integration resource adapters, see BEA WebLogic Adapter 8.1 Documentation.

Inbound, Outbound, and Bidirectional Resource Adapters

WebLogic Server supports three types of resource adapters:

Outbound resource adapter (supported by J2EE 1.0 and 1.5 Connector Architecture)—Allows an application to connect to an EIS system and perform work. All communication is initiated by the application. In this case, the resource adapter serves as a passive library for connecting to an EIS and executes in the context of the application threads.

Outbound resource adapters based on the J2EE 1.5 Connector Architecture can be configured to have more than one simultaneous outbound connection. You can configure each outbound connection to have its own WebLogic Server-specific authentication and transaction support. See Configuring Outbound Connections.
Outbound resource adapters based on the J2EE 1.0 Connector Architecture are also supported. These resource adapters can have only one outbound connection.

Inbound resource adapter (1.5 only)—Allows an EIS to call application components and perform work. All communication is initiated by the EIS. The resource adapter may request threads from WebLogic Server or create its own threads; however, this is not the BEA-recommended approach. BEA recommends that the resource adapter submit work by way of the WorkManager. See Message and Transactional Inflow.

Note: The WebLogic Server thin-client JAR also supports the WorkManager contracts and thus can be used by non-managed resource adapters (resource adapters not running in WebLogic Server.)

Bi-directional resource adapter (1.5 only)—Supports both outbound and inbound communication.

Comparing 1.0 and 1.5 Resource Adapters

WebLogic Server supports resource adapters developed under either the J2EE 1.0 Connector Architecture or the J2EE 1.5 Connector Architecture. The J2EE 1.0 Connector Architecture restricts resource adapter communication to a single external system using one-way outbound communication. The J2EE 1.5 Connector Architecture lifts this restriction. Other capabilities provided by and for a 1.5 resource adapter that do not apply to 1.0 resource adapters include:

Outbound communication from the application to multiple systems, such as Enterprise Information Systems (EISes) and databases. See Inbound, Outbound, and Bidirectional Resource Adapters.
Inbound communication from one or more external systems such as an EIS to the resource adapter. See Handling Inbound Messages
Transactional inflow to enable a J2EE application server to participate in an XA transaction controlled by an external Transaction Manager by way of a resource adapter. See Transactional Inflow.
An application server-provided Work Manager to enable resource adapters to create threads through Work instances. See work-manager.
A life cycle contract for calling start() and stop() methods of the resource adapter by the application server. See Programming a Resource Adapter to Perform as a Startup Class.

Another important difference between 1.0 resource adapters and 1.5 resource adapters has to do with connection pools. For 1.5 resource adapters, you do not automatically get one connection pool per connection factory; you must configure a connection instance. You do so by setting the connection-instance element in the weblogic-ra.xml deployment descriptor.

Although WebLogic Server is now compliant with the J2EE 1.5 Connector Architecture, it continues to fully support the J2EE 1.0 Connector Architecture. In accordance with the J2EE 1.5 Connector Architecture, WebLogic Server now supports schema-based deployment descriptors. Resource adapters that have been developed based on the J2EE 1.0 Connector Architecture use Document Type Definition (DTD)-based deployment descriptors. Resource adapters that are built on DTD-based deployment descriptors are still supported.

This document describes the development and use of 1.5 resource adapters. For more information on WebLogic Server resources adapters that are based on the J2EE 1.0 Connector Architecture, see the BEA WebLogic Server 8.1 version of Programming WebLogic Resource Adapters.

J2EE Connector Architecture

The J2EE Connector Architecture defines a standard architecture for connecting the J2EE platform to heterogeneous Enterprise Information Systems (EISes), such as Enterprise Resource Planning (ERP) systems, mainframe transaction processing (TP), and database systems

The resource adapter serves as a protocol adapter that allows any arbitrary EIS communication protocol to be used for connectivity. An application server vendor extends its system once to support the J2EE Connector Architecture and is then assured of seamless connectivity to multiple EISes. Likewise, an EIS vendor provides one standard resource adapter that can plug in to any application server that supports the J2EE Connector Architecture.

For a more detailed overview of the J2EE Connector Architecture, see Section 3 "The Connector Architecture" of the J2CA 1.5 Specification.

J2EE Architecture Diagram and Components

Figure 2-1 and the discussion that follows describe a WebLogic Server implementation of the J2EE 1.5 Connector Architecture.

Figure 2-1 Connector Architecture Overview

Connector Architecture Overview

The connector architecture shown in Figure 2-1, Connector Architecture Overview, on page 2-5 demonstrates a bi-directional resource adapter. The following components are used in outbound connection operations:

A client application that connects to WebLogic Server, but also needs to interact with the EIS.
An application component (an EJB or servlet) that the client application uses to submit outbound requests to the EIS through the resource adapter
The WebLogic Server Connector container in which the resource adapter is deployed. The container in this example holds the following:

A deployed resource adapter that provides bi-directional (inbound and outbound) communication to and from the EIS.
One or more connection pools maintained by the container for the management of outbound managed connections for a given ManagedConnectionFactory (in this case, MCF-2—there may be more corresponding to different types of connections to a single EIS or even different EISes)
Multiple managed connections (MC1, MCn), which are objects representing the outbound physical connections from the resource adapter to the EIS.
Connection handles (C-handle) returned to the application component from the connection factory of the resource adapter and used by the application component for communicating with the EIS.

The following components are used for inbound connection operations:

One or more external message sources (MS1, MS2), which could be an Enterprise Information System (EIS) or Message Provider, and which send messages inbound to WebLogic Server.
One or more ActivationSpecs (Act Spec), each of which corresponds to a single MessageListener type (MLT-i).
A MessageEndpointFactory created by the EJB container and used by the resource adapter for inbound messaging to create proxies to MessageEndpoint instances (MDB instances from the MDB pool).
A message endpoint application (a message-driven bean (MDB) and possibly other J2EE components) that receives and handles inbound messages from the EIS through the resource adapter.

System-Level Contracts

To achieve a standard system-level pluggability between WebLogic Server and an EIS, WebLogic Server has implemented the standard set of system-level contracts defined by the J2EE Connector Architecture. These contracts consist of SPI classes and interfaces that are required to be implemented in the application server and the EIS, so that the two systems can work cooperatively. The EIS side of these system-level contracts are implemented in the resource adapter's Java classes. The following standard contracts are supported:

Connection management contract—Enables WebLogic Server to pool connections to an underlying EIS and enables application components to connect to an EIS. Also allows efficient use of connection resources through resource sharing and provides controls for associating and disassociating connection handles with EIS connections.
Transaction management contract—A contract between the transaction manager and an EIS that supports transactional access to EIS resource managers. Enables WebLogic Server to use its transaction manager to manage transactions across multiple resource managers.
Transaction inflow contract—Allows a resource adapter to propagate an imported transaction to WebLogic Server. Allows a resource adapter to flow-in transaction completion and crash recovery calls initiated by an EIS. Transaction inflow involves the use of an external transaction manager to coordinate transactions.
Security contract—Provides secure access to an EIS and support for a secure application environment that reduces security threats to the EIS and protects valuable information resources managed by the EIS.
Life cycle management contract—Enables WebLogic Server to manage the life cycle of a resource adapter. This allows bootstrapping a resource adapter instance during its deployment or application server startup, and notification to the resource adapter instance when it is undeployed or when the application server is being shut down.
Work management contract—Allows a resource adapter to do work (monitor network endpoints, call application components, and so on) by submitting Work instances to WebLogic Server for execution.
Message inflow contract—Allows a resource adapter to asynchronously or synchronously deliver messages to message endpoints residing in WebLogic Server independent of the specific messaging style, messaging semantics, and messaging infrastructure used to deliver messages. Also serves as the standard message provider pluggability contract that enables a wide range of message providers (Java Message Service, Java API for XML Messaging, and so on) to be plugged into WebLogic Server through a resource adapter.

These system-level contracts are described in detail in the J2CA 1.5 Specification.

Resource Adapter Deployment Descriptors

The structure of a resource adapter and its run-time behavior are defined in deployment descriptors. Programmers create the deployment descriptors during the packaging process, and these become part of the application deployment when the application is compiled.

WebLogic Server resource adapters have two deployment descriptors, each of which has its own XML schema:

ra.xml—The standard J2EE deployment descriptor. All resource adapters must be specified in an ra.xml deployment descriptor file. The schema for ra.xml is http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd.
weblogic-ra.xml—This WebLogic Server-specific deployment descriptor contains elements related to WebLogic Server features such as transaction management, connection management, and security. This file is required for the resource adapter to be deployed to WebLogic Server. The schema for the weblogic-ra.xml deployment descriptor file is http://www.bea.com/ns/weblogic/90/weblogic-ra.xsd. For a reference to the weblogic-ra.xml deployment descriptor, see weblogic-ra.xml Schema.