25 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 Section 25.2.1, "Adapter Support."

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

25.1 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 25-1. Solid arrows signify request, dotted arrows signify response.

Figure 25-1 Oracle Service Bus Services Interacting With an EIS

Description of Figure 25-1 follows
Description of "Figure 25-1 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.

25.1.1 Messaging

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

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

25.1.2 Transport Headers

Oracle JCA adapters transmit header information through Normalized Message properties (with the exception of the Oracle JCA Adapter for AQ's payload header). You cannot map these Normalized Message properties to SOAP message headers in Oracle Service Bus, but the Oracle Service Bus transport maps the properties to transport headers. The following subsections list the predefined transport headers in Oracle Service Bus that support the Normalized Message properties in the Oracle Database, AQ, and Applications JCA adapters. Oracle Service Bus 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.2.1 $inbound and $outbound Request Headers

Following are predefined Oracle Service Bus transport headers in the $inbound and $outbound request variables:

  • jca.aq.Priority (int)

  • jca.aq.Correlation (string)

  • jca.aq.HeaderDocument (string)

  • jca.apps.HeaderDocument (string)

  • jca.file.FileName

  • jca.file.Directory

  • jca.file.Size

  • jca.file.Batch

  • jca.file.BatchIndex

  • jca.file.LastModifiedTime

25.1.2.2 $inbound-Only Request Headers

Following are predefined Oracle Service Bus transport headers in the $inbound request variable:

  • jca.aq.MessageId (string)

  • jca.aq.Attempts (int)

  • jca.aq.EnqueueTime (string)

  • jca.aq.OrigMessageId (string)

25.1.2.3 $outbound-Only Request Headers

Following are predefined Oracle Service Bus transport headers in the $outbound request variable:

  • jca.aq.Delay (int)

  • jca.aq.Expiration (int)

  • jca.aq.RecipientList (string)

  • jca.aq.ExceptionQueue (string)

  • jca.db.ProxyUserName (string)

  • jca.db.ProxyPassword (string)

  • jca.db.ProxyRoles (string)

  • jca.db.ProxyCertificate (string)

  • jca.db.ProxyDistinguishedName (string)

  • jca.db.ProxyIsThickDriver (boolean)

  • jca.apps.Username(string)

  • jca.apps.Responsibility(string)

  • jca.apps.RespApplication(string)

  • jca.apps.SecurityGroup(string)

  • jca.apps.NLSLanguage(string)

  • jca.apps.ORG_ID(integer)

  • jca.apps.ecx.TransactionType(string)

  • jca.apps.ecx.TransactionSubtype(string)

  • jca.apps.ecx.PartySiteId(string)

  • jca.apps.ecx.MessageType(string)

  • jca.apps.ecx.MessageStandard(string)

  • jca.apps.ecx.DocumentNumber(integer)

  • jca.apps.ecx.ProtocolType(string)

  • jca.apps.ecx.ProtocolAddress(string)

  • jca.apps.ecx.Username(string)

  • jca.apps.ecx.Password(string)

  • jca.apps.ecx.Attribute1(string)

  • jca.apps.ecx.Attribute2(string)

  • jca.apps.ecx.Attribute3(string)

  • jca.apps.ecx.Attribute4(string)

  • jca.apps.ecx.Attribute5(string)

  • jca.apps.ecx.Payload(string)

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.3.1 Proxy Service Endpoint Properties

Following are the supported endpoint properties in JCA proxy services:

  • jca.retry.count

  • jca.retry.interval

  • jca.retry.backoff

  • jca.retry.maxInterval

Oracle JCA Adapter for AQ

  • DequeueTimeOut

  • ConnectionRetryDelay

  • adapter.aq.dequeue.threads

Oracle JCA Adapter for Database and Oracle Applications

  • activationInstances

Oracle JCA Adapter for Files

  • ignoreListingErrors

  • IgnoreZeroByteFile

  • jca.message.encoding

  • notifyEachBatchFailure

  • oracle.tip.adapter.file.debatching.rejection.quantum

  • oracle.tip.adapter.file.highavailability.maxRetry

  • oracle.tip.adapter.file.highavailability.maxRetryInterval

  • oracle.tip.adapter.file.rejectOriginalContent

  • oracle.tip.adapter.file.timeout.recoverpicked.minutes

  • oracle.tip.adapter.file.timeout.recoverunpicked.minutes

  • recoveryInterval

  • serializeTranslation

  • useFileSystem

25.1.3.2 Business Service Endpoint Properties

Following are the supported endpoint properties in JCA business services:

  • jca.retry.count

  • jca.retry.interval

  • jca.retry.backoff

  • jca.retry.maxInterval

  • jca.retry.maxPeriod

Oracle Adapter for Oracle Applications

  • Username

  • Responsibility

Oracle JCA Adapter for Files

  • inMemoryTranslation

  • IgnoreZeroByteFile

  • oracle.tip.adapter.file.mutex

  • oracle.tip.adapter.file.rejectOriginalContent

  • serializeTranslation

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.4.1 Proxy Services

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

25.1.4.2 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:

  • No service account is used – An anonymous subject is used to invoke outbound JCA endpoint.

  • A pass-through service account is used – The subject associated with the inbound request is used to invoke the outbound JCA endpoint.

  • A static service account is used – The subject associated with the static user name/password in the service account is used to invoke the outbound JCA endpoint.

  • A mapping service account is used – The subject associated with the mapped user name/password in the service account is used to invoke the outbound JCA endpoint.

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

Note:

The alsb-transports-debug flag, which is used for all other transports, has no effect on the JCA transport, framework, and adapters.

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

25.1.6 URI Rewriting

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

25.1.7 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.8 Encoding

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

25.2 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 JCA file and WSDL are 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 JCA files and WSDLs in your EIS system environment. After you generate JCA files and WSDLs, import them into your Oracle Service Bus configuration and use the JCA file to create a JCA service.

For example, when creating services that interact with Oracle JCA adapters, generate a JCA file and WSDL in Oracle JDeveloper, import the files into the Oracle Service Bus IDE, and create and configure JCA services based on the JCA file. For more information, see Section 2.2.2, "Generating a JCA Business Service from an Outbound JCA File" and Section 2.3.2, "Generating a JCA Proxy Service from an Inbound JCA File."

You can also import the JCA and WSDL files into the Oracle Service Bus Console for JCA service generation, as described in the console online help.

This section contains the following topics:

25.2.1 Adapter Support

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

  • Oracle Adapter for Oracle Applications

  • Oracle JCA Adapter for AQ

  • Oracle JCA Adapter for Database

  • Oracle JCA Adapter for Files

  • 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:

25.2.1.1 Oracle JCA Adapter Limitations

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

  • Oracle JCA Adapter for Files – Attachments (large payload support), pre- and post-processing of files, using a re-entrant valve for processing ZIP files, content streaming, and file chunked read are not supported with Oracle Service Bus.

  • Oracle JCA Adapter for AQ – Streamed payload is not supported with Oracle Service Bus.

25.2.2 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.3 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.4 Configuring Adapters that Poll a Database

By default, as a performance best practice, 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.

25.2.5 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/technology/sample_code/products/osb/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.6 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.7 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 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 25-2.

Figure 25-2 A Client Invoking an EIS Service Through Oracle Service Bus

Description of Figure 25-2 follows
Description of "Figure 25-2 A Client Invoking an EIS Service Through Oracle Service Bus"

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

25.4 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 25-3.

Figure 25-3 An EIS Invoking an External Service Through Oracle Service Bus

Description of Figure 25-3 follows
Description of "Figure 25-3 An EIS Invoking an External Service Through Oracle Service Bus"

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

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.1.1 Endpoint Redeployment

JCA service endpoints are dependent on WSDLs, service accounts, JCA resources, XML schemas, and XML resources (TopLink or EclipseLink mapping files). 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 file" option for a service as described in Table 25-1. For example:

  • If "Always use configuration from JCA file" is selected, after a JCA endpoint is redeployed, the updated JCA file is used to connect and interact with the resource adapter at run time.

  • If "Always use configuration from JCA file" is not selected, existing service configuration overrides are used to interact with the resource adapter at run time instead of corresponding JCA file properties that may have been updated.

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

Table 25-1 JCA Transport Configuration Options

Option Description

JCA File

Click Browse to select a JCA resource. The JCA resource defines different aspects of the service, such as details about the adapter used, a binding to the WSDL and TopLink or EclipseLink mapping file, and the activation/interaction spec properties required by the service.

Once you select a valid JCA resource, the remaining transport configuration fields become available.

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 Oracle 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 "Using Work Managers to Optimize Scheduled Work" in Oracle Fusion Middleware Configuring Server Environments for Oracle WebLogic Server.

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 Section 25.1.4, "Security."

EndPoint Properties

This field lets you assign values to endpoint properties such as retries for the type of adapter the service uses.

For a list of supported endpoint properties, see Section 25.1.3, "Endpoint Properties."

Dynamic EndPoint Properties

This option lets you pass request parameters to JCA-compliant services. For example, you can use a dynamic endpoint property to pass database query parameters to the Oracle JCA Adapter for Database.

For more information on querying with parameters, see “Oracle JCA Adapter for Database” in the Oracle Fusion Middleware User's Guide for Technology Adapters.

Enter a name/value pair for each dynamic endpoint property you want to provide. The endpoint property key matches the query parameter name.

Always use configuration from JCA file

This option determines whether or not Activation Spec Properties (proxy services) and Interaction Spec Properties (business services) are always used from the JCA file.

If this option is selected (default), the JCA transport interacts with the JCA framework using the activation/interaction spec properties in the JCA file.

If this option is deselected, you can override the Activation/Interaction Spec Properties.

For the redeployment impact of using this option, see Section 25.5.1.1, "Endpoint Redeployment."

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

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

Connection properties (legacy)

For legacy JCA services that use non-managed mode connection properties (deprecated in this release), see the connection configuration options at http://download.oracle.com/docs/cd/E13159_01/osb/docs10gr3/jcatransport/transport.html#wp1105451.

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.

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