25 Using the JCA Transport and JCA Adapters

This chapter describes the Oracle JCA adapter framework and provides guidance on using specific adapters with Service Bus. It also describes how to use and configure the Oracle JCA adapter in Service Bus services.

This chapter includes the following sections:

• Introduction to the JCA Transport

• JCA Adapter Configuration Recommendations for Service Bus

• Working with JCA Binding Resources

• Working with JavaScript Resources

• JCA Transport Configuration Reference

25.1 Introduction to the JCA Transport

Service Bus provides a J2EE Connector Architecture (JCA) transport that interacts with back-end Enterprise Information Systems (EIS), letting these systems participate in the Service Bus integration environment. The JCA transport provides native connectivity between Service Bus and external systems, letting those systems interact in the service bus layer and leverage the capabilities and features of Service Bus. For a list of adapters the JCA transport supports, see Supported JCA Adapters.

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 Service Bus Services Interacting With an EIS

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

25.1.1 Supported JCA Adapters

With JCA adapters, you can integrate proxy and business services with technologies like databases, file systems, FTP servers, messaging systems, email, LDAP, Coherence cache, cloud services, and Oracle E-Business Suite. Dragging a JCA adapter into a swimlane of the Service Bus Overview Editor invokes the Adapter Configuration Wizard, where you can define the configuration properties for the adapter. The following sections give an overview of the JCA adapters supported by Service Bus.

25.1.1.1 AQ Adapter

The AQ adapter lets Service Bus business and proxy services interact with a single consumer or multi-consumer queue. Oracle Streams AQ provides a flexible mechanism for bidirectional, asynchronous communication between participating applications. Advanced queues are an Oracle database feature, and are therefore scalable and reliable. Multiple queues can also service a single application, partitioning messages in a variety of ways and providing another level of scalability through load balancing.

For more information, see "Oracle JCA Adapter for AQ" in Understanding Technology Adapters.

25.1.1.2 Oracle BAM 11g Adapter

The Oracle BAM 11g adapter integrates Service Bus business and proxy services with Oracle BAM Server 11g. Dragging an Oracle BAM adapter into a swimlane of the Service Bus Overview Editor invokes the Adapter Configuration Wizard, where you can configure the adapter properties.

For more information, see Oracle Fusion Middleware Integration with Adapters in Understanding Technology Adapters.

25.1.1.3 Coherence Adapter

The Oracle Coherence adapter integrates Service Bus business services with Oracle Coherence. A Coherence cache is a collection of data objects that serves as an intermediary between the database and client applications. Database data can be loaded into a cache and made available to different applications. A Coherence cache reduces load on the database and provides faster access to database data. Objects in the cache can be either XML or Plain Old Java Objects (POJOs). The Coherence adapter enables you to perform the following operations against a Coherence cache.

• Add an item

• Obtain an item

• Remove an item

• Query for an item

For more information, see "Oracle JCA Adapter for Coherence" in Understanding Technology Adapters.

25.1.1.4 Database Adapter

The database adapter lets Service Bus business and proxy services communicate with Oracle databases or third-party databases through JDBC.

For more information, see "Oracle JCA Adapter for Database" in Understanding Technology Adapters.

25.1.1.5 File Adapter

The file adapter lets Service Bus business and proxy services exchange (read and write) files on local file systems. The file contents can be in both XML and non-XML data formats.

For more information, see "Oracle JCA Adapter for Files/FTP" in Understanding Technology Adapters.

25.1.1.6 FTP Adapter

The FTP adapter lets Service Bus business and proxy services exchange (read and write) files on remote file systems through use of the file transfer protocol (FTP). The file contents can be in both XML and non-XML data formats.

For more information, see "Oracle JCA Adapter for Files/FTP" in Understanding Technology Adapters.

25.1.1.7 JDE World Adapter

The JDE World adapter integrates Service Bus business services with the JDE World System, an ERP (Enterprise Resource Planning) product running on IBM minicomputers. The JDE World Adapter uses a new JDBC-driver based connection to the IBM system and lets Service Bus interact with JDE World system as a typical database.

