Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Service Bus
11g Release 1 (11.1.1.7)

Part Number E15866-09
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

25 JCA Transport

This chapter provides an overview of the JCA transport and describes how to use and configure it in your services. The chapter also describes the Oracle JCA adapter framework and provides guidance on using specific adapters with Oracle Service Bus.

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

Service Bus 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. Service Bus maps all other normalized message properties to user-defined transport headers.

Note:

You cannot map normalized message properties to SOAP message headers in Oracle Service Bus.

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

  • jca.ftp.FileName

  • jca.ftp.Directory

  • jca.ftp.Size

  • jca.ftp.Batch

  • jca.ftp.BatchIndex

  • jca.ftp.CreationTime (supported only by SFTP)

  • jca.ftp.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.db.XADataSourceName (string)

  • jca.db.DataSourceName (string)

  • 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 (Inbound)

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

  • payloadSizeThreshold

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

  • payloadThreshold

  • recoveryInterval

  • serializeTranslation

  • useFileSystem

Oracle JCA Adapter for FTP

  • IgnoreZeroByteFile

  • oracle.tip.adapter.file.rejectOriginalContent

  • serializeTranslation

  • timestampOffset

  • ignoreListingErrors

  • 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.timeout.recoverpicked.minutes

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

  • payloadSizeThreshold

  • recoveryInterval

  • useFileSystem

25.1.3.2 Business Service Endpoint Properties (Outbound)

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

Oracle JCA Adapter for FTP

  • IgnoreZeroByteFile

  • oracle.tip.adapter.file.rejectOriginalContent

  • serializeTranslation

  • timestampOffset

  • inMemoryTranslation

  • oracle.tip.adapter.file.mutex

Oracle JCA Adapter for Database

  • cacheConnections – Oracle Service Bus implicitly sets the value of this property to true. With this property value set to true, outbound connections to the database adapter are cached. If you change the default and set this property to false, a connection open and close occurs for every outbound invocation.

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

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 runtime, 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 runtime 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 (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.

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.5.1 Oracle BAM Adapter Logging

To enable debug-level logging for Oracle BAM Adapter batch processing using RMI- and SOAP-based connection pools, add the following logger entries to domain_home/config/fmwconfig/servers/server_name/logging.xml:

  • For RMI/EJB – <logger name="oracle.bam.adc.api.batching.BatchProcessor" level="FINER"/>

  • For SOAP – <logger name="oracle.bam.adapter.adc.soap.SOAPBatchProcessor" level="FINER"/>

25.1.6 Error Handling

This section describes error handling information for the JCA transport.

25.1.6.1 EIS Fault Details in JCA Business Services

When the JCA framework and adapters throw an exception from an EIS, a JCA business service propagates that exception to the SOAP fault inside a jca-runtime-fault-detail element.

You can access the EIS fault details in one or more of the following sub-elements:

  • eis-error-code (string) – Captures the EIS error code propagated by the JCA framework and adapter, if available.

  • eis-error-message (string) – Captures the EIS error message propagated by the JCA framework and adapter, if available.

  • exception (string) – Captures the JCA framework and adapter stack trace.

This fault structure is defined in the JCA transport schema.

Note:

The JCA transport may handle EIS faults differently in future releases.

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

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 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, following the "Resource Naming Restrictions" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus. 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 Administration Console for JCA service generation, as described in the Oracle Service Bus Administration 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:

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

  • SAP R/3 (Oracle Application Adapters)

  • Siebel (Oracle Application Adapters)

  • J.D. Edwards (Oracle Application Adapters)

See the following guides for more information on Oracle adapters:

25.2.2 Oracle JCA Adapter Limitations

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

25.2.2.1 Limitations that Apply to All JCA Adapters

The JCA transport does not support the "singleton" endpoint property for an active/passive topology.

25.2.2.2 Oracle JCA Adapter for AQ Limitations

For Oracle JCA Adapter for AQ, the JCA transport does not support streamed payload.

25.2.2.3 Oracle JCA Adapters for Files/FTP Limitations

For Oracle JCA Adapter for Files/FTP, the JCA transport does not support the following: 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.

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:

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 Service Bus" 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

You can create and use custom JCA adapters with Oracle Service Bus. You create the custom adapter in Oracle JDeveloper, and then import the file into Oracle Service Bus and register it in an XML file. Once you register a custom adapter with Service Bus in the registration file, you can use it in conjunction with the JCA transport like you would any other JCA adapter.

Note:

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

About the custom adapter registration file

All custom adapters need to be registered in the OSBSupportedAdapters.xml file, located in the Service Bus home directory in OSB_HOME/config/adapter. This file simply lists the names of all the custom JCA adapters for Service Bus. If you have not previously registered a custom JCA adapter, you may need to create the registration file. Below is a sample file you can use to create your own registration file.

<jca:osb-supported-adapters 
   xmlns:jca="http://www.bea.com/wli/sb/transports/jca">
     <jca:adapter-type>CUSTOM_ADAPTER</jca:adapter-type>
     <jca:adapter-type>SAMPLE_ADAPTER</jca:adapter-type>
     <jca:adapter-type>MY_ADAPTER</jca:adapter-type>
</jca:osb-supported-adapters>

The value for the adapter-type element comes from the adapter JCA file. It is the same as the value of the adapter attribute in the adapter-config element with the following changes:

  • Convert all letters to capital letters.

  • Convert all single spaces to an underscore; for example, My Adapter would be MY_ADAPTER.

  • Convert consecutive spaces to a single underscore; for example, My Adapter would also be MY_ADAPTER.

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>

To register and use a custom JCA adapter with Oracle Service Bus:

  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. Do one of the following:

    • If the custom adapter registration file, OSB_HOME/config/adapter/OSBSupportedAdapters.xml, already exists, add your custom adapter to the list of supported adapter types as illustrated in "About the custom adapter registration file".

    • If the custom adapter registration file does not exist, create the file using the sample file in "About the custom adapter registration file" as a basis. Replace the sample adapter type names with the actual names from your adapter JCA file.

  3. Import your custom adapter JCA resources into Oracle Service Bus.

    Notes:

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

  • If "Always use configuration from JCA file" is not selected, existing service configuration overrides are used to interact with the resource adapter at runtime 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 Administration 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:

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

Use this section to add and configure endpoint properties for custom adapters.

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 not selected, 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 runtime. 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.