2 Understanding Resource Adapters
This chapter describes WebLogic Server resource adapters, which provide connectivity to Enterprise Information Systems (EISes), and the Java EE Connector Architecture on which the resource adapters are based. This chapter also describes the deployment descriptors that define the structure and run-time behavior of a resource adapter that is deployed on WebLogic Server.
This chapter includes the following sections:
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 Chapter 8, "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.
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:
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 Java EE application server to participate in an XA transaction controlled by an external Transaction Manager by way of a resource adapter. See Transactional Inflow.
A Work Manager provided by WebLogic Server to enable resource adapters to create threads through
Workinstances. See work-manager.
A life cycle contract for calling
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 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.
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.xmlfile. 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.
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.
Workprocessing, which gives an application server instance's WorkManager the choice to distribute a
Workinstance submitted by a resource adapter to another
WorkManagerresiding in a different application server instance.
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 Chapter 5, "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.RuntimeTransactionSupportMBean attribute and in the Administration Console. For more information, see Supported Transaction Levels.
Ability to lookup the
TransactionSynchronizationRegistryobject in JNDI, using the standard name of
java:comp/TransactionSynchronizationRegistry. Oracle extends support by providing two additional global JNDI names:
weblogic/transaction/TransactionSynchronizationRegistry. For more information, see
Management and monitoring of long-running
Workinstances, including the number of current active work requests and the number of completed work requests, which WebLogic Server exposes on the
ConnectorWorkManagerRuntimeMBeanand in the Administration Console. See Long-Running Work Support.
Additional support for the
javax.resource.spi.RetryableExceptionexception by extending it to outbound connection pools. When you try to get a connection from a suspended connection pool, WebLogic Server throws a
RetryableApplicationServerInternalExceptionthat implements the
RetryableExceptioninterface. You can then use the
RetryableExceptioninstance to determine whether the failure is transient.
Supplemental support for the security context in the 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
Provide a means for a resource adapter to look up the
ValidatorFactoryinstances of its own beans for validation. See Bean Validation.
Return the resource adapter's
BeanManagerinstance to support CDI injection. See BeanManager, and Using Resource Adapters Deployed as CDI Bean Archives.
WorkName Hint — Names a
Workinstance and is used as part of the thread name assigned to a long-running Work instance. The
nameHintforms 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.
For a more detailed overview of the connector architecture, see Section 3, "The Connector Architecture," in JSR 322: Java EE Connector Architecture 1.6.
See also "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 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).
MessageEndpointFactorycreated by the EJB container and used by the resource adapter for inbound messaging to create proxies to
MessageEndpointinstances (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.
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
Workinstances 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 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 Java EE deployment descriptor. All resource adapters must be specified in an
ra.xmldeployment descriptor file. The schema for
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
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.xmldeployment descriptor file is
http://xmlns.oracle.com/weblogic/weblogic-connector/1.4/weblogic-connector.xsd. For a reference to the
weblogic-ra.xmldeployment descriptor, see Appendix A, "weblogic-ra.xml Schema."