For more information, see "Oracle JCA Adapter for JDE Edwards World" in Understanding Technology Adapters and the Integration Adapters Documentation page on Oracle Technology Network.

25.1.1.8 JMS Adapter

The JMS adapter lets Service Bus business and proxy services interact with a Java Messaging System (JMS). The JMS architecture uses one client interface to many messaging servers. The JMS model has two messaging domains:

• Point-to-point: Messages are exchanged through a queue and each message is delivered to only one receiver.

• Publish-subscribe: Messages are sent to a topic and can be read by many subscribed clients.

For more information, see "Oracle JCA Adapter for JMS" in Understanding Technology Adapters.

25.1.1.9 LDAP Adapter

The LDAP adapter lets Service Bus business and proxy services interact with an LDAP directory. The LDAP adapter defines both asynchronous and synchronous interfaces to send requests to and receive responses from LDAP directory servers. The LDAP adapter enables processes to search, compare, and modify LDAP directories using the LDAP protocol.

For more information, see "Oracle JCA Adapter for LDAP" in Understanding Technology Adapters.

25.1.1.10 MQ Series Adapter

The MQ Series adapter provides message exchange capabilities between Service Bus business and proxy services and the WebSphere MQ queuing systems. The Messaging and Queuing Series (MQ Series) is a set of products and standards developed by IBM. The MQ Series provides a queuing infrastructure that provides guaranteed message delivery, security, and priority-based messaging.

For more information, see "Oracle JCA Adapter for MQ Series" in Understanding Technology Adapters.

25.1.1.11 MSMQ Adapter

The MSMQ adapter provides message exchange capabilities between Service Bus business and proxy services and Microsoft Message Queueing (MSMQ). MSMQ is a message infrastructure and a development platform for creating distributed, loosely-coupled messaging applications for the Microsoft Windows operating system.

For more information, see "Oracle JCA Adapter for Microsoft Messaging Queue" in Understanding Technology Adapters.

25.1.1.12 Oracle E-Business Suite Adapter

The Oracle E-Business Suite adapter lets Service Bus business and proxy services interact with Oracle E-Business Suite. The adapter supports all modules of Oracle E-Business Suite in Release 12 and Release 11i, including selecting custom integration interface types based on the version of Oracle E-Business Suite.

For more information, see Oracle Fusion Middleware Oracle E-Business Suite Adapter User's Guide.

25.1.1.13 Salesforce Cloud Adapter

The Salesforce Cloud Adapter lets Service Bus business services interact with Salesforce services. It enables integration with Enterprise, Unlimited, or Developer Editions of Salesforce, and lets you connect a variety of systems to Salesforce, leveraging the SOAP API of Salesforce.

For more information, see the Integration Adapters Documentation page on Oracle Technology Network.

25.1.1.14 SAP Adapter

The SAP adapter is a packaged-application adapter that lets Service Bus business and proxy services integrate with SAP applications.

For more information, see "Packaged Application Adapters" in Understanding Technology Adapters and the Integration Adapters Documentation page on Oracle Technology Network.

25.1.1.15 Socket Adapter

The socket adapter lets you create a client or a server socket and establish a connection. With this adapter, you can model standard or nonstandard protocols for communication over TCP/IP sockets. The transported data can be text or binary in format.

For more information, see "Oracle JCA Adapter for Sockets" in Understanding Technology Adapters.

25.1.1.16 Third Party Adapter

The third party adapter lets Service Bus business and proxy services integrate third-party adapters such as PeopleSoft, SAP, and others. These third-party adapters produce artifacts (WSDL and JCA files) that can configure a JCA adapter.

For more information, see Packaged-Application Adapters in Understanding Technology Adapters.

25.1.1.17 User Messaging Service Adapter

The Oracle User Messaging Service supports messaging channels such as email, secure messaging service (SMS), instant messaging, and voice. The Oracle User Messaging Service provides a messaging proxy between Service Bus business and proxy services and the external world. The Oracle User Messaging Service provides two-way messaging (inbound and outbound).

For more information, see "Oracle JCA Adapter for UMS" in Understanding Technology Adapters.

25.1.2 Oracle JCA Adapter Limitations

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

• Limitations that Apply to All JCA Adapters

