Oracle® Fusion Middleware Developer's Guide for Oracle Service Bus 11g Release 1 (11.1.1.5.0) E15866-03 |
|
![]() Previous |
![]() Next |
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 26.2.1, "Adapter Support."
This document, which describes the JCA transport, contains the following sections:
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 26-1. Solid arrows signify request, dotted arrows signify response.
Figure 26-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.
The JCA transport supports request-only and synchronous request/response messaging patterns using SOAP 1.1.
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. 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.
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
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)
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)
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 26.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.
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
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
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.
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.
On inbound requests the JCA adapter framework, which invokes a JCA proxy service, always invokes the proxy service as anonymous.
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.
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.
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"/>
This section describes error handling information for the JCA transport.
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. |
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 26.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)
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:
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/FTP
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/
Following are limitations when using some JCA adapters with Oracle Service Bus:
Oracle JCA Adapter for AQ – Streamed payload is not supported with Oracle Service Bus.
Oracle JCA Adapter for FTP and 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.
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.
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).
Create a data source – In the Oracle WebLogic Server Console, create and configure a data source to connect to the EIS database.
Configure the deployed resource adapter – In the Oracle WebLogic Server Console, modify the adapter configuration to use the data source you created.
Go to Deployments > [adapter] > Configuration > Outbound Connection Pools.
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.
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. |
Activate your changes in the Change Center.
See the following sections for adapter-specific configuration information.
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
"Using Work Managers with Oracle Service Bus" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus
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. |
For the Oracle JCA Adapter for AQ data source, select the Test Connections on Reserve option.
The JCA adapter framework automatically logs rejected messages—messages with data errors—to a /domain/jca/.../rejectedMessages directory for each adapter.
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 26-2.
Figure 26-2 A Client Invoking an EIS Service Through Oracle Service Bus
Use the following guidelines to invoke an EIS service from a client.
For configuration issues that apply to specific adapters, see Section 26.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 26.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".
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 26-3.
Figure 26-3 An EIS Invoking an External Service Through Oracle Service Bus
Use the following guidelines to invoke an external service from an EIS.
For configuration issues that apply to specific adapters, see Section 26.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".
This section provides descriptions for JCA transport-specific configuration options. For descriptions of general business and proxy service configuration options, see the following topics:
Oracle Fusion Middleware Developer's Guide for Oracle Service Bus
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.
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 26-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.
Table 26-1 describes the options available on the JCA transport configuration page in either Eclipse or in the Oracle Service Bus Administration Console.
Table 26-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 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 26.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 26.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 26.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 |
For more information on endpoint and activation/interaction spec properties, see the Oracle Fusion Middleware User's Guide for Technology Adapters.
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.
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.