|Oracle® Fusion Middleware User's Guide for Technology Adapters
11g Release 1 (11.1.1)
Part Number E10231-02
Oracle Application Server adapters can be integrated with various components of Oracle WebLogic Server and Oracle Fusion Middleware. This chapter discusses how to integrate adapters with Oracle WebLogic Server and Oracle Fusion Middleware.
This chapter includes the following topics:
Oracle JCA Adapters are based on the J2CA 1.5 specification and are deployed to the Oracle WebLogic Server. The resource adapter is used within the address space of the Oracle Fusion Middleware. This section provides an overview of the Oracle WebLogic Server and design-time and run-time integration with an adapter.
This section includes the following topics:
Oracle WebLogic Server is the core J2EE run-time component of Oracle Application Server. 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
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.
The following adapters support XA transactions:
Oracle MQ Series Adapter
Oracle JMS Adapter
Oracle AQ Adapter
Oracle Database Adapter
Oracle EBS Adapter
The following adapters do not support XA transactions:
Oracle File Adapter
Oracle FTP Adapter
Oracle Socket Adapter
Note that all Oracle JCA Adapters come 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.
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.
Use the adapter design-time tool to generate XML Schema Definition (XSD) files for the adapter request-response service. The Oracle WebLogic Server clients use these XSD files during run time 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.
Oracle JCA Adapters are based on the J2CA 1.5 specification but are deployed as the J2CA 1.5 resource adapter within the Oracle WebLogic Server container in this release. The J2CA 1.5 specification addresses the life-cycle management, message-inflow (for Adapter Event publish), and work management contracts.
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
The Adapter Configuration Wizard 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 Oracle JCA Adapters.
This section includes the follows topics:
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.
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.
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 need to invoke for a particular call on a particular EIS, is stored in a separate
This section describes:
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.
|Oracle Technology Adapters||Oracle JDeveloper|
|Legacy 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 run time 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
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 run time.
Figure 3-4 Configuring Packaged-Application Adapters
Oracle Application Server adapters are based on the J2CA 1.5 specification, and BPEL is deployed on the 11g run-time 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 run time. The JCA Binding Component acts as a pseudo J2CA 1.5 container.
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. This end-to-end invocation is synchronous.
You could also wrap up your custom adapter as a Web Service, and expose this to BPEL Process Manager. This is a loose coupling strategy and does not need an Adapter SDK. Both these approaches (JCA/Web service) are suitable for outbound invoke operations referred to as reference. Only the JCA 1.5 integration allows the Oracle BPEL PM to receive inbound events (from EIS to J2EE/Oracle BPEL PM). The Oracle BPEL PM acts as a pseudo JCA 1.5 container and implements the JCA 1.5-specific System Contracts.
You can use any custom design tool for the configuration of the adapter, but a WSDL file must be generated at the end of the design-time phase for consumption by the Oracle BPEL PM design-time (JDeveloper). The WSDL file for the JCA interactions have a JCA extension. The Adapter is a JCA 1.5 resource adapter deployed in the same Oracle WebLogic Server container as that of the Oracle BPEL PM product. Note that the JCA 1.5 Resource Adapter and the Oracle BPEL PM instance must be deployed in the same Oracle WebLogic Server container.
The JCA Binding Component is the glue layer that integrates the standard JCA 1.5 Resource Adapter seamlessly with the Oracle BPEL PM product at run time. The JCA Binding Component has a JCA Provider for wrapping the JCA interactions as Web Services and performs the translation between Web Service messages to JCA interaction messages based on the WSDL files generated at design time.
The following is a snippet of the
composite.xml file for an outbound invoke (referred to as reference in the 11g release):
<reference name="insert" ui:wsdlLocation="insert.wsdl"> <interface.wsdl interface="http://xmlns.oracle.com/pcbpel/adapter/db/DBRetriesApplication/XARollback/insert%2F#wsdl.interface(insert_ptt)"/> <binding.jca config="insert_db.jca"/> </reference>
The following list summarizes the process of BPEL Process Manager integration with the outbound interaction:
During design time, adapter services are exposed as WSDL files and consumed during configuration of the
PartnerLink activity of the BPEL process.
.jca file contains the JNDI address of the resource adapter,
InteractionSpec class name,
During run time, the Invoke activity of the BPEL Process Manager is used to call the
PartnerLink activity, which is a J2CA Resource Adapter outbound interaction.
The components are wired into a composite application.
The JCA Binding Component translates the event to a Web service response for consumption by the Oracle BPEL PM instance.
The outbound JCA adapter communicates with the EIS through CCI interaction.
Note:The outbound interaction with Oracle Mediator is the same as that of Oracle BPEL PM.
BPEL Process Manager receives events from the J2CA 1.5 resource adapter through the JCA Binding Component, which is the pseudo J2CA 1.5 container and implements the message inflow contracts for receiving events from the adapter. The J2CA inbound interaction is captured in a WSDL file during design time. The J2CA inbound WSDL binding section contains the J2CA 1.5
ActivationSpec parameter. The
ActivationSpec parameter captures the inbound connectivity and inbound interaction details (according to J2CA 1.5 specification). The J2CA Inbound WSDL Service section contains the J2CA 1.5
ResourceAdapter class name. In addition, the Service section can optionally contain a JNDI location.
The following list summarizes the process of BPEL Process Manager integration with the inbound interaction:
ResourceAdapter class name and the
ActivationSpec parameter are captured in the WSDL extension section of the J2CA inbound interaction WSDL during design time and made available to BPEL Process Manager and the JCA Binding Component during run time.
An instance of the J2CA 1.5
ResourceAdapter class is created, and the
Start method of the J2CA
ResourceAdapter class is called.
Each inbound interaction operation referenced by the BPEL Process Manager processes results in invoking the
EndPointActivation method of the J2CA 1.5
ResourceAdapter instance. The JCA Binding Component creates the
ActivationSpec class (Java bean) based on the
ActivationSpec details present in the WSDL extension section of the J2CA inbound interaction and activates the endpoint of the J2CA 1.5 resource adapter.
The JCA Binding Component
MessageEndpoint implementation implements the
javax.resource.cci.MessageListener interface. The J2CA 1.5 resource adapter calls the
onMessage() method in this
MessageEndpoint when it receives a back-end application event. The J2CA 1.5 resource adapter creates an instance of the
MessageEndpoint implementation through
MessageEndpointFactory provided to the resource adapter during
The JCA Binding Component receives the event through the
MessageListener class and forwards it to the Receive activity of the BPEL Process Manager instance.
When the BPEL process is stopped, all associated inbound end points are deactivated through the
endPointDeactivation method implemented by the resource adapter.
In the case of J2CA adapters, particularly the JDBC based ones, such as Oracle Database Adapter and Oracle AQ Adapter, there are two kinds of connection management at play:
for inbound (endpoint) activations (BPEL Receive)
for outbound interactions (BPEL Invoke).
In the case of inbound activations, the J2CA adapter is fully in charge of connection creation and recovery. The JCA Binding Component can only be requested to lookup and provide a J2CA
ConnectionFactory handle to the adapter through its
ActivationSpec. This is possible only if it implements a certain interface, which it can use to create connections, thereby going through the Application Server connection manager. Whenever a managed (JDBC) connection goes bad, the adapter must close the J2CA connection handle (and subsequently the managed connection if
destroy() is called by the Application Server), enter a temporary recovery loop, and then try to reestablish a new connection.
In the case of outbound interactions (J2CA), each port caches tuples of the following:
As the BPEL engine typically invokes the port concurrently with any number of threads, the size of the cache will typically reflect the highest concurrency level at any given time. The cache can be tuned to automatically expire unused tuples after a configured idle period (interactions and connection handles are then closed). The cache greatly improves performance in high load environments, for example, Retek (8 million transactions every hour).
If just one JCA adapter interaction using the cache throws a
ResourceException, then all members of the cache are closed and released immediately (purged), so new interactions will have to re-create (fresh) members to the cache. The BPEL engine has a feature known as PartnerLink retry which can be configured for each invoke. Thus, any JCA adapter invoke or interaction which throws a
ResourceException exception marked as
Retryable will make the engine retry the Invoke (Database update) which will then repopulate the port cache (if the Database has become available again: typically immediately the case with RAC).For non-transactional adapters (
adapterMetadata.supportsLocalTransactionDemarcation() == false), such as File adapter, the J2CA connection cache contains only one member. Thus all threads coming through will multiplex over the same CCI Connection handle.
The JCA connection cache can be enabled or configured explicitly by using the following
bpel.xml partnerlink properties:
Generally, this property is derived from the declared transactional support of the adapter. For example, the File adapter does not use this connection pool because it is multi thread safe, but that can be overridden through the following property:
If the property mentioned in the preceding example is not specified, then the size of the connection pool is assumed to be unbounded. This applies for each partnerlink.
The maximum age of idle connections in the pool is important because some type of connections hold on to expensive external resources, for example DB shadow processes which is measured in ms, as shown in the following example:
Finally, the property mentioned in the preceding example determines how frequently the connection pool should be scanned for idle connections, also measured in ms.
The following is a code snippet of the
composite.xml file for an inbound polling receive operation (referred to as service in the 11g release):
<service name="poll" ui:wsdlLocation="poll.wsdl"> <interface.wsdl interface="http://xmlns.oracle.com/pcbpel/adapter/db/DBRetriesApplication/ XARollback/poll%2F#wsdl.interface(poll_ptt)" (http://xmlns.oracle.com/pcbpel/adapter/db/DBRetriesApplication/XARollback/poll%2F#wsdl.interface%28poll_ptt%29)/> <binding.jca config="poll_db.jca"/> </service>
Note how the
composite.xml file links together the WSDL interface (
the interface.wsdl file), the name of the component which is handling the request (the
binding.jca file), and the binding information required to invoke a particular call (
the config file). Hence the JCA Binding Component is registered in SCA as the implementation of the
binding.jca file (others include
binding.java), while in the 10.1.3 release it was registered as a WSIF provider.
In the current release the
<binding.jca> element is in the
composite.xml file, which explicitly indicates that the JCA Binding Component is handling the invoke activity. Whereas in the 10.1.3 release you had to look at the concrete binding in the WSDL to see whether it was an adapter invoke or not, as shown in the following example:
<binding name="invokeService_binding" type="tns:invokeService_ptt"> <jca:binding /> <operation name="merge"> <jca:operation>
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
Click the Define Service icon, shown in Figure 3-6, to access the Configure Service or Adapter dialog.
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
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
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
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.
Oracle JCA Adapters can be integrated with Oracle SOA Suite.
This section includes the following:
An SOA composite application is an assembly of services, service components, references, and wires designed and deployed together 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.
A composite is an assembly of services, service components, wires, and references designed and deployed together 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
An Oracle SOA composite typically comprises the following parts:
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 WebSphere 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.
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 as well as dynamic binding at run time.
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 together 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.
The following is a sample
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 Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
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 are broken down into categories and individual tasks. The following is an example of how statistics are broken down in an outbound (reference) process:
Setting up Callable Statement
The adapter statistics can be viewed in the Fusion Middleware Control Console. The following are the steps to view the adapter statistics:
SOA folder in the Target Navigation tree (in the extreme left pane), click
The soa-infra page is displayed.
From the SOA Infrastructure menu in the soa-infra page, click Services and References, as shown in Figure 3-10.
Figure 3-10 Viewing the Adapter Statistics in the Fusion Middleware Control Console
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 > Interfaces Page