• Oracle JCA Adapters for Files/FTP Limitations

25.1.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.1.2.2 Oracle JCA Adapters for Files/FTP Limitations

For Oracle JCA Adapter for Files/FTP, the JCA transport does not support the following: pre- and post-processing of files, using a re-entrant valve for processing ZIP files, and file chunked read.

25.1.3 JCA Adapter Framework

The JCA transport uses the 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.

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, 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 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 and deploy your adapters.

25.1.4 JCA Transport Messaging

The JCA transport supports request-only and synchronous request/response messaging patterns using SOAP 1.1. 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.5 Security for JCA Transports

When a service uses the JCA transport, 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 support static, pass through, and mapping service accounts at runtime. If a service account is configured on a JCA business service, the 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 (such as Oracle Adapters for Database, AQ, and Oracle E-Business Suite) 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 Understanding Technology Adapters.

The JCA transport can also be used with Oracle Web Services Manager (OWSM) policies. For more information, see "Which OWSM Policies Are Supported for JCA Adapters?" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

25.1.5.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.5.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. Instead, 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 and 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 and password in the service account is used to invoke the outbound JCA endpoint.

25.1.6 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 the oracle.osb.debug.jca-framework-adapter logger is configured for debugging. JCA framework and adapter messages are logged with the tag JCA_FRAMEWORK_AND_ADAPTER. For more information, see "Configuring and Monitoring Log Files" in Administering Oracle Service Bus.

25.1.6.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.7 JCA Transport Error Handling

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. This fault structure is defined in the JCA transport schema.

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.

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.8 URI Rewriting with JCA Transports

The JCA transport supports URI rewriting in a pipeline.

25.1.9 JCA Transport Message Encoding

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

25.1.10 Rejected Messages

The JCA adapter framework automatically logs rejected messages (messages with data errors) to a /domain/jca/read/rejectedMessages directory for each adapter. For more information, see "Handling Rejected Messages" in Understanding Technology Adapters.

25.2 JCA Adapter Configuration Recommendations for Service Bus

The JCA transport is compatible with all JCA adapters, each of which can be configured through a set of endpoint properties, activation or interaction specification properties, or connection properties. Any runtime or binding properties defined for the JCA adapter itself are not propagated to the transport configuration in the proxy or business service. You need to manually configure those properties. For more information, see JCA Transport Endpoint Properties.

The following topics provide configuration recommendations specific to Service Bus.

25.2.1 Configuring the JCA Adapter Connections

The Oracle JCA adapters are deployed automatically in a Service Bus domain. You must manually install and deploy other supported third-party resource adapters in the Oracle WebLogic Server Administration Console. In order to use the deployed Oracle Adapters, you must create a data source and connection pool for each adapter in Oracle WebLogic Server. For information and instructions on creating the required data source and connection pool, see "Adding an Adapter Connection Factory" in Understanding Technology Adapters. Additional information about data sources is provided in that guide for each type of adapter.

25.2.2 Configuring JCA 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 the following topics:

• Using Work Managers with Service Bus

• "Using Work Managers to Optimize Scheduled Work" in Administering Server Environments for Oracle WebLogic Server

25.2.3 Configuring the Oracle JCA Adapter for Database

Only one proxy service can poll a specific Oracle Database table. 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

25.2.4 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.5 Configuring the Oracle JCA Adapter for Coherence

If the objects in the Coherence cache are Plain Old Java Objects (POJOs), the adapter configuration includes specifying the archive resource that stores the POJO JAR files. You can create this resource in the Service Bus project before you can create the Coherence adapter and its associated business service. The configuration wizard also gives you the option to search the file system for a JAR file to upload, and lets you import the file and create the archive resource in the Service Bus project. For more information about creating archive resources, see Working with JAR Files.

25.2.6 Configuring the Salesforce Cloud Adapter

In addition to a dependency on the standard WSDL file, the Salesforce adapter has a dependency on an enterprise WSDL file, which you generate directly from Salesforce. This file is associated with the JCA resource in addition to the standard JCA WSDL file, and is referenced in the proxy or business service's non-managed connection property as the value for the targetWSDLURL property.

25.3 Working with JCA Binding Resources

