6.8 Adding Adapter Services to Oracle Enterprise Service Bus

Oracle Enterprise Service Bus provides support for creating and modifying services for the Oracle Technology adapters. The Oracle Technology adapters enable you to integrate mainframe and legacy applications with enterprise resource planning (ERP), customer relationship management (CRM), database, and messaging systems.

Table 6-2 provides a summary of the Oracle Technology adapter services you can create. Adapters services can be configured as inbound or outbound adapters services. Inbound adapter services send messages to the enterprise service bus, while outbound adapter services send messages to an application or system external to the enterprise service bus.

Table 6-2 Summary of Oracle Technology Adapters

Adapter Service	Description
AQ Adapter Service	Sends or receives messages from Oracle Advanced Queuing single or multiconsumer queues
Database Adapter Service	Sends or receives messages extracted from an Oracle Database table or created by executing a stored procedure
File Adapter Service	Sends or receives messages from a file in the local file system
FTP Adapter Service	Sends or receives messages from a file at a remote FTP server
JMS Adapter Service	Sends or receives messages from a JMS queue or topic
MQ Adapter	Sends or receives messages from IBM's MQ Series
Oracle Applications Adapter Service	Sends or receives messages from an Oracle E-Business Suite interface

Refer to the following resources for more information:

For an overview of adapters, see Oracle Application Server Adapter Concepts.
For specific details about configuring adapters for Oracle Enterprise Service Bus, see Oracle Application Server Adapter for Files, FTP, Databases, and Enterprise Messaging User's Guide.
For information about using the Oracle Applications adapter for Oracle E-Business Suite, see Oracle Application Server Adapter for Oracle Applications User's Guide.
For information about managing adapters in Oracle Enterprise Service Bus, see "Creating Inbound and Outbound Services" in Oracle Enterprise Service Bus Developer's Guide.
For a tutorial that describes how to design an Oracle Enterprise Service Bus flow that uses adapter services, see Oracle Enterprise Service Bus Quick Start Guide.

6.8.1 How to Add Adapter Services

Oracle JDeveloper ESB Designer provides wizards that assist you in creating inbound and outbound adapter services. The wizard collects the necessary information to generate the WSDL file that defines the service.

To add an adapter service:

In the Application Navigator, navigate to the ESB project for which you want to create a SOAP service, expand the Resources folder. Double click project-name.esb, where project-name is the name of the project to which you want to add the SOAP service.

The Design tab for the project is displayed.
In the Component Palette, click the down arrow and select Adapter Services if not already selected.
Drag and drop an adapter into the Design tab.

The create adapter service dialog for the specific adapter type opens.
Enter the Name, System/Group, and an optional Description for the adapter.

Name: Enter a unique name across the ESB system in which you are creating the service; spaces are not allowed.

System/Group: Click on the flashlight (torch) to open the ESB Service Group Browser dialog and select the system/group for this service. For example: Fulfillment under Systems/Groups in project.

Description: Enter an optional description.
To complete WSDL File field, you can click on the following icons to the right of the field:
- Configure adapter service wsdl icon
  
  Click on this icon to launch the adapter configuration wizard for the specific type of adapter you have selected from the Component Palette. The wizard guides you through the setups.
  
  For details about configuring the AQ, database, file, FTP, JMS, and MQ adapters in Oracle JDeveloper ESB Designer, see Oracle Application Server Adapter for Files, FTP, Databases, and Enterprise Messaging User's Guide. For details about configuring the Oracle application adapter for Oracle E-Business Suite, see Oracle Application Server Adapter for Oracle Applications User's Guide.
- Service Explorer icon
  
  Click on this icon to launch the Service Explorer and search for deployed services.
  
  See Section 6.5.1, "How to Browse for Deployed Services".
Click OK.

Figure 6-4 is an example of a completed Create Adapter Service dialog.

Figure 6-4 Create Adapter Service Dialog

Description of "Figure 6-4 Create Adapter Service Dialog"

The new adapter service appears in the Design tab, as shown in Figure 6-1. The adapter service requires a routing service to route message instances to or from the adapter service.

6.8.2 How to Modify Adapter Services

You can modify adapter services in Oracle JDeveloper ESB Designer by opening the adapter property page.

To modify an adapter service:

In the Design tab, double click on the upper section of the adapter service icon. The cursor is shaped like a hand on that region of the icon. An example of the Design tab is shown in Figure 6-7.
Make your changes to the adapter service information that can be modified. Note that the name of the service cannot be changed.
In the Endpoint Properties panel, you can add, delete, update, or view endpoint properties for the service. For information about endpoint properties, see Section 6.6, "Adding Endpoint Properties for Adapter or SOAP Services".
Save your changes.

6.8.3 How to Delete Adapter Services

