|
Oracle® Application Server Adapter Concepts Guide
10g Release 2 (10.1.2) B14058-04 |
|
 Previous |
 Next |
|
Oracle® Application Server Adapter Concepts Guide
10g Release 2 (10.1.2) B14058-04 |
|
|
Previous |
Next |
Oracle Application Server adapters can be integrated with various components such as Oracle Application Server Containers for J2EE (OC4J), Oracle Application Server InterConnect, and Business Process Execution Language for Web services (BPEL) Process Manager. This chapter discusses how to integrate adapters with OC4J, BPEL Process Manager, and OracleAS Integration InterConnect.
This chapter contains the following topics:
Oracle Application Server adapters are deployed as J2EE Connector Architecture (J2CA) 1.0 resource adapters in an OC4J container. The resource adapter is used within the address space of the Oracle Application Server. This section provides an overview of OC4J and design-time and run time integration with an adapter. This section contains the following topics:
OC4J is the core J2EE run-time component of Oracle Application Server. OC4J is a J2EE 1.3 compliant container that runs on a standard JDK 1.4 Java Virtual Machine (JVM) and provides complete support for Java Server Page (JSP) files, servlets, enterprise java beans (EJBs), Web services, and all J2EE services. In addition, OC4J consists of a J2CA container for hosting J2CA resource adapters. J2CA defines standard Java interfaces for simplifying the integration of a J2EE server with various back-end applications.
All client applications run within the OC4J environment. To integrate an OC4J client application with a resource adapter, use the common client interface (CCI). The OC4J 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 OC4J container and the resource adapter is defined by the service provider interface (SPI). Contracts define a standard between OC4J and adapters. The system handles these contracts automatically and hides them from the application developer. The following figure illustrates the CCI and SPI contracts:
Figure 5-1 Contracts between OC4J and Resource Adapter
The OC4J 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 OC4J container. This leads to a scalable and efficient environment that can support a large number of components requiring access to a back-end application.
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).
Security management: Provides authentication, authorization, and secure communication between the J2EE server and the back-end application. The OC4J supports both container-managed (the Oracle Application Server is responsible for sending security credentials to the back-end application) and component-managed sign-on (the J2CA adapter is responsible for forwarding the security credentials to the back-end application).
Oracle Application Server adapters are J2CA 1.5 based and deployed within OC4J during installation. The OC4J component supports only the J2CA 1.0 specification in this release. The J2CA resource adapter is packaged into a Resource Adapter Archive (RAR) file using the Java Archive (JAR) format. An RAR file contains a correctly formatted deployment descriptor (/META-INF/ra.xml). In addition, it contains declarative information about the contract between the OC4J and resource adapter.
OC4J generates the corresponding oc4j-ra.xml file during the deployment of the J2CA adapter. The oc4j-ra.xml file is the deployment descriptor for a resource adapter. It contains deployment configurations for deploying resource adapters to OC4J, 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.
Design Time
Use the adapter design-time tool to generate XML Schema Definition (XSD) files for the adapter request-response service. The OC4J clients use these XSD files during run time for calling the J2CA outbound interaction. Packaged-application adapters use OracleAS Adapter for Application Explorer (Application Explorer), Legacy adapters use OracleAS Studio, and technology adapters use JDeveloper.
Run Time
Oracle Application Server adapters are based on the J2CA 1.5 specification but are deployed as the J2CA 1.0 resource adapter within the OC4J container in this release. The J2CA 1.0 specification addresses the request-response service also known as outbound interaction and does not address the asynchronous publication of back-end events by the adapter. The J2CA 1.5 specification addresses the life-cycle management, message-inflow (for Adapter Event publish) and work management contracts.
Oracle Application Server adapters can be integrated with BPEL Process Manager. This section discusses the follows topics:
BPEL Process Manager is a comprehensive solution for creating, deploying, and managing BPEL business processes. BPEL Process Manager is based on the Service Oriented Architecture (SOA) to provide flexibility, interoperability, reusability, extensibility, and rapid implementation. BPEL Process Manager 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.
Adapter Framework is used for the bidirectional integration of the J2CA 1.5 resource adapters with BPEL Process Manager. Adapter Framework is based on standards and employs the Web service Invocation Framework (WSIF) technology for exposing the underlying J2CA interactions as Web services.
Design Time
While integrating adapters with BPEL Process Manager, 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 files for various types of adapters.
| Adapter | Tool |
|---|---|
| Technology and OracleAS Adapter for Oracle Applications | JDeveloper |
| Packaged application | Application Explorer |
| Legacy | Oracle Studio |
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 Adapter Framework during run time to convert Web service messages to J2CA Interactions and back. The J2CA WSDL extension elements contain the metadata for Adapter Framework 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 5-2 illustrates the design time tool, JDeveloper, used by technology adapters.
Figure 5-2 Design Time Configuration of Technology Adapters
Figure 5-3 illustrates the design-time tool for configuring packaged-application and legacy 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 5-3 Configuring Legacy and Packaged-Application Adapters
Run Time
Oracle Application Server adapters are based on J2CA 1.5 specification and deployed with the Oracle BPEL Process Manager in the same OC4J container. Adapter Framework acts as the glue layer that integrates the standard J2CA 1.5 resource adapter with the Oracle BPEL Process Manager during run time. Adapter Framework acts as a psuedo-J2CA 1.5 container, which enables implementation although the Oracle Application Server OC4J container supports only J2CA 1.0. Adapter Framework consists of a WSIF J2CA Provider for wrapping the J2CA interactions as Web services. In addition, Adapter Framework translates Web service messages to J2CA interaction message based on the WSDL files generated during design time.
The WSIF Provider converts the Web service invocation (from BPEL PM Invoke activity) to a J2CA outbound interaction call and performs the reverse conversion in the other direction. In other words, 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. The WSIF Provider also supports the one-way asynchronous J2CA outbound interaction invocation. The WSIF Provider element hides the J2CA implementation details from the BPEL Process Manager process and the Web service details from the J2CA 1.5 resource adapter.
BPEL Process Manager Integration with Outbound Interaction
BPEL Process Manager uses the WSIF technology to start the request-response service of the resource adapter. WSIF is used for calling Web services and separating the abstract part of the Web service definition from the physical binding (transport and protocol) to generate a Service-Oriented Architecture (SOA). 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.
The WSDL extensions specify the JNDI address of the resource adapter, InteractionSpec class name, InteractionSpec parameters.
During run time, the Invoke activity of the BPEL Process Manager is used to call the PartnerLink activity, which is J2CA Resource Adapter outbound interaction.
The WSIF J2CA provider receives the Web service request from BPEL Process Manager.
The WSDL file associated with this Web service request contains the JNDI name of the J2CA ConnectionFactory class in the WSDL extension element.
The WSIF provider performs the JNDI lookup and obtains a Connection instance.
The WSIF provider creates an InteractionSpec Bean object from the WSDL extension element jca:operation.
The WSIF provider starts the J2CA outbound interaction by passing the InteractionSpec, the InputRecord, and an empty OutputRecord parameter.
The J2CA 1.5 resource adapter calls the back-end application and returns the back-end application response to the WSIF Provider.
This XML record is translated to a Web service Response for consumption by the BPEL PM instance.
The whole end-to-end scenario is synchronous and any J2CA exception is forwarded as a Web service fault message.
BPEL Process Manager Integration with Inbound Interaction
BPEL Process Manager receives events from the J2CA 1.5 resource adapter through Adapter Framework, which is the psuedo 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:
The 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 Adapter Framework 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. Adapter Framework 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 messageEndPoint method consists of a messageListener component and the J2CA 1.5 resource adapter calls the onMessage method when it receives an back-end application event. A MessageEndpoint is a class that exposes the onMessage method, which creates MessageEndpoint through the MessageEndpointFactory provided to the resource adapter during endpointActivation.
Adapter Framework receives the event through the MessageListener class and forwards it to the Receive activity of the BPEL Process Manager instance.
All end points are deactivated and the EndPointDeactivation method is called.
BPEL WSIF JCA Connection Pool
In the case of J2CA adapters, particularly the JDBC based ones, such as DB adapters and AQ adapters there are two kinds of connection management at play: one for inbound (endpoint) activations (BPEL Receive) and one for outbound interactions (BPEL Invoke).In the case of inbound activations, the J2CA adapter is fully in-charge of connection creation and recovery. The Adapter Framework (AF) 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 re-establish a new connection.
In the case of outbound activations (WSIFor J2CA) each WSIF port caches tuples of the following:
ConnectionFactory
ConnectionSpec
Connection
Interaction
InteractionSpec
As the BPEL engine typically invokes the WSIF 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 auto-expire unused tuples after a configured idle period (interactions and connection handles are then closed). The main reason for this is that currently all outbound J2CA adapter interactions are scoped by LocalTransaction's only (we add XA support with 10.1.3), and hence two threads must each have their own exclusive Connection/LocalTransaction to work with. The cache also 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, 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 marked as Retryable, will make the engine retry the Invoke (DB update) which will then repopulate the WSIF port cache (if the DB 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 only contains 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 using the following bpel.xml partnerlink properties:
<property name="useJCAConnectionPool">true</property>
Normally 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:
<property name="maxSizeJCAConnectionPool">500</property>
If the property mentioned in the preceding example is not specified, then it is assumed to be unbounded. This applies on a each of the WSIFPort (partnerlink) as shown in the following example:
<property name="lruConnectionMaxIdleAge">50000</property>
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:
<property name="lruConnectionCheckInterval">10000</property>
Packaged-application adapters including OracleAS Adapter for PeopleSoft, OracleAS Adapter for SAP R/3, OracleAS Adapter for Siebel, and OracleAS Adapter for J.D. Edwards can be integrated with OracleAS Integration InterConnect. In addition to J2CA deployment, packaged-application adapters support web service servlet deployment, which is called Business Service Engine (BSE). This integration can be deployed within an enterprise or across enterprise boundaries through the Internet. OracleAS Integration InterConnect is designed as a hub and spoke system. In this system, spokes function as OracleAS Integration InterConnect adapters that access other applications and systems. The hub acts as a OracleAS Integration InterConnect repository server, which is a standalone Java application. The OracleAS Integration InterConnect repository is a database that stores the design-time metadata definition.
Deployment and Integration through BSE
BSE integrates with OracleAS Integration InterConnect products and enables access to packaged applications. It helps businesses to integrate heterogeneous information systems faster, more cost effectively, and more uniformly by implementing standards that provide simple and consistent connections between these systems over the Internet. Business functions and data can be exposed as a Web Service, and tools on other platforms can use these services with minimal effort. The OracleAS Adapter Business Services Engine supports the following standards:
A Simple Object Access Protocol (SOAP) request makes a Web Service perform a task.
Web Services Definition Language (WSDL) describes all of the SOAP calls that can be used for a set of services.
A Universal Description, Discovery, and Integration (UDDI) server acts as a directory of relevant Web Services and the WSDL that describes them.
No programming knowledge is necessary to generate these services, which reuse functionality from ERP or CRM systems, legacy applications, and diverse data sources.
BSE is deployed as a servlet within the OC4J container of the Oracle Application Server, and it depends on the OC4J container for scalability and high availability. The Swing-based design-time tool, Application Explorer, is used for browsing the EIS metadata that it passes to BSE. Adapter creates the WSDLs for the various adapter services and stores the WSDL schemas in an XML-based file repository or an Oracle Database repository. BSE must be running during both design time and at runtime.
Integration with OracleAS Integration InterConnect
The OracleAS Integration InterConnect EIS Adapter Plugin integrates the OracleAS Web Services adapter with OracleAS Integration InterConnect by translating XML payloads between XSD and DTD formats, respectively.
The OracleAS Integration InterConnect product supports four messaging paradigms: implemented procedures (request-response service), subscribe (one-way request service), publish (event service), and invoked procedure (OracleAS Integration InterConnect is the server in this case and EIS is the client making the request).
OracleAS Integration InterConnect EIS Adapter Plugin supports only the first three messaging paradigms. It uses SOAP for implemented procedure and subscription and RMI for the request-response and event notification services.
The following components are used in integrating with OracleAS Integration InterConnect:
BSE, which is the OracleAS Adapter deployed as a Web Services servlet within OC4J
OracleAS Integration InterConnect EIS Adapter Plugin to talk to the BSE
OracleAS Integration InterConnect deployment
Oracle iStudio
Application Explorer
OracleAS Integration InterConnect at Design Time
During design time, Application Explorer configures BSE. In addition to the standard WSDL schemas, BSE generates DTD schemas and stores them locally in a file system specified by the user. The OracleAS Integration InterConnect iStudio tool includes a DTD browser plugin, and can be used to convert DTD schemas to the native OracleAS Integration InterConnect schema and store these in the OracleAS Integration InterConnect repository. More specifically, the following steps complete configuration for Request-Response and Event Notification scenarios during the design time.
Request-Response; Implemented Procedures and Subscribe
Configure the BSE for request-response service using Application Explorer. The WSDL schemas are stored in the OracleAS Adapter repository and the DTD schemas are saved to a local file system.
Use OracleAS Integration InterConnect iStudio DTD browser to consume the DTD schemas generated in the previous step and store the configuration information in the OracleAS Integration InterConnect repository.
Event Notification; Publish
Configure the BSE for event services, including the RMI port definition, using Application Explorer. The WSDL schemas are stored in the Oracle Adapter repository and the DTD schemas are saved to a local file system.
Use OracleAS Integration InterConnect iStudio DTD browser to consume the DTD schemas generated in the previous step and store the configuration information in the OracleAS Integration InterConnect repository.
OracleAS Integration InterConnect During Runtime
The OracleAS Integration InterConnect EIS Adapter Plugin loads the metadata from the OracleAS Integration InterConnect repository using its own API. The OracleAS Integration InterConnect EIS Adapter Plugin interfaces with the EIS application and translates the data between EIS native format and the Application View, a format recognized by OracleAS Integration InterConnect. This interaction is illustrated in Figure 6. More specifically, the following steps describe run-time behavior for Request-Response and Event Notification scenarios.
Request-Response; Implemented Procedures and Subscribe
The OracleAS Integration InterConnect hub sends the request to OracleAS Integration InterConnect EIS Adapter Plugin, which creates a SOAP client request and makes a call to the BSE. The adapter invokes the EIS and forwards the EIS response as a SOAP response back to the OracleAS Integration InterConnect EIS Adapter Plugin, which in its turn translates the SOAP response to appropriate OracleAS Integration InterConnect format and forwards it on to the OracleAS Integration InterConnect hub.
Event Notification; Publish
BSE receives an EIS event notification through the Channel component. It then forwards this event as an RMI request to the OracleAS Integration InterConnect EIS Adapter Plugin, which acts as an RMI server and consumes this event, translates it to the appropriate OracleAS Integration InterConnect format and forwards it to the OracleAS Integration InterConnect hub.
Deployment and Integration through J2CA
The OracleAS Adapter J2CA supports only synchronous outbound interactions, such as the request-response service, not event notification. At runtime, an EJB, a servlet or a Java application client communicates with the OracleAS Adapter J2CA through the CCI API. The OracleAS Adapter J2CA is deployed within OC4J as a standard J2CA 1.0 Resource Adapter, and runs in managed mode within the OC4J container. Similar to the BSE, it is configured using Application Explorer. The OracleAS Adapter J2CA is in practice a J2CA wrapper around the adapter SDK.
An OracleAS Adapter J2CA is universal; its repository project can contain more than one EIS connection and it can talk to more than one EIS type. The repository project can be in a file or database repository; its ra.xml file contains the repository connection parameters and the repository project name. Multiple managed ConnectionFactory objects can be specified in the oc4j-ra.xml file generated by OC4J, each pointing to a different repository project and JNDI name. To connect to a particular EIS, the J2CA CCI ConnectionSpec class is used to specify the EIS type and the EIS connection name.
The basic outline for using CCI with the OracleAS Adapter J2CA consists of the following steps:
Find a ConnectionFactory object for the OracleAS Adapter J2CA.
Create a ConnectionSpec object that uses the EIS type and EIS connection name.
Create a Connection to the EIS using the ConnectionFactory and ConnectionSpec objects.
Create an Interaction object based on the request and response XSD schemas.
Call the execute() method on the Interaction.
After the required interactions have been processed, close the Interaction and Connection objects.
