JCA Transport User Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Using the JCA Transport

Oracle Service Bus provides a J2EE Connector Architecture (JCA) transport that interacts with Enterprise Information Systems (EIS), such as Enterprise Resource Planning (ERP) systems, letting EIS applications and services participate in the service bus environment. For a list of adapters the JCA transport works with, see Adapter Support.

This document, which describes the JCA transport, contains the following sections:

 


About the JCA Transport

The JCA transport provides native connectivity between Oracle Service Bus and EIS systems, letting those systems interact in the service bus layer and leverage the capabilities and features of Oracle Service Bus.

In JCA proxy or business services, the JCA transport works in conjunction with a built-in JCA adapter framework and JCA-compliant adapters to interact with EIS systems, as shown in Figure 1. Solid arrows signify request, dotted arrows signify response.

Figure 1 Oracle Service Bus services interacting with an EIS

Oracle Service Bus services interacting with an EIS

JCA proxy services listen for inbound requests from supported JCA adapters, and JCA business services invoke EIS endpoints through supported adapters.

This section describes features and characteristics of the JCA transport.

Messaging

The JCA transport supports request-only and synchronous request/response messaging patterns using SOAP 1.1.

Headers

The JCA transport models the JCA WSDL’s <jca:header> as SOAP headers.

Transactions

The JCA transport is transactional. If a JCA proxy service is invoked in an EIS transaction, or if a JCA business service is invoked in a transaction, the transport propagates the transaction.

Security

This section describes how the JCA transport and JCA adapter framework handle security for proxy and business services.

Security between a JCA service and an EIS adapter is handled differently depending on whether the service is configured to use managed mode or non-managed mode.

In managed mode, a service authenticates to an adapter with an Oracle Service Bus JNDI service account (static only for proxy services) when connecting to the adapter’s connection factory. If no JNDI service account is selected, the service connects to the adapter’s connection factory as anonymous. For the Oracle Database, Oracle AQ, and Oracle Applications adapters, the adapter connects to the EIS database using the JDBC datasource associated with the adapter-managed connection factory.

In non-managed mode, the JCA service connects to a JCA adapter directly through the JCA adapter framework. The JCA adapter framework manages the connection to adapters using the connection factory properties defined in the JCA WSDL or using any overrides you provide in the JCA transport connection authentication properties, as described in the Transport Configuration Reference.

Proxy Services

On inbound requests the JCA adapter framework, which invokes a JCA proxy service, always invokes the proxy service as anonymous.

Business Services

Depending on which type of JNDI service account is used in a JCA business service, the outbound service endpoint is invoked with a subject in the following ways:

Logging

The JCA transport logs messages using the WebLogic Server NonCatalog logger. JCA adapter framework logs are redirected to the WebLogic Server log.

Debug log records generated by the JCA transport, JCA adapter framework, and JCA adapters are redirected to the WebLogic Server log only if Oracle Service Bus transport debug logging is enabled. For more information, see Debugging Oracle Service Bus.

URI Rewriting

The JCA transport supports URI rewriting in a proxy service message flow.

Environment Variables

The JCA transport declares the following environment variable values, which can be maintained when moving an Oracle Service Bus configuration among different deployment environments.

For descriptions of these values, see JCA Transport Configuration for Proxy and Business Services.

Encoding

For inbound requests and outbound responses, the JCA adapter framework sends messages to JCA proxy services with UTF-8 encoding.

 


Adding the JCA Transport to Existing Domains

If you upgraded Oracle Service Bus 10g Release 3 to Maintenance Pack 1, you can add JCA transport functionality to existing domains using the Configuration Wizard. See the Oracle Service Bus Upgrade Guide for instructions.

New installations of Oracle Service Bus 10g Release 3 MP1 include the JCA transport and JCA adapter framework.

 


Working with Adapters

The JCA transport is compatible with a variety of EIS adapters. This section describes how to use the supported adapters with Oracle Service Bus and the JCA transport.

