Setting Web Service and JCA Adapter Endpoints Dynamically in Oracle SOA Suite

by Simone Geib

This installment of the SOA Suite Essentials for WLI Users series shows how adapter endpoints can be set dynamically in Oracle SOA Suite, and the similarities to the process in WebLogic Integration controls.

Published March 2010

Downloads for this article: Oracle SOA Suite

Introduction

Most business processes use some form of integration with external systems. These might be file systems, web services, message queues, databases or backend applications. In many cases, the endpoints for those systems (queue name, URL, file directory, etc.) will be different for development, testing, and production. In other cases the endpoints can change during the application's life cycle.

In these situations, a developer can change the endpoint property in question within the business process, and then recompile, redeploy, retest, and so on. This is obviously a time-consuming and error-prone process. A better strategy is to keep potentially changing endpoints dynamic.

Ideally, an administrator would set the endpoint property values in an administration console. The business process would then read and set values at run-time.

This article describes how dynamic endpoints can be handled in Oracle WebLogic Integration (WLI) and Oracle SOA Suite.

Dynamic Endpoints in WLI

Most controls in WLI allow the specification of dynamic properties, which are passed as an XML variable at run-time. These dynamic properties overwrite the properties that were defined for the control at design-time.

In order to set the dynamic properties, an XML variable has to be created that conforms to the control's dynamic-property schema and is used in thecontrol's setProperties() method. The current property settings can be retrieved using the getProperties() method.

Let's take the email control as an example. The setProperties() method of this control accepts an EmailControlPropertiesDocument parameter. The EmailControlPropertiesDocument type is an XML Beans class that is generated out of the corresponding schema element defined in DynamicProperties.xsd, which is located in the system folder of the Schemas project of the WLI application.

The following is an example of an XML variable used to set dynamic properties for an email control:

 <EmailControlProperties>
     <smtp-address>myorg.mymailserver.com:25</smtp-address>
     <from-name>Joe User</from-name>
     <from-address>joe.user@myorg.com</from-address>
     <reply-to-address>reply@myorg.com</reply-to-address>
     <reply-to-name>Joe User</reply-to-name>
</EmailControlProperties>

The control properties are often retrieved through an XML MetaData Cache control. (see XML MetaData Cache Control).

This control retrieves an XML document at run-time from the WLI cache that was created by an administrator through the WLI admin console. The content of the xml document can be changed at any time without affecting the deployed applications.

Dynamic Endpoints in SOA Suite

Message header properties can be configured for Web service binding components or JCA adapter binding components that are part of a deployed SOA composite application. Oracle JCA Adapters expose the properties specific to underlying back-end operations as header elements and allow the manipulation of these elements within a business process.

(See Using Header Properties for Oracle JCA Adapters)

Oracle JCA Adapters properties can also be added, deleted, or reverted from the Oracle Enterprise Manager Fusion Middleware Control Console (EM). The properties listed below are classified based on adapter behaviour when properties are added, deleted, or updated.

The InteractionSpec or ActivationSpec Properties

Properties in this group require the adapter endpoint to be recycled. The values of properties in this group can be changed from the EM console. However, property-dependency constraint validation requires that Oracle JDeveloper be used to make changes (adding or removing) to the composition of these properties.

(See The InteractionSpec or ActivationSpec Properties)

Endpoint Properties

The adapter is notified of changes to these properties without restarting the endpoint. Properties that belong to this group can be added or removed. The endpoint properties represent auxiliary tuning properties that an adapter might want to expose. The auxiliary tuning properties include various time intervals, thresholds, and other values. These endpoint properties are not exposed through the interactionspec or activationspec properties.

Configuring the End Point Properties for an Adapter

A number of BPEL activities, including invoke, receive, and reply and the onMessage branch of pick activities, provide a Properties tab. Header properties for JCA adapters can be set trough this tab.

In order to use this functionality, the property value is assigned to a string variable. This variable can then be used in the properties tab, as described in the use case sample below.

(See Introduction to BPEL Activities for a description of the properties tab in BPEL activities.)

The Domain Value Maps in SOA Suite are similar in concept to the XML Meta Data cache in WLI. Domain Value Maps can be used to retrieve information at run-time. The use of Domain Value Maps will be addressed in an upcoming article in this series.

