Oracle Service Bus provides a J2EE Connector Architecture (JCA) transport that interacts with Enterprise Information Systems (EIS), such as Enterprise Resource Planning (ERP) systems, letting EIS applications and services participate in the service bus environment. For a list of adapters the JCA transport works with, see Adapter Support.
This document, which describes the JCA transport, contains the following sections:
The JCA transport provides native connectivity between Oracle Service Bus and EIS systems, letting those systems interact in the service bus layer and leverage the capabilities and features of Oracle Service Bus.
In JCA proxy or business services, the JCA transport works in conjunction with a built-in JCA adapter framework and JCA-compliant adapters to interact with EIS systems, as shown in Figure 1. Solid arrows signify request, dotted arrows signify response.
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.
The JCA transport models the JCA WSDL’s <jca:header> as SOAP headers.
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.
This section describes how the JCA transport and JCA adapter framework handle security for proxy and business services.
Security between a JCA service and an EIS adapter is handled differently depending on whether the service is configured to use managed mode or non-managed mode.
In managed mode, a service authenticates to an adapter with an Oracle Service Bus JNDI service account (static only for proxy services) when connecting to the adapter’s connection factory. If no JNDI service account is selected, the service connects to the adapter’s connection factory as anonymous. For the Oracle Database, Oracle AQ, and Oracle Applications adapters, the adapter connects to the EIS database using the JDBC datasource associated with the adapter-managed connection factory.
In non-managed mode, the JCA service connects to a JCA adapter directly through the JCA adapter framework. The JCA adapter framework manages the connection to adapters using the connection factory properties defined in the JCA WSDL or using any overrides you provide in the JCA transport connection authentication properties, as described in the Transport Configuration Reference.
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:
The JCA transport logs messages using the WebLogic Server NonCatalog logger. JCA adapter framework logs are redirected to the WebLogic Server log.
Debug log records generated by the JCA transport, JCA adapter framework, and JCA adapters are redirected to the WebLogic Server log only if Oracle Service Bus transport debug logging is enabled. For more information, see Debugging Oracle Service Bus.
The JCA transport supports URI rewriting in a proxy service message flow.
The JCA transport declares the following environment variable values, which can be maintained when moving an Oracle Service Bus configuration among different deployment environments.
For descriptions of these values, see JCA Transport Configuration for Proxy and Business Services.
For inbound requests and outbound responses, the JCA adapter framework sends messages to JCA proxy services with UTF-8 encoding.
If you upgraded Oracle Service Bus 10g Release 3 to Maintenance Pack 1, you can add JCA transport functionality to existing domains using the Configuration Wizard. See the Oracle Service Bus Upgrade Guide for instructions.
New installations of Oracle Service Bus 10g Release 3 MP1 include the JCA transport and JCA adapter framework.
The JCA transport is compatible with a variety of EIS adapters. This section describes how to use the supported adapters with Oracle Service Bus and the JCA transport.
A WSDL is required to create a JCA proxy or business service in Oracle Service Bus. For proxy or business services that interact with supported adapters, you must generate the WSDLs in your EIS system environment. After you generate a WSDL, import it into your Oracle Service Bus configuration and use it to create a JCA service.
For example, for Oracle Applications, Oracle AQ, or Oracle Database adapters, generate a WSDL in Oracle JDeveloper, import the WSDL into Oracle Service Bus, and generate a configuration JAR for run-time deployment. Create and configure JCA services based on the WSDL, as described in Transport Configuration Reference.
The Oracle Service Bus JCA transport lets you interact with the following JCA-compliant adapters:
See the following guides for more information on Oracle adapters:
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 Applications, Oracle AQ, and Oracle Database adapters are deployed automatically in an Oracle Service Bus domain. You must manually install and deploy other supported resource adapters in the Oracle WebLogic Server Console, such as the Oracle Application Adapters.
You must create a data source for and configure each adapter in WebLogic Server, as described in the following section, Configuring Oracle Adapters.
Perform the following general steps to configure an already-deployed Oracle AppsAdapter, AqAdapter, or DbAdapter. The deployed adapter resource files (*.rar) are located in ALSB_HOME/lib/transports/jca/.
Note: | For Oracle databases, use the Oracle Driver (Thin XA) driver. |
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. |
Using Oracle JCA adapters with Oracle Service Bus requires that you create service WSDLs in Oracle JDeveloper. To ensure that you are using the most recent version of an adapter in Oracle JDeveloper, back up the existing adapter JAR file in the Oracle JDeveloper environment and replace it with the Oracle Service Bus JAR.
For example, if you are using the Oracle Database Adapter with Oracle Service Bus, copy ALSB_HOME/eclipse/plugins/com.bea.alsb.transports.jca.version/DBAdapter.jar to jdev/integration/lib/. The adapter JARs are also available inside the adapter RAR files in ALSB_HOME/lib/transports/jca/.
See the following sections for adapter-specific configuration information.
For the Oracle AQ Adapter’s data source, select the Test Connections on Reserve option.
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.
Note: | Only one proxy service can poll a specific Oracle Database table. |
To prevent stuck thread stack traces from appearing for the Oracle Database 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 the following WebLogic Server Administration Console Online Help topics:
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 2.
Use the following guidelines to invoke an EIS service from a client.
For configuration issues that apply to specific adapters, see Working with Adapters.
The “location” attribute in a WSDL’s <jca:address> binding element corresponds to a JNDI name for the EIS adapter managed connection factory.
See one of the following topics for business service creation and configuration details:
See one of the following topics for proxy service creation and configuration details:
This section describes the process of invoking an external service from an EIS through Oracle Service Bus.
The JCA transport supports request and synchronous request/response message patterns. This section illustrates a synchronous request/response pattern, as shown in Figure 3.
Use the following guidelines to invoke an external service from an EIS.
For configuration issues that apply to specific adapters, see Working with Adapters.
The “location” attribute in a WSDL’s <jca:address> binding element corresponds to a JNDI name for the EIS adapter.
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.
See one of the following topics for proxy service creation and configuration details:
This section provides descriptions for JCA transport-specific configuration options. For descriptions of general business and proxy service configuration options, see the following topics:
Use the following endpoint URI format for JCA services:
where resource_adapter_jndi is the value of location attribute in the JCA WSDL <jca:address> element, which is also the JNDI name for the adapter deployed on WebLogic Server.
JCA service endpoints are dependent on WSDLs, XML schemas, and service accounts. When any of those resource types is updated and saved for a service, the JCA service endpoint is automatically deleted, recreated, and redeployed. For a JCA proxy service, a new adapter listener is also initialized to listen for inbound requests.
JCA endpoint redeployment has a potential impact on services at run time, depending on whether or not you select the “Always use configuration from JCA WSDL” option for a service as described in Table 1. For example:
Table 1 describes the options available on the JCA transport configuration page in either Workshop for WebLogic or in the Oracle Service Bus console.
Select the instance of the WebLogic Server Work Manager that you want to use for the dispatch policy for this endpoint. The default Work Manager is used if no other Work Manager exists.
|
|||
JNDI Service Account is for JNDI context security, used to access the EIS adapter managed connection factory. Click Browse and select a service account. If no service account is specified, an anonymous subject is used.
For JCA business services, there is no restriction on the type of JNDI service account that can be configured, such as static or pass-through, but the run time must be able to access a user name and password. JCA proxy services can use only static JNDI service accounts.
For more information on JNDI service accounts, see the Security section.
|
|||
This option determines whether or not connection factory properties, activation spec properties (proxy services), and interaction spec properties (business services) are always used from the WSDL.
If this option is selected (default), the JCA transport interacts with the JCA framework in the following ways, depending on whether you are using managed or non-managed mode:
If this option is deselected, you can override the Activation/Interaction Spec Properties of the WSDL; and in non-managed mode you can override the Connection Factory Properties of the WSDL. At run time the JCA transport interacts with the JCA framework using the JCA WSDL and any activation/interaction spec or connection factory overrides you have provided.
For more information on using this option, see Endpoint Redeployment.
|
|||
Managed – Recommended for production. The JCA transport connects to the JCA adapter through the JCA adapter-managed connection factory configured in WebLogic Server. For authentication, specify a JNDI service account. If no JNDI service account is specified, an anonymous subject is used. In managed mode, Connection Factory Authentication Properties are read-only.
Non-Managed – The JCA transport connects to the JCA adapter through the JCA adapter framework, which acts as a container for the JCA adapter. For authentication, specify a JNDI service account. If no JNDI service account is specified, an anonymous subject is used. In non- managed mode, Connection Factory Authentication Properties are editable for overrides.
|
|||
This field is enabled if “Overwrite Connection Authentication Properties” is enabled and selected. This service account browser displays available service accounts. If the “Overwrite Connection Authentication Properties” option is selected, you must select a service account. For proxy services, only static service accounts are available.
|
|||
Development and Testing: You can override this value if you deselect “Always use configuration from JCA WSDL” and make the Connection Mode Non-Managed. In production environments, use managed mode, which makes the JCA transport connect to the adapter connection factory configured in WebLogic Server.
|
|||
“Activation Spec Properties” is the field name for proxy services; “Interaction Spec Properties” is the field name for business services.
If this service is an inbound service invoked by an EIS application, this field displays the activation spec properties for the JCA inbound operation shown in Operation Name field.
You can override the activation/interaction spec properties if you deselect “Always use configuration from JCA WSDL.”
|
|||
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.
Setting policies on JCA services has no effect on the services. Policies are used in SOAP WSDL services.
Application errors cannot be retried with the JCA transport, and the transport has no control of this option. Set this option to “No.”