3 Adapter Integration with Oracle Application Server Components

Learn how Adapters integrate with the Oracle SOA Suite and the Oracle Weblogic Server.

3.1 Adapter Integration with Oracle WebLogic Server

Oracle JCA Adapters are based on the J2CA 1.5 specification and are deployed to the Oracle WebLogic Server.

The resource adapter runs in the same Java Virtual Machine (JVM) as Fusion Middleware does. Get an overview of the Oracle WebLogic Server and design-time and runtime integration with an adapter.

3.1.1 Oracle WebLogic Server Overview

Oracle WebLogic Server is a scalable, enterprise-ready Java Platform, Enterprise Edition (Java EE) application server. The WebLogic Server infrastructure supports the deployment of many types of distributed applications. It is an ideal foundation for building applications based on Service Oriented Architecture (SOA).

All client applications run within the Oracle WebLogic Server environment. To integrate an Oracle WebLogic Server client application with a resource adapter, use the common client interface (CCI). The Oracle WebLogic Server adapter clients include a servlet, EJB, or Java application client that implements the CCI Application Programming Interface (API). The CCI defines a standard client API for application components to access the back-end application.

On the other hand, the contract between the Oracle WebLogic Server container and the resource adapter is defined by the service provider interface (SPI). Contracts define a standard between Oracle WebLogic Server and adapters. The system handles these contracts automatically and hides them from the application developer. Figure 3-1 illustrates the CCI and SPI contracts:

Figure 3-1 Contracts Between Oracle WebLogic Server and Resource Adapter

Description of Figure 3-1 follows
Description of "Figure 3-1 Contracts Between Oracle WebLogic Server and Resource Adapter"

The Oracle WebLogic Server architecture includes the following set of system-level contracts:

  • Connection management: Enables application components to connect to a back-end application and leverage any connection pooling support of the Oracle WebLogic Server container. This leads to a scalable and efficient environment that can support a large number of components requiring access to a back-end application. For more information, see Adding an Adapter Connection Factory.

  • Transaction management: Enables an application server to use a transaction manager to manage transactions across multiple resource managers. Most of the adapters support only local transactions (single-phase commit) and not XA transactions (two phase commit). For more information, see How Oracle JCA Adapters Ensure No Message Loss.

    All Oracle JCA Adapters are preconfigured with the correct value for transaction, and you must not change this configuration in the Oracle WebLogic Server Administration Console.

  • Security management: The WebLogic Server security architecture provides a comprehensive, flexible security infrastructure designed to address the security challenges of making applications available on the web. WebLogic security can be used standalone to secure WebLogic Server applications or as part of an enterprise-wide security management system that represents a best-in-breed security management solution.

3.1.2 Oracle WebLogic Server Integration with Adapters

Oracle JCA Adapters are based on the J2CA 1.5 specification and are deployed as the J2CA resource adapter within the Oracle WebLogic Server container in this release. The J2CA resource adapter is packaged into a Resource Adapter Archive (RAR) file using the Java Archive (JAR) format. A RAR file contains a correctly formatted deployment descriptor (/META-INF/ra.xml). In addition, it contains declarative information about the contract between the Oracle WebLogic Server and resource adapter.

Oracle WebLogic Server generates the corresponding weblogic-ra.xml file during the deployment of the J2CA adapter. The weblogic-ra.xml file is the deployment descriptor for a resource adapter. It contains deployment configurations for deploying resource adapters to Oracle WebLogic Server, which includes the back-end application connection information as specified in the deployment descriptor of the resource adapter, Java Naming and Directory Interface (JNDI) name to be used, connection pooling parameters, and resource principal mapping mechanism and configurations.

3.1.2.1 Design Time

Use the adapter design-time tool to generate WSLD, XSD and JCA artifacts for the adapter request-response service. Information in these artifacts would be used a runtime while creating the JCA interaction.. The Oracle WebLogic Server clients use these XSD files during runtime for calling the J2CA outbound interaction.

Packaged-application adapters use OracleAS Adapter Application Explorer (Application Explorer), Legacy adapters use OracleAS Studio, and technology adapters use Oracle JDeveloper (JDeveloper).

For more information, see Design Time.

3.1.2.2 Runtime

Oracle JCA Adapters are deployed as the J2CA 1.5 resource adapter within the Oracle WebLogic Server container. The J2CA 1.5 specification addresses the life-cycle management, message-inflow (for Adapter Event publish), and work management contracts.

3.2 Adapter Integration with Oracle Fusion Middleware

Adapters integrate with the JCA Binding Component of the Oracle Fusion Middleware platform, thereby seamlessly integrating with service engines, such as Oracle BPEL Process Manager (Oracle BPEL PM) and Oracle Mediator.

Figure 3-2 shows the architecture of Oracle JCA Adapters.