Using Oracle JDeveloper and other supported JCA development environments, you can create and configure a JCA adapter and create the JCA adapter resources (.jca files and WSDL files) used for the back-end integration.

In the Oracle Service Bus Console, you cannot create and configure a JCA adapter, but you can upload an adapter you created in JDeveloper into a JCA binding resource. Once you create the JCA binding resource, you can generate proxy and business services that use the Service Bus JCA transport to communicate with the EIS applications through the JCA adapter.

Once you create a JCA adapter in JDeveloper, you can import it into a JCA binding resource in the Oracle Service Bus Console if that is your development environment.

25.3.1 How to Create a JCA Adapter in JDeveloper

The Service Bus Overview Editor provides a simple drag-and-drop method of creating JCA adapters in Service Bus projects in JDeveloper. You can drag any supported JCA adapter from the Component window onto the canvas, which launches the configuration wizard for that adapter. Completing the wizard creates the JCA file and proxy or business service, and adds all the required files to the Service Bus project.

Note:

When you create a business or proxy service in JDeveloper by creating a JCA adapter directly in the overview, the JCA transport is still the intermediary between the service and the adapter.

For more information, see Adding Service Bus Components in this guide and Introduction to Oracle JCA Adapters in Understanding Technology Adapters

25.3.2 How to Import JCA Adapters in the Oracle Service Bus Console

The easiest way to create JCA binding resources in the Oracle Service Bus Console is by bulk importing the JCA resources you created in JDeveloper, including the JCA file, associated WSDL file, and TopLink mapping file). With a bulk import, Service Bus automatically creates JCA bindings out of JCA files, WSDL resources out of WSDL files, and XML document resources out of mapping files. Service Bus maintains the dependencies among the files. For more information on importing, see Importing and Exporting Resources and Configurations .

Once you import your JCA resources, you can generate proxy or business services out of them, as described in How to Generate a Proxy Service from a JCA Binding Resource and How to Generate a Business Service from a JCA Binding Resource.

25.3.3 How to Create a JCA Binding Resource in the Oracle Service Bus Console

If you do not bulk import your JCA resources into the Oracle Service Bus Console, you can manually create JCA binding resources and upload the JCA file to the console. A JCA file and WSDL file are required to create a JCA proxy or business service in the Oracle Service Bus Console. This section describes the process for creating a JCA binding resource. For information about creating a WSDL resource, see How to Create a WSDL Resource in the Console.

To create a JCA binding resource in the console:

1. In Oracle JDeveloper, create and configure a JCA adapter. You can do this directly in a Service Bus project using the Service Bus Overview Editor.

   For more information, see Adding Service Bus Components.

2. In the Oracle Service Bus Console, upload any JCA dependencies for the JCA adapter you created in Oracle JDeveloper, such as the WSDL and XML resources.
3. In the Project Navigator, right-click the project or folder to contain the new JCA binding resource, point to Create, and select JCA Binding.
4. Do one of the following:

   • To upload a JCA file when you create the resource, click Browse next to the File Upload field and then navigate to and select the JCA file to use.

     The Resource Name field is automatically populated with the file name minus the file extension. You can change this name and optionally enter a description. JCA binding names must be unique.

   • To create a JCA binding resource and upload the JCA file at a later time, enter a name and optional description for the resource.

5. Click Create.

   The JCA Binding Definition Editor appears.

6. In the JCA Binding Definition Editor toolbar, click Save.
7. To end the session and deploy the configuration to the runtime, click Activate.

After you add JCA binding resources and its dependencies, you can generate proxy and business services from JCA bindings. For more information, see How to Generate a Proxy Service from a JCA Binding Resource and How to Generate a Business Service from a JCA Binding Resource.

25.3.4 How to Edit JCA Binding Resources in the Console

If you are using the Oracle Service Bus Console, use the following procedure to edit JCA bindings.

For information about modifying JCA adapters in JDeveloper, see How to Edit Components from the Service Bus Overview Editor.

To edit a JCA binding in the console:

1. In the Project Navigator, expand the project and folders containing the JCA binding to edit.

2. Right-click the JCA binding name, and select Open.

