2 Understanding Resource Adapters

Resource adapters play a central role in the integration and connectivity between enterprise information systems (EIS) and applications deployed on Oracle WebLogic Server by communicating through well-defined contracts that are specified in the Java EE Connector Architecture. This chapter explains resource adapter concepts, and also describes the deployment descriptors that define the structure and runtime behavior of a resource adapter that is deployed on WebLogic Server.

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 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 Java EE-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 — 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 Java EE Connector Architecture 1.5 and 1.6 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 Java EE Connector Architecture 1.0 are also supported. These resource adapters can have only one outbound connection.

  • Inbound resource adapter (1.5 and 1.6 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 Message and Transactional Inflow.


    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 and 1.6 only) — Supports both outbound and inbound communication.

Connector Architecture 1.7 Support

WebLogic Server supports the following Java EE Connector Architecture (1.7) features:

  • Supports @AdministeredObjectDefinition/@AdministeredObjectDefinitions annotations and equivalent deployment descriptors for defining an administered object resource.

  • Supports @ConnectionFactoryDefinition/@ConnectionFactoryDefinitions and equivalent deployment descriptors for defining a connection factory resource.

Connector Architecture 1.6 Support

The major themes of Connector Architecture 1.6 that are supported in WebLogic Server Full Platform include the following:

  • Ease of development features

    Connector Architecture 1.6 adds a number of features to simplify the development process, such as metadata annotations and support for sparse deployment descriptors. Metadata annotations can be embedded within resource adapter class files to specify deployment information, minimizing or even eliminating the need to manually create the ra.xml file. See Using Metadata Annotations to Specify Deployment Information.

  • Generic work context

    A generic work context is the mechanism used by the resource adapter to propagate contextual information, such as the transaction context and security context, from the EIS to WebLogic Server during message delivery or submitting a work instance. For more information, see Generic Work Context.

  • Security context

    Connector Architecture 1.6 defines a standard, generic security context that leverages the work done in JSR 196: Java Authentication Service Provider Interface for Containers. For more information, see Security Inflow.

  • Miscellaneous improvements, including:

    • Integration of JSR 303: Bean Validation

    • Dynamic Reconfigurable Configuration Properties

      This includes the ability to designate specific properties of resource adapter component beans to be dynamically configurable, enabling those properties to be reconfigured at run time without requiring adapter restart or redeployment. See Dynamic Reconfigurable Configuration Properties.

    • The ability for a resource adapter to determine and classify the level of transaction support it can provide at run time. See Specifying and Obtaining Transaction Support Level.

    • Optional distributed Work processing, which gives an application server instance's WorkManager the choice to distribute a Work instance submitted by a resource adapter to another WorkManager residing in a different application server instance.

Comparing 1.0 Resource Adapters to 1.5 and 1.6

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

Another important difference between 1.0 resource adapters and 1.5 and 1.6 resource adapters is regarding connection pools. For 1.5 and 1.6 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 Full Platform is now compliant with JSR 322: Java EE Connector Architecture 1.6, it continues to fully support versions 1.0 and 1.5. In accordance with Connector Architecture 1.6, WebLogic Server supports schema-based deployment descriptors. Resource adapters that have been developed based on the Java EE Connector Architecture 1.0 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.6 resource adapters.

Additional Support Provided by the WebLogic Server Connector Container