Figure 3-2 Oracle Adapter Architecture in Oracle Fusion Middleware

Description of Figure 3-2 follows
Description of "Figure 3-2 Oracle Adapter Architecture in Oracle Fusion Middleware"

. The Adapter Configuration Wizard, amongst others, generates a WSDL and a JCA properties file, which contain the binding information for that service.

Oracle technology adapters gather and publish statistics for every inbound and outbound message they process. For more information, see Monitoring .

For information on using adapters with the Oracle Service Bus, see “Using the JCA Transport and JCA Adapters” in the Developing Services with Oracle Service Bus guide. For the Open Service Bus (OSB), the only difference is that rather than having the .jca file referenced by the composite.xml itself, for OSB the file is referenced by a proxy/business service.

This section includes the follows topics:

3.2.1 Oracle BPEL Process Manager Overview

Oracle BPEL PM is a comprehensive solution for creating, deploying, and managing Oracle BPEL PM business processes. Oracle BPEL PM is based on the Service Oriented Architecture (SOA) to provide flexibility, interoperability, reusability, extensibility, and rapid implementation. Oracle BPEL PM reduces the overall cost of management, modification, extension, and redeployment of existing business processes. Each business activity is a self-contained, self-describing, modular application with an interface that is defined by a WSDL file and the business process that is modeled as a web service.

3.2.2 Oracle Mediator Overview

Oracle Mediator provides a lightweight framework to mediate between various producers and consumers of services and events. In most business environments, customer data resides in disparate sources including business partners, legacy applications, enterprise applications, databases, and custom applications. The challenge of integrating this data can be met by using Oracle Mediator to deliver appropriate real-time data access to all applications that update or have a common interest in the same data. For example, a Mediator can accept data contained in a text file from an application or service, transform it to a format appropriate for updating a database that serves as a customer repository, and then route and deliver the data to that database.

3.2.3 Oracle Fusion Middleware Integration with Adapters

The JCA Binding Component is used for the bidirectional integration of the J2CA 1.5 resource adapters with Oracle BPEL PM and Oracle Mediator. Oracle JCA Adapters generate a WSDL file and a JCA binding, and expose the underlying interactions as web Services.

The interface (input/output XML elements) to an adapter service is described through a WSDL file. However, in the 11g release, the binding element has been removed, making the WSDL file abstract. Instead the binding information, that the JCA Binding Component (referred to as adapter framework in the previous releases) and adapters must invoke for a particular call on a particular EIS, is stored in a separate binding.jca file.

This section describes:

3.2.3.1 Design Time

While integrating adapters with Oracle BPEL PM and Oracle Mediator, the underlying adapter services are exposed as WSDL files with the J2CA extension. The following table lists the design-time tools used for generating WSDL and JCA files for various types of adapters.

Adapter Tool

Oracle Technology Adapters

Oracle JDeveloper

Mainframe and TP-Monitor Adapters

Oracle Studio

Packaged-Application Adapters

Application Explorer

Oracle Adapter for Oracle Applications

Oracle JDeveloper

WSDL files are created for both request-response and event-notification services of an adapter. The J2CA extension contains J2CA elements that are required by the JCA Binding Component during runtime to convert web service messages to J2CA Interactions and back. The J2CA WSDL extension elements contain the metadata for the JCA Binding Component to call any request-response service and activate any inbound J2CA 1.5 endpoint to receive inbound events. The J2CA extension elements for the request-response service contains the JNDI location and InteractionSpec details for calling an outbound interaction. The J2CA extension elements for the event-notification service contains the resource adapter class name and ActivationSpec parameters for publishing an adapter event through the J2CA inbound interaction.

Figure 3-3 illustrates the design-time tool, JDeveloper, used by Oracle JCA Adapters.

Figure 3-3 Design Time Configuration of Technology Adapters

Description of Figure 3-3 follows
Description of "Figure 3-3 Design Time Configuration of Technology Adapters"

Figure 3-4 illustrates the design-time tool for configuring packaged-application adapters. In this figure, the design-time tools are used to expose adapter metadata as WSDL files. The WSDL files are consumed by BPEL Process Manager during runtime.

Figure 3-4 Configuring Packaged-Application Adapters

Description of Figure 3-4 follows
Description of "Figure 3-4 Configuring Packaged-Application Adapters"

3.2.3.2 Runtime

Oracle Application Server adapters are based on the J2CA 1.5 specification, and BPEL is deployed on the runtime on the Oracle WebLogic Server. The JCA Binding Component acts as a glue layer that integrates the standard J2CA 1.5 resource adapter with the Oracle BPEL Process Manager and Oracle Mediator during runtime.

The web service invocation launched by the BPEL Invoke activity is converted to a J2CA CCI outbound interaction, and the J2CA response is converted back to a web service response.