3. To search for and select a new WSDL file to reference, click the Choose a WSDL icon in the WSDL Dependency section.

4. To modify the contents of the JCA file or upload a new JCA file, do the following:

   1. Click Edit Source in the toolbar.

      The Edit Source dialog appears.

   2. To browse to and select a new JCA file to upload, click Browse.

   3. To modify the contents of the file, update the code directly in the Contents section of the dialog.

   4. Click Save.

5. In the JCA Binding Definition Editor toolbar, click Save.

6. To end the session and deploy the configuration to the runtime, click Activate.

25.3.5 How to Delete JCA Binding Resources

If any business service or proxy service is based on the JCA binding resource, remove the JCA binding resource from the business service or proxy service before deleting the JCA binding resource itself. In the Oracle Service Bus Console, open the JCA binding in the JCA Binding Definition Editor and click the References icon in the upper right to find out if it has any references. In JDeveloper, right-click the JCA file and select Explore Dependencies.

To delete a JCA binding resource:

1. In the Application Navigator or Project Navigator, expand the project and folders containing the JCA binding to delete.
2. Right-click the name of the JCA binding, and select Delete.

   The JCA binding resource is deleted. A Deletion Warning icon appears when other resources reference this resource. You can delete the resource with a warning confirmation. This might result in conflicts due to unresolved references to the deleted resource.

3. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

25.3.6 Using Custom JCA Adapters

You can create and use custom JCA adapters in Service Bus projects. You can only create a custom adapter in JDeveloper. Once you create the adapter, you can either use it in JDeveloper or you can import the adapter's associated file into the Oracle Service Bus Console as described in How to Create a JCA Binding Resource in the Oracle Service Bus Console. You can then use the adapter 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.

25.3.6.1 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_ORACLE_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>

25.3.6.2 Registering and Using a Custom JCA Adapter with Service Bus

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

1. In JDeveloper, create a custom JCA adapter.

   You can do this using the Service Bus Overview Editor, as described in Adding Service Bus Components. For more information about configuring a custom adapter, see Creating a Custom Adapter in Understanding Technology Adapters.

2. Do one of the following, using the sample registration file in About the Custom Adapter Registration File as a basis:

   • If the custom adapter registration file, OSB_ORACLE_HOME/config/adapter/OSBSupportedAdapters.xml, already exists, add your custom adapter to the list of supported adapter types.

   • If the custom adapter registration file does not exist, create the file. Replace the sample adapter type names with the actual names from your adapter JCA file.

3. If you are using the Oracle Service Bus Console for development, import the new custom adapter JCA resources into the console. For information and instructions, see Working with JCA Binding Resources.
4. On the JCA transport configuration page of the business or proxy service, configure the endpoint properties, dynamic endpoint properties, and activation or interaction spec properties. For information about the properties that are available for each adapter, see Oracle JCA Adapter Properties in Understanding Technology Adapters.

   Note:

   • You can use the JCA file to generate a proxy or business service, or you can configure JCA proxy or business services to use your custom adapter. For information on generating a service from a JCA file, see Creating and Configuring Business Services or Creating and Configuring Proxy Services.

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

25.4 Working with JavaScript Resources

The JCA Adapter for Sockets provides support for handling a handshake using custom JavaScript in addition to using XSLT and custom Java code. JavaScript is a light-weight scripting language used to add interactive features to HTML pages.

25.4.1 How to Create JavaScript Resources

f you are working in JDeveloper, you can add JavaScript to your projects using standard JDeveloper features. For more information, see "Developing Applications with Script Languages" in Developing Applications with Oracle JDeveloper.

In the Oracle Service Bus Console, you create a JavaScript resource and upload an existing JavaScript file into the resource.

To create a JavaScript resource in the Oracle Service Bus Console:

1. In Oracle JDeveloper or other editor, create and define the JavaScript file.
2. In the Project Navigator of the Oracle Service Bus Console, right-click the project or folder to contain the new JavaScript resource, point to Create, and select JavaScript.
3. Do one of the following:

   • To upload a JavaScript file when you create the resource, click Browse next to the File Upload field and then navigate to and select the file to use.

     The Resource Name field is automatically populated with the file name minus the file extension. You can change this name and optionally enter a description. JavaScript resource names must be unique.

   • To create a JavaScript resource and upload the actual file at a later time, enter a name and optional description for the resource.