Configuring message header properties for Web service binding components or JCA adapters through Enterprise Manager Oracle JCA Adapters and Web Services are either Service or Reference Binding Components within a SOA Suite composite application. Binding components are network protocols and services that connect the SOA platform with the outside world. Message header properties can be configured for Web service binding components or for JCA adapter binding components.

For more information about endpoint properties, see the chapter Configuring Service and Reference Binding Components in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite.

• Oracle AQ Adapter (see Oracle AQ Adapter Properties)
• Oracle Database Adapter (see Oracle Database Adapter Properties)
• Oracle File and FTP Adapter (see Oracle File and FTP Adapters Properties)
• Oracle JMS Adapter (see Oracle JMS Adapter Properties)
• Oracle MQ Series Adapter (see Oracle MQ Series Adapter Properties)
• Oracle Socket Adapter (see Oracle Socket Adapter Properties)

For more information about Oracle JCA Adapters properties, see Oracle JCA Adapter Properties.

To configure JCA adapter or Web Services properties, select the Properties tab of the adapter or web service in Enterprise Manager.

(See Configuring Service and Reference Binding Component Properties).

The following section explains this process in more detail.

Configuring the End Point Properties for an Adapter through Oracle Enterprise Manager

A variety of Oracle SOA Suite administration (configuration, monitoring, and management) tasks can be performed from the Enterprise Manager Console. One of these tasks is to configure the end point properties for a JCA adapter.

The properties of an adapter are usually defined in Oracle JDeveloper during design time. However, it is possible to edit or add predefined properties or to create or delete properties at a later stage.

Editing a Predefined Property for an Adapter

To edit a predefined property for an inbound adapter, navigate to the SOA composite application by using either of the following options:

1. Click Home.
   The SOA Infrastructure page is displayed.
   
2. Click the Deployed Composites tab.
   The list of deployed composite applications is displayed.
   
3. In the Composite section, click a specific SOA composite application.
   The SOA composite home page is displayed.
   
4. Click the inbound/outbound adapter (service/reference) from the Services and References section in the right panel.
   The Service Home page is displayed.

1. Under soa-infra, click a specific SOA composite application.
   The SOA Composite home page is displayed.
   
2. Click the inbound/outbound adapter (service/reference) from the Services and References section in the right panel.
   The Service Home page is displayed.

Edit a predefined property

1. Click Properties to see a list of the currently defined binding properties.
   
2. Select the property to be edited.
   
3. Edit the value in the Value text box.
   
4. Click Save.

Adding Predefined Properties for an Adapter

To add a predefined property for an adapter:

1. Navigate to the SOA composite application as described above.
   
2. Add a predefined property:
   1. Click the Properties tab to see a list of the currently defined binding properties.
   2. Click the Add button. A new empty row is appended to the existing list of properties.
   3. Click the Select Values icon in the Name field of the new row.
      The Properties dialog is displayed.
   4. Select a property that is valid for the particular adapter from the list of properties, and then click OK.
   5. Click Save.

Creating a New Property for an Adapter

To create a new property for an inbound adapter:

1. Navigate to the SOA composite application as described above
   
2. Create a new property:
   1. Click the Properties tab to see the list of the currently defined binding properties.
      
   2. Click the Add button.
      A new empty row is appended to the existing list of properties.
   3. Specify the property name and value in the Name and the Value fields of the new row.
      
   4. Click Save.

Deleting a Property for an Adapter

To delete a property for an inbound adapter:

1. Navigate to the SOA composite application as described above
   
2. Delete a property:
   1. Click the Properties tab to see a list of the currently defined binding properties.
   2. Select the property you want to delete, and then click Delete.
      A message asking you to confirm your action is displayed.
   3. Click OK to confirm.
   4. Click Save.

Reverting a Property Value for an Adapter

You can revert only those properties that you have changed. Also note that you can perform the revert operation only on the existing property values and not on those that were added from the predefined list of properties or those that you created.

To revert a property value for an inbound adapter:

1. Navigate to the SOA composite application as described above.
   
2. Revert a property value for an inbound adapter:
   1. Click the Properties tab to see a list of the currently defined binding properties.
      
   2. Select the property you want to revert, and then click Revert.
      A message asking you to confirm your action is displayed.
   3. Click OK to confirm.
   4. Click Save.