WebLogic Server provides a number of features in its Connector container that supplement the JSR 322: Java EE Connector Architecture 1.6, including the following:

  • Support for JSR 299: Contexts and Dependency Injection for the Java EE Platform (CDI) in embedded and global resource adapters. CDI defines a set of services for using injection to specify dependencies in an application. For more information, see Using Contexts and Dependency Injection in Resource Adapters.

  • Additional runtime transaction level specification. WebLogic Server exposes information about the runtime transaction level in the ConnectorConnectionPoolRuntimeMBean.RuntimeTransactionSupport MBean attribute and in the WebLogic Server Administration Console. For more information, see Supported Transaction Levels.

  • Ability to lookup the TransactionSynchronizationRegistry object in JNDI, using the standard name of java:comp/TransactionSynchronizationRegistry. Oracle extends support by providing two additional global JNDI names: javax/transaction/TransactionSynchronizationRegistry and weblogic/transaction/TransactionSynchronizationRegistry. For more information, see javax.transaction.TransactionSynchronizationRegistry.

  • Management and monitoring of long-running Work instances, including the number of current active work requests and the number of completed work requests, which WebLogic Server exposes on the ConnectorWorkManagerRuntimeMBean and in the WebLogic Server Administration Console. See Long-Running Work Support.

  • Additional support for the javax.resource.spi.RetryableException exception by extending it to outbound connection pools. When you try to get a connection from a suspended connection pool, WebLogic Server throws a RetryableApplicationServerInternalException that implements the RetryableException interface. You can then use the RetryableException instance to determine whether the failure is transient.

  • Supplemental support for the security context in the WebLogic Server Administration Console by providing a means to create inbound EIS-to-WebLogic principal mappings, which map EIS principals, such as users or groups defined in the EIS security domain, to corresponding principals in the WebLogic domain. For more information, see Inbound Principal Mappings.

  • Support for module-level JSR 303: Bean Validation configuration. WebLogic Server extends Java EE 6 by supporting the optional use this bean configuration file to validate a resource adapter module.

  • New methods on the weblogic.connector.extensions.ExtendedBootstrapContext that:

  • Work Name Hint — Names a Work instance and is used as part of the thread name assigned to a long-running Work instance. The nameHint forms part of the thread name and is used only for long-running work. For more information, see Long-Running Work Support.

  • In resource adapters configured with multiple connection pools, the ability to isolate failed connection pools from healthy ones during deployment. This enables you to locate, diagnose, and fix failed connection pools, and then dynamically update the adapter deployment, without redeploying the resource adapter.

    The ability to detect outbound connection pool failures is available through the health monitoring feature, which is extended to resource adapters. You can access the health state of a resource adapter deployment using WLST or the WebLogic Server Administration Console. For more information, see Monitoring Resource Adapter Health, and Deploying a Resource Adapter Configured with Multiple Outbound Connection Pools.

Java EE Connector Architecture

The Java EE Connector Architecture defines a standard architecture for connecting the Java EE 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 Java EE 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 Java EE Connector Architecture.

See Resource Adapters and Contracts in The Java EE 6 Tutorial.

Java EE Architecture Diagram and Components

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

Figure 2-1 Connector Architecture Overview

Description of Figure 2-1 follows
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 Java EE 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 Java EE 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 — Extends the connection management contract by providing 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.

  • Generic work context contract — Enables a resource adapter to control the contexts in which the Work instances that it submits are executed by the WorkManager in WebLogic Server. A generic work context mechanism also enables WebLogic Server to support new message inflow and delivery schemes, providing the resource adapter with a robust contextual Work execution environment that includes the ability to manage concurrent activity.

    The generic work context contract standardizes the transaction context and the security context. JSR 322: Java EE Connector Architecture 1.6 defines this contract between the resource adapter and the application server in detail, including interfaces and classes, the thread model, rules for verifying and establishing contexts, error handling, event notifications, and so on.

  • 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 JSR 322: Java EE Connector Architecture 1.6.

Resource Adapter Deployment Descriptors

The structure of a resource adapter and its runtime 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 Java EE deployment descriptor. All resource adapters must be specified in an ra.xml deployment descriptor file. The schema for ra.xml is http://xmlns.jcp.org/xml/ns/javaee/connector_1_7.xsd.


    Connector Architecture 1.6 introduces metadata annotations, which allow you to specify deployment information in resource adapter class files, thereby minimizing or eliminating the need to manually create the deployment descriptor file ra.xml.

  • 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://xmlns.oracle.com/weblogic/weblogic-connector/1.5/weblogic-connector.xsd. For a reference to the weblogic-ra.xml deployment descriptor, see weblogic-ra.xml Schema.