4. Click Create.

   The JavaScript Definition Editor appears.

5. In the JavaScript Definition Editor toolbar, click Save.
6. To end the session and deploy the configuration to the runtime, click Activate.

25.4.2 How to Edit JavaScript Resources

If you are using JDeveloper, you can edit the JavaScript file using the standard editors in the IDE. If you are using the Oracle Service Bus Console, use the following procedure to edit JavaScript resources.

To edit a JavaScript resource in the Oracle Service Bus Console:

1. In the Project Navigator, expand the project and folders containing the JavaScript resource to edit.

2. Right-click the JavaScript resource name, and select Open.

3. To modify the contents of the JavaScript resource or upload a new JavaScript resource, do the following:

   1. Click Edit Source in the toolbar.

      The Edit Source dialog appears.

   2. To browse to and select a new JCA file to upload, click Browse.

   3. To modify the contents of the file, update the code directly in the Contents section of the dialog.

   4. Click Save.

4. In the JavaScript Definition Editor toolbar, click Save.

5. To end the session and deploy the configuration to the runtime, click Activate.

25.4.3 How to Delete JavaScript Resources

If the JavaScript resource is associated with a JCA adapter, remove the resource from the adapter before deleting the JavaScript resource itself. In the Oracle Service Bus Console, open the JavaScript resource in the JavaScript Definition Editor and click the References icon in the upper right to find out if it has any references. In JDeveloper, right-click the JavaScript file and select Explore Dependencies.

To delete a javaScript resource:

1. In the Application Navigator or Project Navigator, expand the project and folders containing the JavaScript resource to delete.
2. Right-click the name of the resource to delete, and select Delete.

   The javaScript resource is deleted. A Deletion Warning icon appears when other resources reference this resource. You can delete the resource with a warning confirmation. This might result in conflicts due to unresolved references to the deleted resource.

3. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

25.5 JCA Transport Configuration Reference

This section provides descriptions for JCA transport-specific configuration options.

• JCA Transport Endpoint URIs

• JCA Transport Headers and Normalized Message Properties

• JCA Transport Endpoint Properties

• JCA Transport Environment Variables

• Configuring Proxy and Business Services to Use the JCA Transport

• Proxy Service Operation Configuration

Note:

Note that runtime and binding properties defined in the JCA adapter file are not propagated to the proxy or business service configuration. You need to configure those properties manually by modifying the endpoint, spec, and connection properties described in the following sections.

For descriptions of general business and proxy service configuration options, see the following topics:

• Creating and Configuring Proxy Services

• Creating and Configuring Business Services