For more information, please see Configuring the End Point Properties for an Inbound Adapter and Configuring the End Point Properties for an Outbound Adapter.

Use Case Example: Change the file name and directory before writing a file

This example will demonstrate how the endpoints (file name and directory) for a file control (in WLI) and a file adapter (in SOA Suite) can be changed dynamically. In order to keep it simple and to the point, we will create a process that does nothing but write a message to a file. A real-world use case would be much more complicated.

Implementing the use case in WLI

The WLI use case is not described in great detail as it is assumed that the audience knows how to implement a dynamic file control in WLI. The focus area is the implementation of the use case in SOA Suite.

A file control is used to write a file to a local directory. As with many other controls, the file control also provides dynamic properties to dynamically set endpoints:

<?xml version= '1.0' encoding= 'UTF-8' ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" 
targetNamespace="http://demo/demoCustomer1"
     xmlns:cu="http://demo/demoCustomer1">
    <xs:element name="customer">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="cu:key"/>
                <xs:element ref="cu:firstname"/>
                <xs:element ref="cu:lastname"/>
                <xs:element ref="cu:address"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="key" type="xs:string"/>
    <xs:element name="firstname" type="xs:string"/>
    <xs:element name="lastname" type="xs:string"/>
    <xs:element name="address" type="xs:string"/>
</xs:schema>

In our sample, the WLI process is started by a Client Request Node which expects a customer XML document as input. An XML MetaData Cache control is used to read the file directory and file name values. A transformation control is used to create the properties for the file control. And finally, the properties are set through the the file control's setProperties() method. The file control's write method is then used to write the customer message to the file.

While some of the steps in this process could be consolidated, they are shown as single steps in order to simplify the sample.

The JPD is illustrated in Figure 1.

Figure 1: JPD

Implementing the use case in SOA Suite

This section will describe the same use case, as implemented in SOA Suite.

In this use case, a business process is started via a web service call with a customer xml message. The business process uses a file adapter to write the customer information to a file.

The following section will describe how the process is deployed and tested, and then demonstrate how the adapter endpoint properties can be changed by using the adapter header properties within the process, or through the Enterprise Manager console.

Create a SOA Application and Project

To get started:

1. Create a new SOA Application in JDeveloper.

2. Name it SOASuiteWLIEssentials

3. Create a new Project named DynamicEndpoints.

4. Click Finish

Create the BPEL Process

1. In the composite, drag-and-drop a BPEL Process component onto the Components swim lane.

2. In the Create BPEL Process dialog, specify the following settings:
   1. Name: WriteCustomer
   2. Template: One Way BPEL Process
   3. Service Name: writecustomer_client
   4. Expose as a SOAP Service: Checked
   5. Input:
      1. Click the flashlight icon to open Type Chooser window.
      2. Click the Import Schema File icon.

3. Choose the customer XML schema from your local disk.
4. Check Copy to Project

5. Click OK
6. Click OK
7. Choose the root element of your schema

8. Click OK

9. Click OK
10. The WSDL for this service is created automatically using this information. Note that the input type specified here goes in to the WSDL for this service.

Adding a File Adapter

1. Drag-and-drop a File Adapter to the External References swim lane. This file adapter will write each customer to a text file.

2. Name the service WriteCustomerData

3. Click Next.
   
4. Select the option to Define from operation and schema.
   
   This feature allows you to use the file operation and schema to define the WSDL automatically.

5. Click Next.
6. Select the Write File operation

7. Click Next.
8. Specify the following settings, leaving all others with their default values:
   1. Directory for Outgoing Files: c:\temp
   2. File Naming Convention: customer_%SEQ%.xml to write the files with increasing sequence numbering. You can see additional options for numbering files in a drop down menu as soon as you enter % in the field

9. Click Next.
10. Browse for the schema that represents the content we will write (customer.xsd)

11. Choose the root element

12. Click OK.

13. Click Next, then Finish to complete the File Adapter wizard and return to the composite.

Wire the BPEL Process and the File Adapter

Next, wire the BPEL process and the file adapter and complete the interface definitions.

The wired components resemble the image below:

Wiring the components in the composite automatically creates a partner link reference inside the BPEL process.

Designing the BPEL Process

