6.9 Adding Routing Services to Oracle Enterprise Service Bus

A routing service is the key component for moving a message across the enterprise service bus – from its entry point to its exit point. Oracle JDeveloper ESB Designer provides tools that assist you in creating a routing service

The following are the key components that define a routing service:

• WSDL file

• Target services and operations

• Transformation definition

• Filter Expression

• Execution type (synchronous or asynchronous)

• The ESB systems from which the routing service accepts messages

The WSDL specifies how other services (either within or outside of the enterprise service bus) call the routing service. The remaining items, referred to as routing rules, determine where the routing service sends each message it receives, how it sends it, and what, if any, changes it makes to the message structure prior to sending it to the target service.

Oracle JDeveloper ESB Designer provides tools that assist you in creating the routing service WSDL and defining the routing rules.

There are two main ways you can create the routing service WSDL:

• By specifying an existing WSDL file and one of the port types defined within that WSDL

  This option enables you to use an existing WSDL file (on the local file system or at an Oracle JDeveloper ESB Designer connection) to define the routing service. Oracle JDeveloper ESB Designer parses the WSDL you specify to present the list of port types from which you make a selection.

  If you want to edit an existing WSDL for the routing service, edit it using a WSDL editor (such as Oracle JDeveloper) prior to specifying it in this dialog.

• By generating the WSDL from a schema file (.xsd)

  This option enables you to use an existing XSD file or a file in a native file format (such as a comma-separated value (CSV) file, a fixed-length file, a document type definition (DTD) file or a COBOL copybook file) to define the routing service.

  You can specify the same or different schema files for the request, response, and fault message schemas, which Oracle JDeveloper ESB Designer converts into WSDL input, output, and fault elements in the WSDL. Minimally, you must specify the schema for the request message. You cannot specify a fault message schema, unless you also specify a response.

  In addition, you specify the operation and namespace. Oracle JDeveloper ESB Designer converts the operation into a operation element in the WSDL file and the namespace you specify is defined as the tns namespace in the WSDL file.

  The operation element describes how input to the operation is defined.

For information about managing routing services in Oracle Enterprise Service Bus, see "Creating Routing Services and Routing Rules" in Oracle Enterprise Service Bus Developer's Guide.

6.9.1 How to Add Routing Services

To create a routing service, you complete the Create Routing Service dialog available in Oracle JDeveloper ESB Designer. You can access this dialog using either of the following two methods described here.

To add an adapter service schematically using the Design tab:

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

   The Design tab for the project is displayed.

2. In the Component Palette, click the down arrow and select ESB services if they are not already selected.

3. Drag and drop Routing Service into the Diagram tab.

   The Create Routing Services dialog opens.

4. You can also right-click in the Design tab, then select Create ESB Service > Routing Service.

To create the routing service using dialog boxes only:

1. In the Applications navigator, right-click the ESB project for which you want to create a routing service, and then click New.

   The New Gallery opens.

2. In the Categories panel, expand Business Tier, and then click Web Services.

3. In the Items panel, click ESB Routing Service, and then click OK.

   The Create Routing Service dialog opens.

The Create Routing Service dialog provides three methods for specifying the WSDL for the routing service, as described in the following sections. Each of these sections provides step-by-step instructions on completing the Create Routing Service dialog for the method you want to use.

Figure 6-5 is an example of a Create Routing Service dialog with the Request tab displayed.

Figure 6-5 Create Routing Service - Request Tab

Description of "Figure 6-5 Create Routing Service - Request Tab"

6.9.1.1 How to Generate the WSDL for a Routing Service from an Existing XSD File

Use this method to provide an existing WSDL for the routing service. After you specify the file, Oracle JDeveloper ESB Designer parses it to determine the defined schema elements and presents them in a drop-down list from which you can make a selection.

To generate a WSDL from an existing XSD file:

1. If you have not already done so, open the Create Routing Service dialog.

2. In the Name field, enter a name for the routing service.

   The name must be unique within the scope of the project in which the routing service is being created. Spaces are not allowed.

3. For the System/Group field, click Browse to open the ESB Service Group Browser dialog, select the system (and service group, if desired) to which you want to add the routing service, and then click OK.

   To create a new system or service group to contain the routing service you are creating, click Create New at the top of the ESB Service Group Browser dialog. See Section 6.4.1, "How to Create an ESB System or Service Group" for information on creating a new ESB system or service group.

4. In the Description field, enter a description for the routing service, if desired. This field is optional.

5. Choose Generate WSDL from Schemas.

   This option includes the Request, Reply, and Fault tabs.

6. On the Request tab, click Browse to access the Schema Location.

   The Type Chooser dialog opens and presents the schema files (XSD files) from which you can choose to generate the WSDL. Expand the trees under Project Schema Files, Project WSDL Files, and ESB to locate the schema. Navigate to the root element of the XSD file for the message instance that you want this routing service to process. Select the element and click OK.

   You can also import a schema or WSDL file by clicking on the Import Schema File or Import WSDL icon that appears at the top right of the Type Chooser dialog.

   Figure 6-6 is an example of a Type Chooser dialog with the Import Schema Files tree expanded.

   Figure 6-6 Type Chooser Dialog

   
   Description of "Figure 6-6 Type Chooser Dialog"
   
   

7. In the Request tab Schema Element field, select the root element for the message that you want this routing service to process if not already selected.

8. On the Reply tab, repeat the steps for the Request tab if entering any information.

9. On the Fault tab, repeat the steps for the Request tab if entering any information.

10. In the Operation Name field, enter the operation name. Spaces are not allowed.