3.2.3.3 Use Case: Integration with Oracle BPEL Process Manager

From the Partner Link dialog in Oracle BPEL PM, shown in Figure 3-5, you can access the adapters that are provided with Oracle BPEL PM.

Figure 3-5 Partner Link dialog box

Description of Figure 3-5 follows
Description of "Figure 3-5 Partner Link dialog box"

Click the Define Service icon, shown in Figure 3-6, to access the Configure Service or Adapter dialog.

Figure 3-6 Defining an Adapter

Description of Figure 3-6 follows
Description of "Figure 3-6 Defining an Adapter"

This dialog enables you to configure the types of adapters shown in Figure 3-7 for use with Oracle BPEL processes.

Figure 3-7 Adapter Types

Description of Figure 3-7 follows
Description of "Figure 3-7 Adapter Types"

When you select an adapter type (Oracle AQ Adapter in this example), and then click OK, the Adapter Configuration Wizard - Welcome page appears, as shown in Figure 3-8.

Figure 3-8 The Adapter Configuration Wizard- Welcome Page

Description of Figure 3-8 follows
Description of "Figure 3-8 The Adapter Configuration Wizard- Welcome Page"

Click Next, and the Service Name page appears, as shown in Figure 3-9. You are prompted to enter a name for the service.

For this example, AQ Adapter is selected, as shown in Figure 3-7. When the wizard completes, a WSDL file by this service name appears in the Application Navigator for the BPEL process (for this example, named DequeueDemo.wsdl). This file includes the adapter configuration settings you specify with this wizard. Other configuration files (such as header properties and files specific to the adapter) are also created and displayed in the Application Navigator.

Figure 3-9 The Adapter Configuration Wizard- Service Name Page

Description of Figure 3-9 follows
Description of "Figure 3-9 The Adapter Configuration Wizard- Service Name Page"

The Adapter Configuration Wizard windows that appear after the Service Name window are based on the adapter type you selected. These configuration windows and the information you must provide are described in later chapters of this guide.

3.2.4 Oracle SOA Composite Integration with Adapters

Oracle JCA Adapters can be integrated with Oracle SOA Suite.

This section includes the following:

3.2.4.1 Oracle SOA Composite Overview

An SOA composite application is an assembly of services, service components, references, and wires designed and deployed to meet a business need.

SOA provides an enterprise architecture that supports building connected enterprise applications. SOA facilitates the development of enterprise applications as modular business web services that can be easily integrated and reused, creating a truly flexible, adaptable IT infrastructure.

3.2.4.2 Adapters Integration With Oracle SOA Composite

A composite is an assembly of services, service components, wires, and references designed and deployed in a single application. The composite processes the information described in the messages.

For example, a composite includes an inbound service binding component (an inbound adapter), a BPEL process service component, and an outbound reference binding component (an outbound adapter). The details of this composite are stored in the composite.xml file.

An Oracle SOA composite typically comprises the following parts:

  • Binding Components

    The binding component establishes the connectivity between a SOA composite and the external world. There are two types of binding components:

    • Service Binding Components

      Provide the outside world with an entry point to the SOA composite application. The WSDL file of the service informs external applications of its capabilities. These capabilities are used for contacting the SOA composite application components. The binding connectivity of the service describes the protocols that can communicate with the service, for example, Oracle JCA adapter.

    • Reference Binding Components

      Enable messages to be sent from the SOA composite application to external services in the outside world.

    The Oracle SOA Suite provides web Services, such as Oracle JCA adapters for integrating services and references with technologies (for example, databases, file systems, FTP servers, messaging: JMS, IBM MQ, and so on) and applications (Oracle E-Business Suite, PeopleSoft, and so on). This includes Oracle AQ Adapter, Oracle Database Adapter, Oracle File Adapter, Oracle FTP Adapter, Oracle JMS Adapter, Oracle MQ Series Adapter, and Oracle Socket Adapter.

  • Service Infrastructure

    Provides internal message transport. For example, receives the message from an inbound adapter and posts the message for processing to the BPEL process service engine.

  • Service Engines (containers hosting service components)

    Host the business logic or processing rules of the service components. Each service component has its own service engine. For example, an Oracle BPEL process engine or an Oracle Mediator Component.

    For more information about adapter integration with service engines, see Adapter Integration with Oracle Fusion Middleware.

  • UDDI and MDS

    The MDS (Metadata Service) repository stores descriptions of available services. The UDDI advertises these services and enables discovery and dynamic binding at runtime.

  • SOA Archive: Composite

    The deployment unit that describes the composite application.

A composite is an assembly of services (for example, inbound adapters), service components, wires, and references (for example, outbound adapters) designed and deployed in a single application. The composite processes the information described in the messages. A composite.xml file is automatically created when you create a SOA project. This file describes the entire composite assembly of services, service components, references, and wires. The composite.xml file describes the entire SOA composite.