1. Double-click the BPEL component to open the BPEL editor.
   
   Notice the WriteCustomerData partnerlink already in the References swim lane because you wired it in the composite. The editors keep the references in sync between the BPEL process and the composite.
2. Drag-and-drop an Invoke activity from the Component Palette to an insertion point under the receiveInput activity.

3. Drag the wire from the Invoke activity to the WriteCustomerData partner link. This tells the BPEL process to invoke the file adapter.

4. In the Edit Invoke dialog, specify the following:
   1. Name: WriteCustomerData
   2. Input Variable: Click the green plus icon and then click OK to create a new global variable, accepting the default name and type.
      
      The variable designated for the input will contain the data that will be sent to the service when it is invoked. It is automatically created with the correct type expected by the service.

5. Click OK.

6. click OK.

Your BPEL process should now resemble the image below:

We've created the variables that will be used when interacting with the WriteCustomerData service, but they haven't been populated. Let's populate the input variable first.

In BPEL, Assign activities are used to assign data to variables. In this case you want to assign the customer information to the WriteCustomerData service.

1. Drag-and-drop an Assign activity above your Invoke activity.

2. Double-click the Assign activity to edit it.
3. Click the General tab and change the name to assignCustomerData

4. Click the Copy Operation tab
5. Click the green plus icon and select Copy Operation to open the Create Copy Operation dialog.

6. Specify the following: In the From side, select Variables > Process > Variables > inputVariable >payload > ns2:customer
7. In the To side, select Variables > Process > Variables >WriteCustomerData_Write_InputVariable > body > ns2:customer

8. Click OK.

The Assign dialog should now resemble the image below:

9. Click OK to return to the BPEL process.
10. Click the green check button in the upper left of the BPEL process to validate the process.

All the warnings should go away. The process should resemble the image below:

The input variable to WriteCustomerData is now populated.

11. Save the BPEL process.

Deploying the SOA Composite

Before the BPEL process can be tested, the composite has to be deployed with Oracle JDeveloper.

Before you start the deployment, please make sure that your SOA Server is running.

Please check Deploying SOA Composite Applications to learn how to deploy SOA composite applications with Oracle JDeveloper and scripting tools and create configuration plans that enable you to move SOA composite applications to and from development, test, and production environments.

Please check Deploying SOA Composite Applications to learn how to deploy, redeploy, and undeploy a SOA composite application from Oracle Enterprise Manager Fusion Middleware Control Console (EM).

When deploying the composite from within JDeveloper, the log should look similar to the example below:

[07:32:39 PM] ----  Deployment started.  ----
[07:32:39 PM] Target platform is  (Weblogic 10.3).
[07:32:39 PM] Running dependency analysis...
[07:32:39 PM] Building...
[07:33:06 PM] Deploying profile...
[07:33:06 PM] Updating revision id for the SOA Project
'DynamicEndpoints.jpr' to '1.0'..
[07:33:06 PM] Wrote Archive Module to D:\1WLI\2SOASuiteMigration\testProjects\JDev\11gPS1\
SOASuiteWLIEssentials\DynamicEndpoints\deploy\sca_DynamicEndpoints_rev1.0.jar
[07:33:06 PM] Deploying sca_DynamicEndpoints_rev1.0.jar to AdminServer [SGEIB01.emea.bea.
com:7001] 
[07:33:06 PM] Processing sar=/D:/1WLI/2SOASuiteMigration/testProjects/JDev/11gPS1/SOASuiteWLIE
ssentials/DynamicEndpoints/deploy/sca_DynamicEndpoints_rev1.0.jar
[07:33:06 PM] Adding sar file - D:\1WLI\2SOASuiteMigration\testProjects\JDev\11gPS1\SOASuite
WLIEssentials\DynamicEndpoints\deploy\sca_DynamicEndpoints_rev1.0.jar
[07:33:06 PM] Preparing to send HTTP request for deployment
[07:33:07 PM] Creating HTTP connection to host:SGEIB01.emea.bea.com, 
port:7001
[07:33:08 PM] Sending internal deployment descriptor
[07:33:08 PM] Sending archive - sca_DynamicEndpoints_rev1.0.jar
[07:33:28 PM] Received HTTP response from the server, response code=200
[07:33:28 PM] Successfully deployed archive sca_DynamicEndpoints_rev1.0.jar to AdminServer
 [SGEIB01.emea.bea.com:7001] 
