Meta Data Cache Control in Oracle WebLogic Integration and Domain Value Maps in SOA Suite
Introduction
Many common integration use cases include the lookup of dynamic data at run-time from within a business process. Examples for this include address data, an endpoint for an adapter (for example, the URL for a web service or the location of a file), or the mapping from the vocabulary in one domain to another vocabulary in a different domain.These data share a common trait: they can change at any time and must not be tied directly to the business process. In an ideal scenario, an administrator can update the information in a console in real-time without having to change any code and re-compile or re-deploy the application. This scenario also offers improved performance and the availability of the data across a cluster.
The retrieval of dynamic data is achieved in Oracle WebLogic Integration (WLI) through an XML MetaData Cache Control, which works on a key-value pair, where the key is a string and the value is an XML document. The value is set by an administrator in the WLI admin console and retrieved at run-time within a business process.
The same can be achieved in Oracle SOA Suite with Domain Value Maps (DVM) where dynamic data retrieval is only one possible use case, but the one that is of specific interest for WLI users.
This article introduces both concepts, and describes the use of Domain Value Maps in SOA Suite 11g in detail.
In order to make this article less theoretical, a sample is used to illustrate the usage of Domain Value Maps from within a BPEL process. This sample explains step-by-step how to look up a file name and location at run-time before a message is written to a file.
The use case builds on a sample that was explained in Setting Web Service and JCA Adapter Endpoints Dynamically in Oracle SOA Suite, another article in the SOA Suite Essentials for WLI Users series. It is highly recommended to work through that article first before going through this use case.
XML MetaData Cache Control in WLI
The WLI XML MetaData Cache Control is used for fast access to a managed set of key-value pairs. The key is of type string and the value contains XML data.These key-value pairs can be retrieved within a business process from the XML MetaData Cache through the get method of the control, where the key is the input parameter and the value (the XML message) is the return parameter. The corresponding entries can then be extracted from the XML message and used to set dynamic control properties (or other dynamic data).
An administrator manages the entries in the cache ( add, delete, update) through the WLI Administration Console without touching the process.
The XML MetaData Cache is a global, domain-wide cache. Data from the cache is made available on a permanent basis throughout a cluster through file-based storage.
For more information on the WLI XML MetaData Cache, please see XML MetaData Cache Control and XML Cache in Using the WebLogic Integration Administration Console.
Domain Value Maps (DVM) in SOA Suite
The original intent of Domain Value Maps (DVM) in SOA Suite was to map from one vocabulary, used in a given domain, to another vocabulary used in a different domain. For example, one domain might use a long name to represent a city (Boston) while another domain may use a short name to represent the same city (BO). In such cases, you can directly map the values by using DVMs. A direct mapping of values between two or more domains is known as point-to-point mapping.Each DVM typically holds a specific category of mappings among multiple applications. For example, one DVM might hold mappings for city codes and another might hold mappings for state codes.
Qualifiers are supported in addition to direct mapping. A mapping may not be valid unless qualified with additional information. For example, a DVM containing city code to city name mapping may have multiple mappings from KN to Kensington because Kensington is a city in Canada as well as in the USA. So, this mapping requires a qualifier ( USA or Canada) for validation.
Multiple qualifiers can also be specified. Qualifiers are used only to qualify the mappings and cannot be looked up.
A qualifier order is used to find the best match during lookup at runtime. The order of a qualifier varies from highest to lowest depending on the role of the qualifier in defining a more exact match. A state qualifier, for example, can have a higher order than a country qualifier, as a matching state indicates a more exact match.
DVMs support hierarchical lookup. If a qualifier value is specified during a lookup and no exact match is found, the lookup mechanism tries to find a more generalized match by setting the higher order qualifiers to a "". It proceeds until a match is found, or until a match is not found with all qualifiers set to a "".
One value in a DVM can also be mapped to multiple values ( One-to-Many Mapping Support). For example, a domain value map for Payment Terms can contain mapping of payment terms to three values, such as discount percentage, discount period, and total payment period.
In addition to this vocabulary mapping, Domain Value Maps can also be used to look up data at run-time, for example dynamic properties for a J2EE Connector Architecture (JCA) Adapter.
This lookup can be used within a BPEL process or a Mediator component for example before calling an adapter service.
For additional information on DVMs, please see Working with Domain Value Maps and Editing a Domain Value Map.
JDeveloper and SOA Composer
DVMs can be created and edited in Oracle JDeveloper. For more details on this please see Creating Domain Value Maps, Editing a Domain Value Map, Creating a Domain Value Map Use Case for Hierarchical Lookup and Creating a Domain Value Map Use Case For Multiple Values.By using JDeveloper, the application has to be recompiled and redeployed every time a change is made to the values in the DVM. In order to avoid this, the SOA Composer offers support for editing DVMs at runtime (starting from SOA Suite 11gR1 PS1).
DVM Metadata can either be associated with one SOA composite, or it can be shared across different composites.
The SOA Composer is an EAR file which is installed as part of SOA installation. It offers complete functionality to manage DVMs at runtime. You can view and edit a DVM in the Composer after it has been created in JDeveloper. The second part of the SOA Suite use case sample below will explain step-by-step how this is done.
For more information, please see Using SOA Composer with Domain Value Maps.
Use Case Example
The following sections will describe how dynamic properties (file name and output directory) are retrieved at run-time in a business process using the XML Meta DataCache Control for a file control in WLI, and using Domain Value Maps for a File Adapter in SOA Suite, .As mentioned, this can also be done in a Mediator component. But a BPEL process was chosen here to show the similarities to a business process in WLI.
As always, it is assumed that readers are familiar with the WLI concepts, so the WLI use case will not be described in much detail. The focus will be on the implementation in SOA Suite, which will be explained step-by-step.
Please make sure you are familiar with the article Setting Web Service and JCA Adapter Endpoints Dynamically in Oracle SOA Suite, as this sample builds on the one that was implemented in that article.
Implementing the Use Case in WLI
As explained in Setting Web Service and JCA Adapter Endpoints Dynamically in Oracle SOA Suite, a file control is used to write a file to a local directory.The WLI process is started by a Client Request Node which expects a customer XML document as input. An XML MetaData Cache control ( get file properties in Figure 1) 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 file control's setProperties() method. The file control's write method is then used to write the customer message to the file.
<?xml version= '1.0' encoding= 'UTF-8' ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified" targetNamespace="http://demo/fileInfo"
xmlns:fi="http://demo/fileInfo">
<xs:element name="fileInfo">
<xs:complexType>
<xs:sequence>
<xs:element ref="fi:fileDirectory"/>
<xs:element ref="fi:fileName"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="fileName" type="xs:string"/>
<xs:element name="fileDirectory" type="xs:string"/>
</xs:schema>
The xml document used in the sample defines the file name and output directory for the file:
<fi:fileInfoxmlns:dem="http://demo/Address">
<fi:fileDirectory>C:/files/output</fi:fileDirectory>
<fi:fileName>customerTest.xml</fi:fileName>
</fi:fileInfo>
The process receives a customer document which includes an element key as part of the message:
<?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>
This element is extracted from the message and used as input to the XML MetaDataCache control.
Implementing the Use Case in SOA Suite
Domain Value Maps can be created in a SOA Composite application of Oracle JDeveloper and used to look up dynamic data at run-time.To create the SOA Application, Project, composite, BPEL process and file adapter for this use case sample, please follow the steps in the "Implementing the use case in SOA Suite" section of the article Setting Web Service and JCA Adapter Endpoints Dynamically in Oracle SOA Suite, including the section "Change the File Adapter end point at run-time through the Properties tab of the Invoke activity".
Create a new Domain Value Map (DVM) in JDeveloper
The DVM is created in JDeveloper initially. It can then be changed at any time in SOA Composer.The values in the DVM will be the property values for the output directory and file name for a given customer. In order to identify the right values, we will use the key element in the customer schema.
We will only create one set of values for the sample, but you can have any number of rows in the DVM with different key values.
In the Application Navigator, right-click the DynamicEndpoints project and select New.
The Create Domain Value Map(DVM) File dialog is displayed.
- In the File Name field, enter the name of the domain value map file: fileProperties.dvm
- In the Description field, enter a description for the domain value map
- Enter:
- Key for the first Domain Name
- 1 for the first Domain Value
- FileDirectory for the second Domain Name
- C:\files\output or another output directory for the first Domain Value. Please make sure the chosen directory exists
The Domain Value Map(DVM) Editor is displayed:
All we need to do is add a column for " FileName".
Click on the green "+" to add a new Domain
This concludes the creation of the initial DVM.
Assign the values from the DVM to the property values
Open the WriteCustomer BPEL process that was created in a previous step. This BPEL process includes an assign activity which hard codes the file adapter properties to the string variables outputFolder and fileName.Instead of the two existing copy operations, we will create new operations that lookup the values using the previously created DVM and assign it to the property variable.
Open the assign activity assignProperties.
Create a new copy operation.
Please note that the usage and syntax of the function is described in the Description window.
- The first parameter is the DVM file, enter " fileProperties.dvm"
- The second parameter is the name of the source column, please enter " Key"
- The third parameter is the name of the source value, which is the key value in our sample. We get the value of this parameter from the element key in the customer variable (which is the input variable).
- In the BPEL Variables window, please expand the variable inputVariable and choose the element key.
- Click the Insert Into Expression button
- The last parameter is the target column name, " FileDirectory" in our case.
The DVM function now looks like this:
dvm:lookupValue1M("fileProperties.dvm", "Key",
bpws:getVariableData('inputVariable','payload','/ns2:customer/ns2:key
'), "FileDirectory")
Choose the property variable outputFolder on the right hand side.
If you see an error regarding the DVM function, it should go away once you click OK.
Repeat these steps to assign a value to the variable fileName
The DVM function looks like this:
dvm:lookupValue1M("fileProperties.dvm", "Key",
bpws:getVariableData('inputVariable','payload','/ns2:customer/ns2:key
'), "FileName")
That's all you have to do to create the DVM lookup.
The BPEL process looks like this:
Check if the output directory and file name are the ones you defined in the DVM and not the ones originally defined in the file adapter.
Change the Domain Value Map at runtime.
You might have to target the SOA Composer first as it is not targeted in development environments by default.To check if you can use the Composer, please log into Enterprise Manager (EM) at http://host_name:port/em where host_name is the name of the host on which Enterprise Manager is installed and port is the port number of your admin server. Enter weblogic/ password and click Login.
Open the Application Deployments under Farm_soaDomain.
If you don't see composer (serverName) as a deployed component, please follow the steps in the next section. If you can see it, please skip the next section.
Target SOA Composer in WebLogic Server administration console
Log into WLS console at http://host_name:port/console where host_name is the name of the host and port is the port number of your admin server.The console application is deployed on first access, which might take a few minutes.
Click on Deployments in the Domain Structure on the left hand side.
Check the box left of composer and hit the Change Targets button.
Check the box in front of composer and click Start - Servicing all requests.
View the previously created DVM in SOA Composer
Log into SOA Composer at http://host_name:port/soa/composer where host_name is the name of the host and port is the port number of your admin server.If there is a problem opening the Composer, make sure it's properly deployed and targeted (see previous step).
Select Open DVM from the Open menu.
The selected DVM opens in view mode.
Edit the DVM in SOA Composer
By default, DVMs open in the view mode. For editing a DVM, you need to change the mode to edit session by clicking the Edit menu item.
- Add rows
- Edit rows
- Delete rows
Add a new row to the DVM
Click Add Domain Values.
The entered values are added to the DVM.
Edit a row in the DVM
Select the row that you want to edit.Click Edit Domain Values.
Save the DVM
Every time a DVM is opened in edit session, a sandbox is created per DVM, per user. If you save your changes, the changes are saved in your sandbox. For saving the changes, you must click the Save menu item.
Committing Changes at Runtime
You must commit the changes in order to save them permanently. Once you commit the changes, runtime picks up the changes and saves them in the MDS repository. In a session, you can save your changes without committing them too. In such a case, the DVM remains in the Saved state. You can reopen the DVM and commit the changes later.Click the Commit menu option.
After you've saved your changes, test the BPEL process again to make sure the changed values are used.
Delete a row in DVM
Select the rows that you want to delete and click Delete Domain Values.
Conflict Detection
SOA Composer detects the conflicts that can occur among concurrent users. You will see a warning if you open a DVM that is being edited by another user.However, if you still want to edit the DVM, click Yes and make the modifications.
If the other user makes changes to the DVM and commits the changes, you will see a warning if you attempt to commit your changes:
Key Takeaways and Recommendations
The sample above illustrates how Domain Value Maps can be used within a BPEL process or Mediator to look up dynamic data at run-time and how the data can easily be changed by an administrator without the need to move through the complete, rigorous IT re-deployment process.Although this was not originally the intended use-case for DVM, it provides a compelling and complete solution to the challenge of migrating dynamic WLI behaviour.
Domain Value Maps are simple to setup in JDeveloper initially and to manage in production using Composer. Furthermore, the administrator has simple production tooling for dynamically changing application behaviour without the need for knowledge of XML.
Key Takeaways:
- SOA Suite provides complete and integrated support for all WLI use cases and techniques
- SOA Suite provides a mechanism for achieving dynamic lookup for applications that is analogous to that provided in WLI
- Qualifiers enhance the power of dynamic lookup of runtime values
- DVM integration reduces code complexity by enabling cleaner process models
- SOA Composer enables lower operation cost allowing operations to focus on what to change, not on how to change XML
- SOA Suite and DVM enable systematic reuse of dynamic data across applications with DVM in SOA Suite composites (including mediator and BPEL PM).
No comments:
Post a Comment