| SOA Suite Essentials for WLI Users
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
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>firstname.lastname@example.org</from-address> <reply-to-address>email@example.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.
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.
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.(See Endpoint 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.(See Understanding 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.The following adapters support header 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.
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:From the SOA Infrastructure Menu:
Edit a predefined property
Adding Predefined Properties for an Adapter
To add a predefined property for an adapter:
Creating a New Property for an Adapter
To create a new property for an inbound adapter:
Deleting a Property for an Adapter
To delete a property for an inbound adapter:
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:
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:
Create the BPEL Process
Adding a File Adapter
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
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.
The Assign dialog should now resemble the image below:
All the warnings should go away. The process should resemble the image below:
The input variable to WriteCustomerData is now populated.
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).
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
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.
Repeat these steps to set a new output file name to the variable filename.
The assign activity should now resemble the image below:
Set the properties for the file adapter
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.
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.