A WSDL is required to create a JCA proxy or business service in Oracle Service Bus. For proxy or business services that interact with supported adapters, you must generate the WSDLs in your EIS system environment. After you generate a WSDL, import it into your Oracle Service Bus configuration and use it to create a JCA service.

For example, for Oracle Applications, Oracle AQ, or Oracle Database adapters, generate a WSDL in Oracle JDeveloper, import the WSDL into Oracle Service Bus, and generate a configuration JAR for run-time deployment. Create and configure JCA services based on the WSDL, as described in Transport Configuration Reference.

Adapter Support

The Oracle Service Bus JCA transport lets you interact with the following JCA-compliant adapters:

See the following guides for more information on Oracle adapters:

JCA Adapter Framework

The JCA Transport uses the Oracle Service Bus JCA adapter framework to interact with JCA-compliant adapters that in turn provide connectivity to external EIS services. The JCA adapter framework abstracts the complexity of interacting with those adapters, letting you focus on proxy and business service development in Oracle Service Bus.

For inbound interactions, the JCA proxy service registers a listener with the associated JCA adapter endpoint. When an event occurs in the EIS system where a message is sent to the JCA proxy, and the JCA adapter framework invokes the proxy service with a request-only or request-response pattern.

On outbound interactions, when a client invokes an EIS service through Oracle Service Bus, the JCA business service invokes the JCA adapter endpoint through the JCA adapter framework.

No configuration of the JCA adapter framework is necessary. It is deployed and functions automatically as you create JCA proxy and business services in Oracle Service Bus and deploy your adapters as required.

Adapter Deployment and Configuration

The Oracle Applications, Oracle AQ, and Oracle Database adapters are deployed automatically in an Oracle Service Bus domain. You must manually install and deploy other supported resource adapters in the Oracle WebLogic Server Console, such as the Oracle Application Adapters.

You must create a data source for and configure each adapter in WebLogic Server, as described in the following section, Configuring Oracle Adapters.

Configuring Oracle Adapters

Perform the following general steps to configure an already-deployed Oracle AppsAdapter, AqAdapter, or DbAdapter. The deployed adapter resource files (*.rar) are located in ALSB_HOME/lib/transports/jca/.

  1. Create a data source – In the WebLogic Server Console, create and configure a data source to connect to the EIS database.
  2. Note: For Oracle databases, use the Oracle Driver (Thin XA) driver.
  3. Configure the deployed resource adapter – In the WebLogic Server Console, modify the adapter configuration to use the data source you created.
    1. Go to Deployments > [adapter] > Configuration > Outbound Connection Pools.
    2. Create a new connection pool factory based on the new data source. During the process, designate a location for the connection pool factory Plan.xml file. This file persists the connection factory configuration settings.
    3. After you create the connection pool factory, click its name and modify its properties. To do this, click in the Properties field for XADataSourceName, enter the name of the data source you created, and press Enter.
    4. Note: You must press Enter after you enter the name of the data source, while the cursor is in the input field. If you do not do this, the connection pool factory properties are not saved.
    5. Activate your changes in the Change Center.
  4. Add the most recent adapters to the Oracle JDeveloper environment.
  5. Using Oracle JCA adapters with Oracle Service Bus requires that you create service WSDLs in Oracle JDeveloper. To ensure that you are using the most recent version of an adapter in Oracle JDeveloper, back up the existing adapter JAR file in the Oracle JDeveloper environment and replace it with the Oracle Service Bus JAR.

    For example, if you are using the Oracle Database Adapter with Oracle Service Bus, copy ALSB_HOME/eclipse/plugins/com.bea.alsb.transports.jca.version/DBAdapter.jar to jdev/integration/lib/. The adapter JARs are also available inside the adapter RAR files in ALSB_HOME/lib/transports/jca/.

See the following sections for adapter-specific configuration information.

Configuring the Oracle AQ Adapter

For the Oracle AQ Adapter’s data source, select the Test Connections on Reserve option.

Configuring the Oracle Database Adapter