You can delete an adapter service in the Oracle JDeveloper ESB Designer Design tab.

To delete an adapter service:

In the Diagram tab, select the adapter service icon.
Click the large red X at the top of Design tab to delete the selected adapter service.
Confirm that you want to delete the selected service.
Save your changes.

Note:

Do not delete adapter services in the Application Navigator.

6.8.4 What Happens When You Add Adapter Services

When you complete the information for adding a new adapter service, the adapter service icon displays in the Design tab and the service definition file appears in the Application Navigator in the Resources folder of the ESB project. The name of the adapter entry in the Application Navigator includes the ESB system name, the adapter name, and the esbsvc extension, in the form system-name_service-name.esbsvc. The actual source of the service definition file is not visible in Oracle JDeveloper ESB Designer.

A WSDL file is created for the service of the form service_name.wsdl which appears in the Application Navigator. The WSDL file defines the input and output messages for this instance flow, the supported client interface and operations, and other features. Example 6-2 is a sample adapter WSDL file.

Example 6-2 Sample Adapter WSDL File

<definitions
     name="USPSShipment"
     targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/file/USPSShipment/"
     xmlns="http://schemas.xmlsoap.org/wsdl/"
     xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/file/USPSShipment/"
     xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
     xmlns:jca="http://xmlns.oracle.com/pcbpel/wsdl/jca/"
     xmlns:imp1="http://www.globalcompany.com/ns/USPSShipment"
     xmlns:hdr="http://xmlns.oracle.com/pcbpel/adapter/file/"
    >
    <import namespace="http://xmlns.oracle.com/pcbpel/adapter/file/"
 location="fileAdapterOutboundHeader.wsdl"/>
    <types>
      <schema xmlns="http://www.w3.org/2001/XMLSchema" >
        <import namespace="http://www.globalcompany.com/ns/USPSShipment" schemaLocation="USPSShipment.xsd" />
      </schema>
    </types>
    <message name="shipment_msg">
        <part name="shipment" element="imp1:shipment"/>
    </message>
    <portType name="Write_ptt">
        <operation name="Write">
            <input message="tns:shipment_msg"/>
        </operation>
    </portType>
    <binding name="Write_binding" type="tns:Write_ptt">
    <jca:binding  />
        <operation name="Write">
      <jca:operation
          PhysicalDirectory="C:\SOAFilesOut"
          InteractionSpec="oracle.tip.adapter.file.outbound.FileInteractionSpec"
          FileNamingConvention="shipment_%SEQ%.txt"
          NumberMessages="1"
          OpaqueSchema="false" >
      </jca:operation>
      <input>
        <jca:header message="hdr:OutboundHeader_msg" part="outboundHeader"/>
      </input>
        </operation>
    </binding>
    <service name="USPSShipment">
        <port name="Write_pt" binding="tns:Write_binding">
      <jca:address location="eis/FileAdapter" />
        </port>
    </service>
  <plt:partnerLinkType name="Write_plt" >
    <plt:role name="Write_role" >
      <plt:portType name="tns:Write_ptt" />
    </plt:role>
  </plt:partnerLinkType>
</definitions>

A standard header file is created for the adapter service of the form adapter_typeAdapterOutboundHeader.wsdl or adapter_typeAdapterInboundHeader.wsdl, depending on whether the service is inbound or outbound. The adapter_type specifies the type of adapter, such as DB, file, or jms. Example 6-2 is a sample adapter header file.

Example 6-3 Sample Adapter Header File

definitions
     name="fileAdapter"
     targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/file/" 
     xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/file/"   
     xmlns="http://schemas.xmlsoap.org/wsdl/" >
    <types>
        <schema attributeFormDefault="qualified" elementFormDefault="qualified" 
                targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/file/"
                xmlns="http://www.w3.org/2001/XMLSchema" 
                xmlns:FILEAPP="http://xmlns.oracle.com/pcbpel/adapter/file/">
            <element name="OutboundFileHeaderType">
                <complexType>
                    <sequence>
                        <element name="fileName" type="string"/>
                    </sequence>
                </complexType>
            </element>  
        </schema>
    </types>
    <!-- Header Message --> 
    <message name="OutboundHeader_msg"> 
      <part element="tns:OutboundFileHeaderType" name="outboundHeader"/> 
   </message> 
</definitions>

When the ESB project is registered with the ESB server, the ESB files for the adapter service that are created in Oracle JDeveloper ESB Designer are deployed to the design time metadata server. See Section 6.2.1, "What Happens When you Create an Oracle Enterprise Service Bus Flow".

6.8.5 What Happens at Runtime

During runtime, an inbound adapter service receives a message instance from an external source and sends the message to an ESB routing service for processing.

An outbound adapter receives a message instance from an ESB routing service and sends the message to an external source.