5 Adapter Integration with Oracle Application Server Components

OC4J Overview

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:

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).

OC4J Integration with Adapters

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.

BPEL Process Manager Overview

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.

BPEL Process Manager Integration with Adapters

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.

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-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.

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>