25 JCA Transport

25.1.1 Messaging

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

25.1.2 Transport Headers and Normalized Message Properties

Oracle JCA adapters transmit header information through normalized message properties (with the exception of the Oracle JCA Adapter for AQ's payload header).

OSB supports JCA adapter normalized message properties. On inbound messages from Oracle JCA adapters, the Oracle Service Bus JCA transport automatically maps normalized message properties to transport headers as key value pairs. On outbound messages to JCA adapters, the JCA transport automatically converts transport headers to normalized message properties.

The following subsections list the predefined transport headers in Oracle Service Bus that support normalized message properties. OSB maps all other normalized message properties to user-defined transport headers.

For more information on Normalized Message properties in JCA adapters, see the Oracle Fusion Middleware User's Guide for Technology Adapters.

25.1.3 Endpoint Properties

The JCA transport supports a number of service endpoint properties you can set in the JCA proxy or business service configuration, as described in Section 25.5.2, "JCA Transport Configuration for Proxy and Business Services.". Following are the supported endpoint properties.

For more information, see "Oracle JCA Adapters Endpoint Properties" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite and "Oracle JCA Adapter Properties" in the Oracle Fusion Middleware User's Guide for Technology Adapters.

25.1.4 Security

This section describes how the JCA transport and JCA adapter framework handle security.

A JNDI service account is used during both endpoint validation and run time.

During endpoint validation, if a static service account is associated with the endpoint, JNDI lookup against the adapter connection factory is performed using the subject in the static service account. If the service does not use a service account, an anonymous subject is used.

At run time, a JCA proxy service supports only static service accounts. If a static service account is configured on the service, the subject in the service account is used to perform the JNDI lookup against the adapter connection factory. Otherwise, an anonymous subject is used.

JCA business services at run time support static, pass through, and mapping service accounts. If a service account is configured on a JCA business service, JNDI lookup against the adapter connection factory and the subsequent outbound invocation is performed using the subject in the service account. If the service does not use a service account, an anonymous subject is used.

Oracle adapters that connect to an EIS database (Oracle Adapters for Database, AQ, and Oracle Applications) connect using the JDBC datasource associated with the adapter-managed connection factory. Other Oracle adapters, such as the Oracle JCA Adapter for Files, support Oracle WebLogic Server container-managed and application-managed sign-on for outbound connections. For more information, see "Securing Enterprise Information System Credentials" in the Oracle Fusion Middleware User's Guide for Technology Adapters.

25.1.5 Logging

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

Debug log records generated by the JCA transport, JCA adapter framework, and JCA adapters (except the Oracle BAM Adapter) are redirected to the Oracle WebLogic Server log only if Oracle Service Bus transport debug logging is enabled. To enable the debug mode, before starting the server, edit the alsbdebug.xml file in the domain directory and set the category alsb-jca-framework-adapter-debug flag to true. JCA framework and adapter messages are logged with the tag JCA_FRAMEWORK_AND_ADAPTER.

For more information, see "Debugging Oracle Service Bus" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

25.1.6 Error Handling

This section describes error handling information for the JCA transport.

25.1.7 URI Rewriting

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

25.1.8 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 Section 25.5.2, "JCA Transport Configuration for Proxy and Business Services."

• JCA JNDI Service Account (JCA_ENV_JNDI_SERVICE_ACCOUNT)

• Work Manager

• JCA Always Use WSDL Flag (JCA_ENV_ALWAYS_USE_WSDL)

• JCA Connection Mode (JCA_ENV_CONNECTION_MODE)

• JCA Overwrite Connection Authentication Flag (JCA_ENV_OVERWRITE_CONNECTION_FACTORY_AUTHENTICATION_PROPERTIES)

• JCA Authentication Overwrite Service Account (JCA_ENV_CONNECTION_AUTHENTICATION_OVERWRITE_SERVICE_ACCOUNT)

25.1.9 Encoding

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

25.2.1 Adapter Support

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

• Custom JCA adapters – See Section 25.2.8, "Using Custom JCA Adapters."

• Oracle Adapter for Oracle Applications

• Oracle JCA Adapter for AQ

• Oracle JCA Adapter for Database

• Oracle JCA Adapter for Files/FTP

• Oracle JCA Adapter for Sockets

• Oracle BAM Adapter (Business Activity Monitoring)

• PeopleSoft (Oracle Application Adapters 10g)

• SAP R/3 (Oracle Application Adapters 10g)

• Siebel (Oracle Application Adapters 10g)

• J.D. Edwards (Oracle Application Adapters 10g)

See the following guides for more information on Oracle adapters:

• Oracle Fusion Middleware User's Guide for Technology Adapters

• Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring

• Oracle Application Adapters 10g documentation at http://download.oracle.com/docs/cd/E13199_01/oracleappsadapter/docs1031/

25.2.2 Oracle JCA Adapter Limitations

Following are limitations when using some JCA adapters with Oracle Service Bus.

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

25.2.4 Configuring Adapters – General

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

Create a data source for and configure each adapter in Oracle WebLogic Server. Perform the following general steps to configure an already-deployed Oracle adapter (such as AppsAdapter, AqAdapter, or DbAdapter).

1. Create a data source – In the Oracle WebLogic Server Console, create and configure a data source to connect to the EIS database.

2. Configure the deployed resource adapter – In the Oracle 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 (for XA data sources) or datasourceName (for non-XA data sources), enter the name of the data source you created, and press Enter.

      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.

   4. Activate your changes in the Change Center.

See the following sections for adapter-specific configuration information.

25.2.5 Configuring Adapters that Poll a Database

By default, the Oracle adapters that poll a database use one thread to poll the database (NumberOfThreads=1 property in the activation spec). Because the adapter never releases that thread, which is by design, you may see a stuck thread stack trace in the server log. If you set the NumberOfThreads to more than one, you may see stack traces for all of those threads. You can ignore stuck thread stack traces.

To prevent stuck thread stack traces from appearing for the adapter, configure a Work Manager that includes the following setting:

<ignore-stuck-threads>true</ignore-stuck-threads>

In the JCA proxy service, configure the transport's Dispatch Policy to use the Work Manager you created.

For information about Work Managers, see:

• "Using Work Managers to Optimize Scheduled Work" in Oracle Fusion Middleware Configuring Server Environments for Oracle WebLogic Server

• "Using Work Managers with Oracle Service Bus" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus

25.2.6 Configuring the Oracle JCA Adapter for Database

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/technetwork/middleware/service-bus/learnmore/index.html.

• Data Source: For the Oracle JCA Adapter for Database data source, set the following options:

  Option	Setting
  Initial Capacity	0
  Test Connections on Reserve	selected
  Test Frequency	5
  Test Table Name	SQL SELECT 1 FROM DUAL
  Seconds to Trust an Idle Pool Connection	0
  Connection Creation Retry Frequency	10

  
  

  Note:

  Only one proxy service can poll a specific Oracle Database table.

25.2.7 Configuring the Oracle JCA Adapter for AQ

For the Oracle JCA Adapter for AQ data source, select the Test Connections on Reserve option.

25.2.8 Using Custom JCA Adapters

This section describes how to register and use custom JCA adapters with Oracle Service Bus. Once you register a custom adapter with OSB, you can use it in conjunction with the JCA transport like you would any other JCA adapter.

To register and use a custom JCA adapter with OSB:

1. Create a custom JCA adapter, as described in "Creating a Custom Adapter" in the Oracle Fusion Middleware User's Guide for Technology Adapters.

2. In OSB_ORACLE_HOME/config/adapter/OSBSupportedAdapters.xml, add your custom adapter to the list of supported adapter types. The name of the custom adapter type comes from the JCA file; the "adapter" attribute value in the <adapter-config> element.

   For example, given the following in the adapter JCA file:

   <adapter-config name="custom-adapter-endpoint" adapter="My Adapter" 
       wsdlLocation="custom-adapter-endpoint.wsdl" 
       xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata">
   . . .
   </adapter-config>
   

   the entry in OSBSupportedAdapters.xml would be:

   <jca:adapter-type>MY_ADAPTER</jca:adapter-type>
   

   Note the change to uppercase and the replacement of the space with an underscore character.

3. Import your custom adapter JCA resources into OSB and use OSB's JCA transport when configuring proxy or business services to use your custom adapter.

   On the JCA transport configuration page, optionally add and configure custom endpoint properties in the "Dynamic Endpoint Properties" section.

   The JCA transport also supports normalized message properties for custom adapters, as described in Section 25.1.2, "Transport Headers and Normalized Message Properties."

   Note:

   Unlike some supported Oracle SOA Suite adapters that include dependency resources such as TopLink XML mapping files or XSLT files, OSB does not support the use of dependency resources with custom adapters.

25.2.9 Rejected Messages

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

25.3.1 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 Section 25.2, "Working with Adapters."

• Create a Business Service in Oracle Service Bus that represents the EIS service you want to invoke.

  Create an outbound JCA business service in Oracle Service Bus. For more information, see Section 2.2.2, "Generating a JCA Business Service from an Outbound JCA File."

  For additional business service configuration details, see Section 2.2, "Working with Business Services.".

• Create a Proxy Service in Oracle Service Bus that invokes the business service.

  • In the proxy message flow, perform any transformation necessary to send messages in the JCA transport's supported message format, described in the Section 25.1.1, "Messaging" section.

  • Invoke the proxy service from the client with the desired payload.

  For additional proxy service configuration details, see Section 2.3, "Working with Proxy Services".

25.4.1 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 Section 25.2, "Working with Adapters."

• Create a Business Service in Oracle Service Bus that represents the external service you want to invoke.

  For business service configuration details, see Section 2.2, "Working with Business Services.".

• Create a Proxy Service in Oracle Service Bus that invokes the business service.

  • Create an inbound JCA proxy service in Oracle Service Bus. For more information, see Section 2.3.2, "Generating a JCA Proxy Service from an Inbound JCA File."

  • In the proxy message flow perform any transformation necessary to send messages in the supported message format of the external service you want to invoke.

  • Invoke the proxy service from the EIS as you normally would.

  When you create a JCA proxy service in Oracle Service Bus, the JCA transport registers a listener with the JCA adapter endpoint that listens for service invocations from the EIS. The JCA adapter framework passes service invocations to the proxy service.

  For additional proxy service configuration details, see Section 2.3, "Working with Proxy Services".

25.5.1 Endpoint URI

Use the following endpoint URI format for JCA services:

jca://<resource_adapter_jndi>

where resource_adapter_jndi is the value of the "location" attribute in the connection-factory element in the JCA file. This value matches the adapter connection factory JNDI.

25.5.2 JCA Transport Configuration for Proxy and Business Services

Table 25-1 describes the options available on the JCA transport configuration page in either Eclipse or in the Oracle Service Bus Administration Console.

For more information on endpoint and activation/interaction spec properties, see the Oracle Fusion Middleware User's Guide for Technology Adapters.

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

25.5.4 Proxy Service Message 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.

25.5.5 Policies

Setting policies on JCA services is not allowed. If you set a policy on a JCA service, Oracle Service Bus shows a conflict in the service configuration.