2 Understanding Resource Adapters

Comparing WebLogic Server and WebLogic Integration Resource Adapters

It is important to note the difference between WebLogic Integration (WLI) resource adapters and 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.

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 Oracle-recommended approach. Oracle recommends that the resource adapter submit work by way of the WorkManager. See Chapter 7, "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.

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

Description of "Figure 2-1 Connector Architecture Overview"

The connector architecture shown in Figure 2-1 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 (http://java.sun.com/j2ee/connector/).