11. In the Namespace field, enter a namespace or accept the current value.

12. Click OK.

The routing service is created and an icon is added to the ESB Project's Design tab.

6.9.1.2 How to Generate the WSDL to Create a Routing Service Based on a Sample File

Oracle JDeveloper ESB Designer provides a wizard that assists you in creating the XSD representation of various file formats (such as CSV file, fixed-length file, DTD, and Cobol copybooks) based on a sample file and details that you provide about the file's structure. You can then direct Oracle JDeveloper ESB Designer to generate the WSDL for the routing service from that XSD file.

To generate a WSDL based on a sample file:

1. If you have not already done so, open the Create Routing Service dialog.

2. In the Service Name field, enter a name for the routing service.

   The name must be unique within the scope of the project in which the routing service is being created. Spaces are not allowed.

3. For the System/Group field, click Browse to open the ESB Service Group Browser dialog, select the system (and service group, if desired) to which you want to add the routing service, and then click OK.

   Click Help for assistance in using the ESB Service Group Browser dialog.

4. In the Description field, enter a description for the routing service, if desired. This field is optional.

5. Choose Generate WSDL from Schema.

   This option includes the Request, Reply, and Fault tabs.

6. On the Request tab, click Define Schema for Native Format.

   The Native Format File Builder wizard opens.

7. Follow the steps through the wizard.

   If you need assistance on a wizard page, click Help.

8. In the Schema Element field on the Request tab, select the root element for the message that you want this routing service to process.

9. Reply tab

10. Fault tab

11. Operation Name

    Spaces are not allowed.

12. Namespace

13. Click OK.

The routing service is created and an icon is added to the ESB project's Design tab.

6.9.1.3 How to Select an Existing WSDL to Create a Routing Service

If you use this method to provide the WSDL for the routing service, the existing WSDL must exist on the local file system. After you specify the file, Oracle JDeveloper ESB Designer parses it to determine the defined port types and presents them in a drop-down list from which you can make a selection.

To select an existing WSDL:

1. If you have not already done so, open the Create Routing Service dialog.

   In the Service Name field, enter a name for the routing service.

   The name must be unique within the scope of the project in which the routing service is being created. Spaces are not allowed.

2. For the System/Group field, click Browse to open the ESB Service Group Browser dialog, select the system (and service group, if desired) to which you want to add the routing service, and then click OK.

   Click Help for assistance in using the ESB Service Group Browser dialog.

3. In the Description field, enter a description for the routing service, if desired. This field is optional.

4. Choose Select Existing WSDL.

5. To complete WSDL File field, you can click on the following icons to the right of the WSDL File field:

   • Browse WSDL Files

     Click on this icon to launch the Open files dialog. In the Open dialog, navigate to an existing WSDL file, and then click Open to close the dialog. If you need assistance with this dialog, click Help.

   • 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 when done to close the dialog.

6. In the Port Type field, click the down arrow, and then select the port type for the routing service.

7. Click OK.

The routing service is created and an icon is added to the ESB project's Design tab.

6.9.2 How to Modify Routing Services

You can modify a routing service in Oracle JDeveloper ESB Designer.

To modify a routing service:

1. In the Design tab, double-click on the upper section of the routing service icon. The cursor is shaped like a hand on that region of the icon.

   Figure 6-7 is an example of a ESB Project Design tab with service icons.

   Figure 6-7 Design Tab - Service Icons

   
   Description of "Figure 6-7 Design Tab - Service Icons"
   
   

2. Update the properties of the routing service that can be modified. Note that the name of the service, WSDL file, and port type cannot be changed.

   You can also update the routing rules on this property page. See Section 6.10, "Specifying Routing Rules".

3. Save your changes.

6.9.3 How to Delete Routing Service

You can delete a routing service in Oracle JDeveloper ESB Designer.

To delete a routing service:

1. In the Design tab, select the routing service icon.

2. Click the large red X at the top of Design tab to delete the selected routing service.

3. Confirm that you want to delete the selected service.

4. Save your changes.

Note: Do not delete routing services in the Application Navigator.

6.9.4 What Happens When You Add Routing Services

When you complete the information for adding a new routing service, the routing 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 routing service entry in the Application Navigator includes the ESB system name, the routing service 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. Example 6-4 is a sample routing service WSDL file.

Example 6-4 Sample Routing Service WSDL File

<?xml version= '1.0' encoding= 'UTF-8' ?>
<definitions
     name="OrderFulfillment"
     targetNamespace="http://www.globalcompany.com/ns/Fulfillment"
     xmlns="http://schemas.xmlsoap.org/wsdl/"
     xmlns:tns="http://www.globalcompany.com/ns/Fulfillment"
     xmlns:inp1="http://www.globalcompany.com/ns/order">
    <types>
      <schema xmlns="http://www.w3.org/2001/XMLSchema" >
        <import namespace="http://www.globalcompany.com/ns/order" schemaLocation="OrderBookingPO.xsd" />
      </schema>
    </types>
    <message name="PurchaseOrder_request">
        <part name="PurchaseOrder" element="inp1:PurchaseOrder"/>
    </message>
    <portType name="execute_ppt">
        <operation name="execute">
            <input message="tns:PurchaseOrder_request"/>
        </operation>
    </portType>
</definitions>

When the ESB project is registered with the ESB server, the ESB files for the routing 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.9.5 What Happens at Runtime

During runtime, a routing service sends or receives a message instance to or from an adapter, routing, or SOAP service for processing. The routing rules determines the conditions of the routing and the data transformation XSL file maps the data from a source to a target.