25.5.1 JCA Transport Endpoint URIs

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 WSDL files, service accounts, JCA resources, XML schemas, and XML resources (TopLink 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-2. For example, after a JCA endpoint is redeployed:

• If Always use configuration from JCA file is selected, 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 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 the JCA adapter normalized message properties. On inbound messages from Oracle JCA adapters, the 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.

You can select each normalized message property from a list of options when creating an XQuery expression.

Note:

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

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

Service Bus transport headers are predefined in the $inbound and $outbound request variables. For lists and descriptions of the normalized message properties, see the following topics in Understanding Technology Adapters:

• JCA Properties for Oracle AQ Adapter: Normalized Properties

• Coherence Adapter Normalized Properties

• JCA Properties for Oracle Database Adapter: Normalized Properties

• JCA Properties for Oracle File Adapter: Normalized Properties

• JCA Properties for Oracle FTP Adapter: Normalized Properties

• JCA Properties for Oracle JMS Adapter: Normalized Properties

• JCA Properties for Oracle MQ Adapter: Normalized Properties and RFH Version 2 (RFH2) Headers

• MSMQ Adapter Normalized Properties

• UMS Adapter Message Headers

25.5.3 JCA Transport 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 Configuring Proxy and Business Services to Use the JCA Transport.. For more information about endpoint properties, see "Oracle JCA Adapter Properties" in Understanding Technology Adapters.

Caution:

Even though these properties might be defined in the JCA adapter file, they also need to be defined for the business or proxy service.

25.5.3.1 Standard Endpoint Properties

A standard set of endpoint properties applies to most JCA adapters. When you configure a JCA-based proxy or business service, you can select these properties from a list of options and configure their value. Table 25-1 lists and describes the endpoint properties you can select for a JCA transport.

Table 25-1 JCA Transport Endpoint Properties

Property Name	Description
jca.retry.count	Indicates the maximum number of retries before rejection.
jca.retry.interval	Indicates the time interval between retries (measured in seconds).
jca.retry.backoff	Indicates the retry interval growth factor (positive integer).
jca.retry.maxInterval	Indicates the maximum value of retry interval; that is, a cap if backoff is greater than 1.
jca.retry.maxPeriod	Indicates the maximum total retry period for outbound JCA adapters. Retries do not occur longer than the value specified in this property.
activationInstances	Increases the number of polling (worker) threads for an inbound JCA resource adapter. It is only meant to help increase concurrency for adapters that do not natively support multithreading. Since most of the adapters included with Oracle Fusion Middleware natively support multithreading, this setting is mostly useful to third party (custom) JCA adapters, which do not natively support multithreading. Set this property to the number of threads required for a particular JCA adapter.
payloadSizeThreshold	Specifies the payload size threshold in the adapter layer. The messages that have sizes beyond the configured threshold limit are rejected. If this property is not configured, it does not impose any restriction on the size of messages.
rejectUncorrelatedMessages	Specifies whether to reject messages that cannot be correlated. When native correlation is used to correlate an inbound asynchronous message with a previous outbound message, the JCA framework normally tries to post the message to the service, whether the inbound message can be correlated or not. By setting this property to true, the JCA framework rejects a message that cannot be correlated (when native correlation is active).
UseWorkManager	Specifies a custom work manager to use for starting polling (worker) threads instead of using the standard work manager used by default. Use this property to configure an inbound JCA endpoint to use a specific WebLogic Work Manager. The work manager is only used to start the JCA service for which this property is defined. The value for this property is just the name of the work manager. If the JNDI lookup fails, the default Service Bus work manager is used.

25.5.3.2 Dynamic Endpoint Properties

Most JCA adapters support a large set of endpoint properties that are unique to the type of system being integrated. When you configure a JCA-based proxy or business service, you can select these properties from a list of options and configure their value. For lists and descriptions of the normalized message properties, see the following topics in Understanding Technology Adapters:

• Binding Properties for all Oracle JCA Adapters

• Binding Properties for Oracle AQ Adapter

• Oracle JCA Adapter for Database

• Binding Properties for Oracle File and FTP Adapters

• Binding Properties Specific to Oracle FTP Adapter

• Binding Properties for Oracle JMS Adapter

• Binding Properties for Oracle MQ Series Adapter

• MSMQ Adapter Binding Properties

• UMS Adapter Message Headers

25.5.3.3 Activation and Interaction Specification Properties

Activation specification properties are specific to proxy services and interaction specification properties are specific to business services in Service Bus. You cannot add or remove these properties; you can only change their values. The properties that appear on the Transport configuration page vary depending on how you defined the adapter properties when creating the adapter in the Adapter Configuration Wizard.

Updating these properties require the adapter endpoint to be recycled. These types of properties have various dependencies on each other. For lists and descriptions of the activation and interaction specification properties, see the following topics in Understanding Technology Adapters:

• Properties for all Oracle JCA Adapters

• JCA Properties for Oracle AQ Adapter

• Coherence Adapter JCA Properties

• Oracle JCA Adapter for Database

• JCA Properties for Oracle File and FTP Adapters

• JCA Properties Specific to Oracle FTP Adapter

• JCA Properties for Oracle JMS Adapter

• LDAP Adapter Connection Properties

• JCA Properties for Oracle MQ Series Adapter

• MSMQ Adapter JCA Properties

• JCA Properties for Oracle Socket Adapter

• UMS Adapter Activation Spec Properties

• UMS Adapter Interaction Specification Properties

25.5.4 JCA Transport Environment Variables

The JCA transport declares the following environment variable values, which can be maintained when moving a Service Bus configuration among different deployment environments.

For descriptions of these values, see Configuring Proxy and Business Services to Use the JCA Transport. For more information about environment variables, see "Customizing Oracle Service Bus Environments" in Administering Oracle Service Bus.

• Work Manager

• JCA Always Use JCA File Flag

• JCA Connection Mode

• JCA Overwrite Connection Authentication Flag

25.5.5 Configuring Proxy and Business Services to Use the JCA Transport

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

Table 25-2 JCA Transport Properties

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 mapping files, 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	Displays the name of the adapter that the JCA service will use.
Adapter Type	Displays the adapter type.
Dispatch Policy	Select the instance of 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 the following topics: Using Work Managers with Service Bus Using Work Managers to Optimize Scheduled Work in Administering Server Environments for Oracle WebLogic Server .
JNDI Service Account	Click Browse and select a JNDIservice account, which is used for JNDI context security to access the EIS adapter managed connection factory. 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 Security for JCA Transports.
EndPoint Properties	Click the Add icon to select endpoint properties from the available list and assign a value to each property. This field lets you assign values to endpoint properties, such as the number of retries for the type of adapter the service uses. For links to information about supported endpoint properties, see JCA Transport Endpoint Properties.
Dynamic EndPoint Properties	Click the Add icon to define dynamic properties for the endpoint and assign a value to each property. Enter a name/value pair for each dynamic endpoint property you want to provide. The endpoint property key matches the query parameter name. 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 Understanding Technology Adapters. For links to information about supported endpoint properties, see JCA Transport Endpoint Properties.
Always use configuration from JCA file	Select this option to specify whether Activation Spec Properties (proxy services) and Interaction Spec Properties (business services) are always used from the JCA file. If you select this option (default), the JCA transport interacts with the JCA framework using the activation or interaction spec properties in the JCA file. If you clear this option, you can override the activation and interaction spec Properties. For the redeployment impact of using this option, see Endpoint Redeployment.
Operation Name	Displays a read-only name of the selected WSDL operation. Each operation can have its own activation or interaction spec properties.
Activation/Interaction Spec Properties	For business services, this field displays the outbound interaction spec properties for the JCA inbound operation shown in the Operation Name field. For proxy services, this field displays the activation spec properties for the JCA inbound operation shown in the Operation Name field. You can override the activation or interaction spec properties if you clear Always use configuration from JCA file. Note: For Oracle Adapter Suite adapters, activation/interaction spec properties are read-only. The Oracle Adapter Suite adapters store their own configurations, which you must change in the Oracle Adapter Suite management tools.
Connection Mode	Select from one of the following options to specify how the service connects to the associated JCA adapter. 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. 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. You can edit the connection factory properties for overrides. Notes: These options are only available for certain adapters, such as legacy and Cloud adapters. If you want to change from non-managed mode to managed mode, deselect the Overwrite Connection Authentication Properties option before changing modes.
Overwrite Connection Authentication Properties	Select this option to specify that the user name and password in the adapter connection factory be overwritten by the Connection Authentication Service Account credentials. If no service account is specified, an anonymous subject is used. This option is available only if the connection factory properties contain user name and password properties, the connection mode is Non-Managed, and Always use configuration from JCA file is not selected.
Connection Authentication Service Account	Browse to and select the service account to use for authentication if you selected Overwrite Connection Authentication Properties above (you must specify a service account if you selected Overwrite Connection Authentication Properties). For proxy services, only static service accounts are available.
Connection Factory Properties	Enter any connection factory override values. Notes: You can override property values if you deselect Always use configuration from JCA file and the connection mode is non-managed. In production environments, use managed mode so the JCA transport connects to the adapter connection factory configured in WebLogic Server.

For more information on endpoint and activation and interaction spec properties, see Adapter Framework in Understanding Technology Adapters.

25.5.6 Proxy Service Operation Configuration

JCA WSDL files support document literal binding only. The only algorithm for Operation configuration in JCA proxy services is SOAPAction Header. Service Bus effective WSDL files always contain SOAPAction. The value of the SOAPAction field is the operation name.