See the example below for a sample composite.xml file.

Example - composite.xml File

Composite.xml (JCA Bindings)<?xml version="1.0" 
encoding="UTF-8" ?>
<!-- Generated by Oracle SOA Modeler version
<! -- 1.0 at [2/23/09 3:02 PM]. -->
<composite name="MediatorFlatStructure"
   revision="1.0"
   label="2009-02-23_15-02-00_374"
   mode="active"
   state="on"
   xmlns="http://xmlns.oracle.com/sca/1.0"
   xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:orawsp="http://schemas.oracle.com/ws/2006/01/policy"
   xmlns:ui="http://xmlns.oracle.com/soa/designer/">
    <import namespace="http://xmlns.oracle.com/pcbpel/
         adapter/file/SOA-FlatStructure/
         MediatorFlatStructure/MedFlatIn%2F" 
        location="MedFlatIn.wsdl" importType="wsdl"/>
    <import namespace="http://xmlns.oracle.com/pcbpel/
          adapter/file/SOA-FlatStructure/
          MediatorFlatStructure/MedFlatOut%2F" 
          location="MedFlatOut.wsdl" importType="wsdl"/>
    <service name="MedFlatIn" 
           ui:wsdlLocation="MedFlatIn.wsdl">
        <interface.wsdl interface=
                "http://xmlns.oracle.com/pcbpel/
          adapter/file/SOA-FlatStructure/
          MediatorFlatStructure/MedFlatIn%2F#wsdl.
          interface(Read_ptt)"/>
        <binding.jca config="MedFlatIn_file.jca"/>
    </service>
    <component name="MediatorFlat">
        <implementation.mediator
                src="MediatorFlat.mplan"/>
    </component>
    <reference name="MedFlatOut" 
                ui:wsdlLocation="MedFlatOut.wsdl">
        <interface.wsdl interface=
          "http://xmlns.oracle.com/pcbpel/
      adapter/file/SOA-FlatStructure/
      MediatorFlatStructure/
          MedFlatOut%2F#wsdl.interface(Write_ptt)"/>
        <binding.jca config="MedFlatOut_file.jca"/>
    </reference>
    <wire>
        <source.uri>MedFlatIn</source.uri>
        <target.uri>
             MediatorFlat/MediatorFlat</target.uri>
    </wire>
    <wire>
        <source.uri>MediatorFlat/MedFlatOut</source.uri>         <target.uri>MedFlatOut</target.uri>
    </wire>
</composite>

For more information about Oracle SOA composite and its integration with various service engines, see “Getting Started with Developing SOA Composite Applications” and other sections in the Developing SOA Applications with Oracle SOA Suite guide.

3.3 Monitoring Oracle JCA Adapters

In Oracle BPEL Process Manager and Oracle Mediator, Oracle JCA adapters such as File, JMS, and Database, gather and publish statistics for every message they process, either inbound or outbound.

The statistics of the messages are broken down into categories and individual tasks. The following is an example of how statistics are broken down in an outbound (reference) process:

  • Adapter Preprocessing

    • Preparing InteractionSpec

  • Adapter Processing

    • Setting up Callable Statement

    • Invoking Database

    • Parsing Result

  • Adapter Postprocessing

The adapter statistics can be viewed in the Fusion Middleware Control Console. The following are the steps to view the adapter statistics:

  1. Navigate to http://servername:portnumber/em.
  2. In the SOA folder in the Target Navigation tree (in the extreme left pane), click soa_infra.

    The soa-infra page is displayed.

  3. From the SOA Infrastructure menu in the soa-infra page, click Services and References.

    Figure 3-10 Viewing the Adapter Statistics in the Fusion Middleware Control Console using Diagnosability Reports

    Description of Figure 3-10 follows
    Description of "Figure 3-10 Viewing the Adapter Statistics in the Fusion Middleware Control Console using Diagnosability Reports"

    The SOA Infrastructure Home > Interfaces page is displayed, as shown in Figure 3-11.

    This page shows a list of all currently active inbound (services) and outbound adapter interactions (references), and the average execution time for the various steps each adapter performs.

    Figure 3-11 The SOA Infrastructure Home Page

    Description of Figure 3-11 follows
    Description of "Figure 3-11 The SOA Infrastructure Home Page"

    For more information on monitoring and configuring SOA Adapters, including Adapter Reporting new to this release, see the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite, in particular, the Monitoring Oracle JCA Adapters, and Configuring Oracle JCA Adapters chapters, and the Diagnosing Problems with SOA Composite Applications, which has information on using Adapter logs to assist in diagnosing SOA Composite application problems that are related to Adapters.