Following are key configuration points between Oracle Service Bus and the Oracle Database Adapter. For more detailed configuration instructions, see the JCA DB Adapter with OSB tutorial at http://www.oracle.com/technology/sample_code/products/osb/index.html.

Rejected Messages

The JCA adapter framework automatically logs rejected messages—messages with data errors—to a /domain/jca/.../rejectedMessages directory for each adapter.

 


Invoking an EIS Service Through Oracle Service Bus

This section describes the process of invoking an EIS service from a client through Oracle Service Bus.

The JCA transport supports request and synchronous request/response message patterns. This section illustrates a synchronous request/response pattern, as shown in Figure 2.

Figure 2 A client invoking an EIS service through Oracle Service Bus

A client invoking an EIS service through Oracle Service Bus

Creating, Configuring, and Invoking the Services

Use the following guidelines to invoke an EIS service from a client.

For configuration issues that apply to specific adapters, see Working with Adapters.

 


Invoking an External Service from an EIS

This section describes the process of invoking an external service from an EIS through Oracle Service Bus.

The JCA transport supports request and synchronous request/response message patterns. This section illustrates a synchronous request/response pattern, as shown in Figure 3.

Figure 3 An EIS invoking an external service through Oracle Service Bus

An EIS invoking an external service through Oracle Service Bus

Creating, Configuring, and Invoking the Services

Use the following guidelines to invoke an external service from an EIS.

For configuration issues that apply to specific adapters, see Working with Adapters.

 


Transport Configuration Reference

This section provides descriptions for JCA transport-specific configuration options. For descriptions of general business and proxy service configuration options, see the following topics:

Endpoint URI

Use the following endpoint URI format for JCA services:

jca://<resource_adapter_jndi>

where resource_adapter_jndi is the value of location attribute in the JCA WSDL <jca:address> element, which is also the JNDI name for the adapter deployed on WebLogic Server.

Endpoint Redeployment

JCA service endpoints are dependent on WSDLs, XML schemas, and service accounts. When any of those resource types is updated and saved for a service, the JCA service endpoint is automatically deleted, recreated, and redeployed. For a JCA proxy service, a new adapter listener is also initialized to listen for inbound requests.

JCA endpoint redeployment has a potential impact on services at run time, depending on whether or not you select the “Always use configuration from JCA WSDL” option for a service as described in Table 1. For example:

JCA Transport Configuration for Proxy and Business Services

Table 1 describes the options available on the JCA transport configuration page in either Workshop for WebLogic or in the Oracle Service Bus console.

Table 1 JCA transport configuration 
Option
Description
Adapter Name
A read-only value showing the name of the adapter that the JCA service will use.
Adapter Type
A read-only value showing the adapter type.
Dispatch Policy
Select the instance of the WebLogic Server Work Manager that you want to use for the dispatch policy for this endpoint. The default Work Manager is used if no other Work Manager exists.
For information about Work Managers, see the following WebLogic Server Administration Console Online Help topics:
JNDI Service Account
JNDI Service Account is for JNDI context security, used to access the EIS adapter managed connection factory. Click Browse and select a service account. If no service account is specified, an anonymous subject is used.
For JCA business services, there is no restriction on the type of JNDI service account that can be configured, such as static or pass-through, but the run time must be able to access a user name and password. JCA proxy services can use only static JNDI service accounts.
For more information on JNDI service accounts, see the Security section.
Always use configuration from JCA WSDL
This option determines whether or not connection factory properties, activation spec properties (proxy services), and interaction spec properties (business services) are always used from the WSDL.
If this option is selected (default), the JCA transport interacts with the JCA framework in the following ways, depending on whether you are using managed or non-managed mode:
  • Managed mode – The activation/interaction spec defined in the JCA WSDL. The Activation/Interaction Spec Properties field is read-only; and if Connection Mode is set to Managed, the Connection Factory Properties field is read-only.
  • Non-managed mode – Connection factory properties defined in the JCA WSDL. The Activation/Interaction Spec Properties field is read-only.