[07:33:28 PM] Elapsed time for deployment:  48 seconds
[07:33:28 PM] ----  Deployment finished.  ----

Testing the BPEL Process

After successful deployment, you can initiate the composite service through Oracle Enterprise Manager Fusion Middleware Control Console (EM).

1. To log in to Enterprise Manager, use Internet Explorer 7, Mozilla Firefox 2.0.0.2, or Firefox 3.0.x to access the following URL: http://host_name:port/em, where host_name is the name of the host on which Enterprise is installed and port is the port number of your admin server.
   
2. Enter weblogic/password and click Login.
   
   (See Getting Started with Administering Oracle SOA Suite for more information.)

3. Go to SOA - soa_infra, then locate and click DynamicEndpoints composite on the EM dashboard to access the composite homepage

4. Once on the page, you can test a composite service by clicking on the Test button...

5. Filling out the payload...

6. And clicking on the button Test Web Service.

If all goes as planned, a new file customer_1.xml will be created in C:\temp.

Change the File Adapter End point at Run-time Through the Properties Tab of the Invoke Activity

This sample will show how the adapter end-point can be changed at run-time. It's very similar to the WLI use case where the information is retrieved through an XML Meta Data Cache control and set as properties to the control.

As mentioned above, a Domain Value Map would be used to retrieve the values for the adapter properties. In order to keep this article simple, the sample BPEL process will use hard coded values for those properties and the use of Domain Value Pairs will be explained separately

Create variables for the properties

1. If the Structure window (by default on the top left of JDeveloper) is not visible, go to View - Structure.
   
2. In the Structure window click on Variables - Process - Variables and click the green plus sign:
   

3. In the Create Variable window, define:
   1. Name: outputFolder
   2. Simple Type: click on the type chooser icon to select the type of the variable

3. Choose string

4. Click OK

5. Click OK

6. Repeat the process for a second string variable fileName

Assign values to the variables

This is where the Domain Value Maps would be used in a real-life use case. However, for this examples we'll use hard coded values.

1. Add an assign activity to the BPEL process, between assignCustomerData and WriteCustomerData with Name: setProperties.
   
2. In the Copy Operation tab, add two copy operations:
   1. Click on the green plus sign and choose Copy Operation.

2. On the left side, choose Expression.
3. Enter a new output file directory, e.g. " C:\files\output".
4. Choose the variable outputFolder on the right side.

5. Click OK

Repeat these steps to set a new output file name to the variable filename.

The assign activity should now resemble the image below:

6. Click OK.

Set the properties for the file adapter

1. Open the invoke activity WriteCustomerData
   
2. Go to the Properties tab
   1. Scroll down to jca.file.Directory
   2. Click the browse button in the Value field

3. Browse variables

4. Choose variable outputFolder

5. Click OK.
6. Click OK.

7. Scroll to jca.file.FileName
8. Choose variable fileName

9. Click OK

The BPEL process should now resemble the image below:

Re-deploy the composite and test the BPEL process again. There should now be a file with the new name in your newly chosen directory

Change the File Adapter end point in Enterprise Manager

Instead of setting the properties dynamically in the BPEL process, you can also make changes to the JCA adapter and web services properties in Enterprise Manager.

1. Click on the DynamicEndpoints composite and scroll down to Services and References.

2. Click on WriteCustomerData (the file adapter)

3. Click on the Properties tab and change the PhysicalDirectory and FileNameConvention. Make sure the output directory exists.

1. Click Apply, then Yes, then OK.

Re-deploy the composite and test the BPEL process again. There should now be a file with the new name in your newly chosen directory.

Key Takeaways and Recommendations

Oracle SOA Suite provides two different ways to configure JCA adapter and Web Services endpoints dynamically: set header properties in a BPEL process, similar to how it's done in WLI, or change header properties in Enterprise Manager console.

Simone Geib is Product Manager for SOA technologies at Oracle Corporation. She joined Oracle through the BEA Systems acquisition, where she was Product Manager for WebLogic Integration. Simone has extensive experience of SOA strategy and implementation across a wide range of industries and geographies. [ Oracle Mix / Blog / LinkedIn]