If this option is deselected, you can override the Activation/Interaction Spec Properties of the WSDL; and in non-managed mode you can override the Connection Factory Properties of the WSDL. At run time the JCA transport interacts with the JCA framework using the JCA WSDL and any activation/interaction spec or connection factory overrides you have provided.
For more information on using this option, see Endpoint Redeployment.
Connection Mode
This option determines how the service connects to the associated JCA adapter for the EIS system.
Managed – Recommended for production. The JCA transport connects to the JCA adapter through the JCA adapter-managed connection factory configured in WebLogic Server. For authentication, specify a JNDI service account. If no JNDI service account is specified, an anonymous subject is used. In managed mode, Connection Factory Authentication Properties are read-only.
Non-Managed – The JCA transport connects to the JCA adapter through the JCA adapter framework, which acts as a container for the JCA adapter. For authentication, specify a JNDI service account. If no JNDI service account is specified, an anonymous subject is used. In non- managed mode, Connection Factory Authentication Properties are editable for overrides.

Note: If you want to change from Non-Managed mode to Managed mode, be sure to deselect the Overwrite Connection Authentication Properties option before changing modes.

Overwrite Connection Authentication Properties
This option indicates whether or not the user name/password in the adapter connection factory is overwritten by the Connection Authentication Service Account credentials. If no JNDI Service Account is specified, an anonymous subject is used.
This option, which is displayed only if the connection factory properties contain user name/password properties, is available in non-managed mode with “Always use configuration from JCA WSDL” deselected.
Connection Authentication Service Account
This field is enabled if “Overwrite Connection Authentication Properties” is enabled and selected. This service account browser displays available service accounts. If the “Overwrite Connection Authentication Properties” option is selected, you must select a service account. For proxy services, only static service accounts are available.
This field if displayed only if the connection factory properties contain user name password properties.
Connection Factory Authentication Properties
This field is displayed only if the Connection Factory Properties contain a user name and password. This field is always read-only.
Connection Factory Properties
This field shows the connection factory properties from the WSDL’s <jca:address> element.
Development and Testing: You can override this value if you deselect “Always use configuration from JCA WSDL” and make the Connection Mode Non-Managed. In production environments, use managed mode, which makes the JCA transport connect to the adapter connection factory configured in WebLogic Server.
Operation Name
Displays a read-only name of the selected WSDL operation. An operation can have its own activation/interaction spec properties, shown in the Activation/Interaction Spec Properties field.
Activation/Interaction Spec Properties
“Activation Spec Properties” is the field name for proxy services; “Interaction Spec Properties” is the field name for business services.
If this service is an inbound service invoked by an EIS application, this field displays the activation spec properties for the JCA inbound operation shown in Operation Name field.
You can override the activation/interaction spec properties if you deselect “Always use configuration from JCA WSDL.”

Note: For Oracle Application Adapters, activation/interaction spec properties are displayed as read-only. The Oracle Application Adapters store their own configurations, which you must change in the Oracle Application Adapters management tools.

TopLink File Browser
For Oracle Database or Oracle Applications adapters that depend on a database, use this field to select a TopLink mapping file from the file system. The content of the TopLink mapping file is displayed in an editable text box.
Generate a TopLink mapping file in Oracle JDeveloper and import it into Oracle Service Bus.

Proxy Service Operation Configuration

JCA WSDLs support document literal binding only. The only algorithm for Operation configuration in JCA proxy services is SOAPAction Header. Oracle Service Bus effective WSDLs always contain SOAPAction. The value of the SOAPAction field is the operation name.

Proxy Service Message Content Handling

The JCA transport does not support message content streaming or attachments. Enabling content streaming has no effect on the JCA transport at run time. Since content streaming is a service configuration option over which the transport has no control, the transport does not raise validation errors if you enable content streaming.

Policies

Setting policies on JCA services has no effect on the services. Policies are used in SOAP WSDL services.

Business Service Retry Application Errors

Application errors cannot be retried with the JCA transport, and the transport has no control of this option. Set this option to “No.”


  Back to Top       Previous  Next