Working with Domain Value Maps

44 Working with Domain Value Maps

This chapter describes how to create and use domain value maps to map the terms used by different domains to describe the same entity, allowing you to map values used by one domain for specific fields to the values used by other domains for the same fields. This chapter also describes the XPath functions used for domain value lookups.

This chapter includes the following sections:

44.1 Introduction to Domain Value Maps

When information is transmitted between different domains, each domain might use different terminology or processing codes to describe the same entity. For example, one domain might use complete city names in its messages (Boston), while another domain uses a code to indicate the city (BO). Rather than requiring each domain to standardize their data to one set of terminology, you can use domain value maps to map the terms used in one domain to the terms used in other domains. Domain value maps operate on the actual data values in the messages that are transmitted through an application at runtime.

While each domain value map typically defines the mapping for only one field or category, a single SOA composite can require mappings for multiple categories. Thus, one SOA composite might contain several domain value maps. For example, you might have one domain value map that defines city name mapping, one that defines state name mapping, and one that defines country name mapping.

A direct mapping of values between two or more domains is known as point-to-point mapping. Table 44-1 shows a point-to-point mapping for cities between two domains:

Table 44-1 Point-to-Point Mapping

CityCode	CityName
`BELG_MN_STLouis`	`BelgradeStLouis`
`BELG_NC`	`BelgradeNorthCarolina`
`BO`	`Boston`
`NP`	`Northport`
`KN_USA`	`KensingtonUSA`
`KN_CAN`	`KensingtonCanada`

Domain value map values are static. You specify the domain value map values at design time using Oracle JDeveloper, and then at runtime the application performs a lookup for the values in the domain value maps. For information about editing domain value maps at runtime with Oracle SOA Composer, see Using Oracle SOA Composer with Domain Value Maps.

Note:

To dynamically integrate values between applications, you can use the cross referencing feature of Oracle SOA Suite. For information about cross references, see Working with Cross References.

44.1.1 Domain Value Map Features

Oracle SOA Suite domain value maps let you further refine the performance and results of the domain value map lookups that are performed at runtime. For example, you can specify qualifying information that provides additional information to assist with mapping. Domain value maps also support one-to-many mappings.

44.1.1.1 Qualifier Domains

Qualifier domains contain information solely to clarify the mapping. A mapping might be ambiguous unless this additional information is defined. For example, a domain value map that defines a city name mapping could have multiple mappings from KN to Kensington because Kensington is a city in both Canada and the USA. Therefore, this mapping requires a qualifier (USA or Canada) to indicate which mapping to use. An example of this is shown in Table 44-2.

Table 44-2 Qualifier Support Example

Country (Qualifier)	CityCode	CityName
`USA`	`BO`	`Boston`
`USA`	`BELG_NC`	`Belgrade`
`USA`	`BELG_MN_Streams`	`Belgrade`
`USA`	`NP`	`Northport`
`USA`	`KN`	`Kensington`
`Canada`	`KN`	`Kensington`

A domain value map can contain multiple qualifier domains. For example, as shown in Table 44-3, the mappings are also qualified with a state name.

Table 44-3 Multiple Qualifier Support Example

Country (Qualifier)	State (Qualifier)	CityCode	CityName
`USA`	`Massachusetts`	`BO`	`Boston`
`USA`	`North` `Carolina`	`BELG`	`Belgrade`
`USA`	`Minnesota`	`BELG`	`Belgrade`
`USA`	`Alabama`	`NP`	`Northport`
`USA`	`Kansas`	`KN`	`Kensington`
`Canada`	`Prince` `Edward` `Island`	`KN`	`Kensington`

Qualifiers are used only to qualify the mappings. Therefore, the qualifier values cannot be looked up.

44.1.1.2 Qualifier Hierarchies

When there are multiple qualifier domains, you can specify a qualifier order to indicate how they are used during runtime lookups. The order of a qualifier varies from highest to lowest depending on the role of the qualifier in defining a more exact match. In Table 44-3, the state qualifier is probably given a higher order than the country qualifier because a matching state indicates a more precise match.

Domain value maps support hierarchical lookup. If you specify a qualifier value during a lookup and no exact match is found, then the lookup mechanism tries to find a more generalized match by setting the higher order qualifiers to empty quotes (""). It proceeds until a match is found, or until a the lookup is exhausted and no match is found. Figure 44-1 describes the steps of a hierarchical lookup performed for the following lookup (based on the values in Table 44-3):

State=Arkansas, Country=Canada, CityCode=KN_USA

In this example, the State qualifier has a qualifier order of 1 and the Country qualifier has a qualifier order of 2. As shown in Figure 44-1, the lookup mechanism sets the higher order qualifier State to the exact lookup value Arkansas and uses Canada|"" for the lower order qualifier Country.

Figure 44-1 Hierarchical Lookup Example

Description of "Figure 44-1 Hierarchical Lookup Example"

If no match is found, the lookup mechanism sets the higher order qualifier State to a value of "" and sets the next higher qualifier Country to an exact value of Canada. If no match is found, the lookup mechanism sets the value of the previous higher order qualifier Country to a value of "". One matching row is found where CityCode is KN_USA and Kensington is returned as a value.

Table 44-4 provides a summary of these steps.

Table 44-4 Domain Value Map Lookup Result

State	Country	Short Value	Lookup Result
`Arkansas`	`CANADA\|" "`	`KN_USA`	`No` `Match`
`" "`	`CANADA`	`KN_USA`	`No` `Match`
`" "`	`" "`	`KN_USA`	`Kensington`

44.1.1.3 One-to-Many Mappings

One value can be mapped to multiple values in a domain value map. For example, a domain value map for payment terms can contain a mapping of payment terms to multiple values, such as discount percentage, discount period, and net credit period, as shown in Table 44-5.

Table 44-5 One-to-Many Mapping Support

Payment Term	Discount Percentage	Discount Period	Net Credit Period
GoldCustomerPaymentTerm	`10`	`20`	`30`
SilverCustomerPaymentTerm	`5`	`20`	`30`
RegularPaymentTerm	`2`	`20`	`30`

44.2 Creating Domain Value Maps

You can create one or more domain value maps in a SOA composite application in Oracle JDeveloper, and then use the maps to look up the mapped values at runtime. Creating a domain value map creates a file with a .dvm extension in the application file structure.

44.2.1 How to Create Domain Value Maps

Create and configure domain value maps using the Create Domain Value Map(DVM) File dialog in Oracle JDeveloper. This dialog lets you define two domains, each with one value. Upon completion, the Domain Value Map Editor appears so you can define additional domains and corresponding values.

To create a domain value map:

In the Applications window, right-click the project in which you want to create a domain value map and select New.

The New Gallery dialog appears.
Expand the SOA Tier node, and then select the Transformations category.
In the Items list, select Domain Value Map(DVM) and click OK.

The Create Domain Value Map(DVM) File dialog appears.
In the File Name field, enter a unique and descriptive name for the domain value map file. The file name must have an extension of .dvm.
In the Description field, enter a description for the domain value map. This field is optional.
In the Domain Name field, enter a name for each domain. These names are the column names for the domain value map, and each represents a fields in a different domain.

Note:

Domain names must be of the type NCName (non-colonized name), which is a valid XML element name with no colons. Each domain name must be unique in a domain value map. You can add more domains later.
In the Domain Value field, enter a value corresponding to each domain. For example, enter BO for a CityCode domain and Boston for a CityName domain, as shown in Figure 44-2.

Figure 44-2 Populated Create Domain Value Map File Dialog

Description of "Figure 44-2 Populated Create Domain Value Map File Dialog"
Click OK.

The Domain Value Map Editor appears with the new domain value map displayed.

44.2.2 What Happens When You Create a Domain Value Map

A file with the extension .dvm is created in the project file structure and appears in the Applications window, as shown in Figure 44-3.

Figure 44-3 A Domain Value Map File in Applications Window

Description of "Figure 44-3 A Domain Value Map File in Applications Window"

All .dvm files are based on the schema definition (XSD) file shown in the following example:

<?xml version="1.0" encoding="UTF-8" ?>
<!-- Copyright (c) 2006, Oracle. All rights reserved.  -->
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  targetNamespace="http://xmlns.oracle.com/dvm"
                  xmlns:tns="http://xmlns.oracle.com/dvm"
                  elementFormDefault="qualified"
                  attributeFormDefault="unqualified">

<xsd:element name="dvm">
    <xsd:annotation>
      <xsd:documentation>The Top Level Element
      </xsd:documentation>
    </xsd:annotation>
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="description" minOccurs="0" type="xsd:string">
          <xsd:annotation>
            <xsd:documentation>The DVM Description.  This is optional
            </xsd:documentation>
          </xsd:annotation>
        </xsd:element>
        <xsd:element name="columns">
          <xsd:annotation>
            <xsd:documentation>This element holds DVM's column List.
            </xsd:documentation>
          </xsd:annotation>
          <xsd:complexType>
            <xsd:sequence>
              <xsd:element name="column" minOccurs="2" maxOccurs="unbounded">
                <xsd:annotation>
                  <xsd:documentation>This represents a DVM Column
                  </xsd:documentation>
                </xsd:annotation>
                <xsd:complexType>
                  <xsd:attribute name="name" use="required" type="xsd:string"/>
                  <xsd:attribute name="qualifier" default="false" type="xsd:boolean"
 use="optional"/>
                  <xsd:attribute name="order" use="optional" type="xsd:positiveInteger"/>
                </xsd:complexType>
              </xsd:element>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
        <xsd:element name="rows" minOccurs="0">
          <xsd:annotation>
            <xsd:documentation>This represents all the DVM Rows.
            </xsd:documentation>
          </xsd:annotation>
          <xsd:complexType>
            <xsd:sequence>
              <xsd:element name="row" minOccurs="1" maxOccurs="unbounded">
                <xsd:annotation>
                  <xsd:documentation>
                    Each DVM row of values
                  </xsd:documentation>
                </xsd:annotation>
                <xsd:complexType>
                  <xsd:sequence>
                    <xsd:element name="cell" minOccurs="2" maxOccurs="unbounded" 
                       type="xsd:string">
                      <xsd:annotation>
                        <xsd:documentation>This is the value for this row and for
 each column in the same order as defined in Columns.
                        </xsd:documentation>
                      </xsd:annotation>
                    </xsd:element>
                  </xsd:sequence>
                </xsd:complexType>
              </xsd:element>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
      <xsd:attribute name="name" use="required" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:annotation>
    <xsd:documentation>This Schema is used to validate the DVM Document got for
 creation and
 update of a DVM.
    </xsd:documentation>
  </xsd:annotation>
</xsd:schema>

44.3 Editing a Domain Value Map

After you create the framework for a domain value map, you can add domains and corresponding domain values to the map using the Domain Value Map Editor.

44.3.1 How to Add Domains to a Domain Value Map

You can define additional domains to map, which are represented as columns in the domain value map. You can also specify whether each new domain contains values to be included in the lookups at runtime or if it is only used to qualify the mapping. Note that domain (column) names must be of the type NCName (non-colonized name), which is a valid XML element name with no colons.

To add a domain to a domain value map:

If the map file is not open in the Domain Value Map Editor, double-click the DVM file in the Applications window.
In the Map Table, click Add and then select Add Domain.

The Create Domain dialog appears.
In the Name field, enter a column name.
In the Qualifier field, select True to set this column as a qualifier. Otherwise, select False.

Tip:

For more information about qualifier domains and qualifier order, see Qualifier Domains and Qualifier Hierarchies.
In the Qualifier Order field, enter a number indicating the priority of the qualifier domain.

This field is enabled only if you selected True in the Qualifier field.

Figure 44-4 Domain Value Map - Create Domain Dialog

Description of "Figure 44-4 Domain Value Map - Create Domain Dialog"
Click OK.

A new column appears in the Map Table.

44.3.2 How to Edit a Domain

Once you add a domain to a domain value map, you can change the name, change whether it is a qualifier domain, and change the qualifier order.

To edit a domain

In the Domain Value Map Editor, select the name of the domain you want to modify.
Click Edit Domain/Values.

The Edit Domain dialog appears.

Figure 44-5 Domain Value Map - Edit Domain Dialog

Description of "Figure 44-5 Domain Value Map - Edit Domain Dialog"
Change any of the fields on the dialog, and then click OK.

Note:

Domain names must be of the type NCName (non-colonized name), which is a valid XML element name with no colons.

44.3.3 How to Add Domain Values to a Domain Value Map

Domain values are displayed in rows in the domain value map, with each row containing the values to be mapped for each domain. You can add as many domain values as required to fully define the mapping between domains.

To add domain values to a domain value map:

In the Domain Value Map Editor, click Add and then select Add Domain Values.

A new row appears beneath the existing rows in the Map Table.
Enter the values for each domain in the new row.
Repeat the above steps to create additional rows. When you are done making changes, click Save All on the Oracle JDeveloper toolbar.

44.3.4 How to Edit Domain Values

Once you add domain values to a domain value map, you can modify the values if needed.

To modify domain values

In the Domain Value Map Editor, select the row containing the values you want to modify.
Click Edit Domain/Values.

The Edit Domain Values dialog appears.

Figure 44-6 Domain Value Map - Edit Domain Values

Description of "Figure 44-6 Domain Value Map - Edit Domain Values"
Modify any of the fields on the dialog, and then click OK.

44.4 Using Domain Value Map Functions

After creating a domain value map, you can use the XPath functions of the domain value map to look up appropriate values and populate the targets for the applications at runtime.

44.4.1 Understanding Domain Value Map Functions

The dvm:lookupValue and dvm:lookupValue1M XPath functions look up a domain value map for a single value or multiple values at runtime.

44.4.1.1 dvm:lookupValue

The dvm:lookupValue function returns a string by looking up the value for the target column in a domain value map, where the source column contains the given source value.

The following code shows an example of dvm:lookupValue function syntax.

dvm:lookupValue(dvmMetadataURI as string, SourceColumnName as string,
 SourceValue as string, TargetColumnName as string, DefaultValue as string) as
 string

The following code provides an example of dvm:lookupValue function use.

dvm:lookupValue('cityMap.dvm','CityCodes','BO', 'CityNames',
'CouldNotBeFound')

The following code shows another example of dvm:lookupValue function syntax:

dvm:lookupValue(dvmMetadataURI as string, SourceColumnName as string,
SourceValue as string, TargetColumnName as string, DefaultValue as string,
(QualifierSourceColumn as string, QualifierSourceValue as string)*) as string

The following code provides another example of dvm:lookupValue function use:

dvm:lookupValue ('cityMap.dvm','CityCodes','BO','CityNames',
 'CouldNotBeFound', 'State', 'Massachusetts')

Arguments

dvmMetadataURI - The domain value map URI.
SourceColumnName - The source column name.
SourceValue - The source value (an XPath expression bound to the source document of the XSLT transformation).
TargetColumnName - The target column name.
DefaultValue - If the value is not found, then the default value is returned.
QualifierSourceColumn: The name of the qualifier column.
QualifierSourceValue: The value of the qualifier.

44.4.1.2 dvm:lookupValue1M

The dvm:lookupValue1M function returns an XML document fragment containing values for multiple target columns of a domain value map, where the value for the source column is equal to the source value. The following example provides details:

dvm:lookupValue1M(dvmMetadataURI as string, SourceColumnName as string,
 SourceValue as string,(TargetColumnName as string)?)as nodeset

Arguments

dvmMetadataURI - The domain value map URI.
SourceColumnName - The source column name.
SourceValue - The source value (an XPath expression bound to the source document of the XSLT transformation).
TargetColumnName - The name of the target columns. At least one column name should be specified. The question mark symbol (?) indicates that you can specify multiple target column names.

The following code shows an example of dvm:lookupValue1M function use.

dvm:lookupValue1M ('cityMap.dvm','CityCode','BO','CityName',
'CityNickName')

The result is shown in the following example:

<CityName>Boston</CityName>
<CityNickName>BeanTown</CityNickName>

44.4.2 How to Use Domain Value Map Functions in Transformations

The domain value map functions can be used for transformations with a BPEL process service component or a Mediator service component. Transformations are performed by using the XSLT Mapper, which appears when you create an XSL file to transform the data from one XML schema to another.

For information about the XSLT Mapper, see Creating Transformations with the XSLT Map Editor.

To use the lookupValue1M function in a transformation:

In the Applications window, double-click an XSL file to open the XSLT Mapper.
In the XSLT Mapper, expand the trees in the Source and Target panes.
In the Components window, click the down arrow, and then select Advanced.
Select DVM Functions, as shown in Figure 44-7.

Figure 44-7 Domain Value Map Functions in the Components Window

Description of "Figure 44-7 Domain Value Map Functions in the Components Window"
Drag and drop lookupValue1M onto the line that connects the source to the target.

A dvm:lookupValue1M icon appears on the connecting line.
Double-click the lookupValue1M icon.

The Edit Function – lookupValue1M dialog appears, as shown in Figure 44-8.

Figure 44-8 Edit Function – lookupValue1M Dialog

Description of "Figure 44-8 Edit Function – lookupValue1M Dialog"
Specify values for the following fields in the Edit Function – lookupValue1M dialog:
1. In the dvmLocation field, enter the location URI of the domain value map file or click Browse to the right of the dvmLocation field to select a domain value map file. You can select an already deployed domain value map from the metadata service (MDS) and also from the shared location in MDS. This can be done by selecting the Resource Palette.
2. In the sourceColumnName field, enter the name of the domain value map column that is associated with the source element value, or click Browse to select a column name from the columns defined for the domain value map you previously selected.
3. In the sourceValue field, enter a value or press Ctrl-Space to use the XPath Building Assistant. Press the up and down arrow keys to locate an object in the list, and press Enter to select an item.
4. In the targetColumnName field, enter the name of the domain value map column that is associated with the target element value, or click Browse to select the name from the columns defined for the domain value map you previously selected.
5. Click Add to add another column as the target column and then enter the name of the column.
A populated Edit Function - lookupValue1M dialog is shown in Figure 44-9.

Figure 44-9 Populated Edit Function – lookupValue1M Dialog

Description of "Figure 44-9 Populated Edit Function – lookupValue1M Dialog"
Click OK.

The XSLT Mapper appears with the lookupValue1M function icon.
From the File menu, select Save All.

For more information about selecting deployed domain value maps, see How to Deploy and Use Shared Data Across Multiple SOA Composite Applications in Oracle JDeveloper.

44.4.3 How to Use Domain Value Map Functions in XPath Expressions

You can use the domain value map functions to create XPath expressions in the Expression Builder dialog. You can access the Expression Builder dialog through the Filter Expressions or the Assign Values functionality of an Oracle Mediator service component.

For information about the Assign Values functionality, see How to Assign Values.

To use the lookupValue function in the Expression Builder dialog:

In the Functions list, select DVM Functions.
Double-click the dvm:lookupValue function to add it to the expression field.
Specify the various arguments of the lookupValue function. For example:
```
dvm:lookupValue('citymap.dvm','CityCodes',$in.Customer/inp1:Customer/Address/Ci
ty,'CityNames','NotFound')
```
This expression, also shown in Figure 44-10, looks up a domain value map for the city name equivalent of a city code. The value of the city code depends on the value specified at runtime.

Figure 44-10 Domain Value Map Functions in the Expression Builder Dialog

Description of "Figure 44-10 Domain Value Map Functions in the Expression Builder Dialog"

44.4.4 What Happens at Runtime

At runtime, a BPEL process service component or a Mediator service component uses the domain value map to look up appropriate values.

44.5 Creating a Domain Value Map Use Case for a Hierarchical Lookup

This section provides a tutorial for using domain value maps in a SOA composite. This use case demonstrates the hierarchical lookup feature of domain value maps. The hierarchical lookup use case consists of the following steps:

Files are retrieved from a directory by an adapter service named ReadOrders.
The ReadOrders adapter service sends the file data to a Mediator named ProcessOrders.
The ProcessOrders Mediator then transforms the message to the structure required by the adapter reference. During transformation, Mediator looks up the UnitsOfMeasure domain value map for an equivalent value of the Common domain.
The ProcessOrders Mediator sends the message to an external reference named WriteOrders.
The WriteOrders reference writes the message to a specified output directory.

To download the sample files mentioned in this section, see the Oracle SOA Suite samples page.

44.5.1 How to Create the HierarchicalValue Use Case

This section provides the design-time tasks for creating, building, and deploying your SOA composite application. These tasks must be performed in the order in which they are presented.

44.5.1.1 Task 1: How to Create an Oracle JDeveloper Application and a Project

To create an Oracle JDeveloper application and a project:

In Oracle JDeveloper, click File and select New.

The New Gallery dialog appears.
In the New Gallery, expand the General node, and select the Applications category.
In the Items list, select SOA Application and click OK.

The Create SOA Application wizard appears.
In the Application Name field, enter Hierarchical and then click Next.

The Name your project page appears.
In the Project Name field, enter HierarchicalValue and click Next.

The Configure SOA settings page appears.
In the Composite Template list, select Empty Composite and then click Finish.

The Applications window of Oracle JDeveloper is populated with the new application and the project, and the SOA Composite Editor contains a blank composite.
From the File menu, select Save All.

44.5.1.2 Task 2: How to Create a Domain Value Map

After creating an application and a project for the use case, create a domain value map.

To create a domain value map:

In the Applications window, right-click the HierarchicalValue project and select New.
In the New Gallery dialog, expand the SOA Tier node, and then select the Transformations category.
In the Items list, select Domain Value Map(DVM) and click OK.

The Create Domain Value Map(DVM) File dialog appears.
In the File Name field, enter UnitsOfMeasure.dvm.
In the Domain Name fields, enter Siebel and Common.
In the Domain Value field corresponding to the Siebel domain, enter Ea.
In the Domain Value field corresponding to the Common domain, enter Each.
Click OK.

The Domain Value Map Editor appears.
Click Add and then select Add Column.

The Create DVM Column dialog appears.
In the Name field, enter TradingPartner.
In the Qualifier list, select true.
In the QualifierOrder field, enter 1 and click OK.
Repeat Step 9 through Step 12 to create another qualifier named StandardCode with a qualifier order value of 2.
Click Add and then select Add Domain Values.

Repeat this step to add two more rows.

Enter the information shown in Table 44-6 in the newly added rows of the domain value map table.

Table 44-6 Information for Rows of Domain Value Map Table

Siebel	Common	TradingPartner	StandardCode
`EC`	`Each`		`OAG`
`E-RN`	`Each`	`A.C.Networks`	`RN`
`EO`	`Each`	`ABC Inc`	`RN`

The Domain Value Map Editor appears, as shown in Figure 44-11.

Figure 44-11 UnitsOfMeasure Domain Value Map

Description of "Figure 44-11 UnitsOfMeasure Domain Value Map"

From the File menu, select Save All and close the Domain Value Map Editor.

44.5.1.3 Task 3: How to Create a File Adapter Service

After creating the domain value map, create a file adapter service named ReadOrders to read the XML files from a directory.

Note:

Oracle Mediator may process the same file twice when run against Oracle Real Application Clusters (Oracle RAC) planned outages. This is because a file adapter is a non-XA compliant adapter. Therefore, when it participates in a global transaction, it may not follow the XA interface specification of processing each file only once.

To create a file adapter service:

From the Components window, select SOA.
Select File Adapter and drag it to the Exposed Services swimlane.
If the Adapter Configuration wizard Welcome page appears, click Next.

The Service Name page appears.
In the Service Name field, enter ReadOrders and then click Next.

The Operation page appears.
In the Operation Type field, select Read File and then click Next.

The File Directories page appears.
In the Directory for Incoming Files (physical path) field, enter the directory from which you want to read the files.
Click Next.

The File Filtering page appears.
In the Include Files with Name Pattern field, enter *.xml and then click Next.

The File Polling page appears.
Change the Polling Frequency field value to 10 seconds and then click Next.

The Messages page appears.
Click Search.

The Type Chooser dialog appears.
Click Import Schema File.

The Import Schema File dialog appears.
Click Search and select the Order.xsd file in the Samples folder.
Click OK.
Expand the navigation tree to Type Explorer > Imported Schemas > Order.xsd.
Select listOfOrder and click OK.
Click Next.

The Finish page appears.
Click Finish.
From the File menu, click Save All.

Figure 44-12 shows the ReadOrders service in the SOA Composite Editor.

Figure 44-12 ReadOrders Service in the SOA Composite Editor

Description of "Figure 44-12 ReadOrders Service in the SOA Composite Editor"

44.5.1.4 Task 4: How to Create ProcessOrders Mediator Component

To create a Mediator named ProcessOrders:

Drag and drop a Mediator icon from the Components window to the Components section of the SOA Composite Editor.

The Create Mediator dialog appears.
In the Name field, enter ProcessOrders.
From the Template list, select Define Interface Later.
Click OK.

A Mediator with name ProcessOrders is created.
In the SOA Composite Editor, connect the ReadOrders service to the ProcessOrders Oracle Mediator, as shown in Figure 44-13.

This specifies the file adapter service to invoke the ProcessOrders Mediator while reading a file from the input directory.

Figure 44-13 ReadOrders Service Connected to the ProcessOrders Mediator

Description of "Figure 44-13 ReadOrders Service Connected to the ProcessOrders Mediator"
From the File menu, select Save All.

44.5.1.5 Task 5: How to Create a File Adapter Reference

To create a file adapter reference:

From the Components window, select SOA.
Select File Adapter and drag it to the External References swimlane.

The Adapter Configuration wizard Welcome page appears.
Click Next.

The Service Name page appears.
In the Service Name field, enter WriteCommonOrder.
Click Next.

The Operation page appears.
In the Operation Type field, select Write File.
Click Next.

The File Configuration page appears.
In the Directory for Outgoing Files (physical path) field, enter the name of the directory in which you want to write the files.
In the File Naming Convention field, enter common_order_%SEQ%.xml and click Next.

The Messages page appears.
Click Search.

The Type Chooser dialog appears.
Navigate to Type Explorer > Project Schema Files > Order.xsd, and then select listOfOrder.
Click OK.
Click Next.

The Finish page appears.
Click Finish.

Figure 44-14 shows the WriteCommonOrder reference in the SOA Composite Editor.

Figure 44-14 WriteCommonOrder Reference in the SOA Composite Editor

Description of "Figure 44-14 WriteCommonOrder Reference in the SOA Composite Editor"
From the File menu, select Save All.

44.5.1.6 Task 6: How to Specify Routing Rules

You must specify the path that messages take from the ReadOrders adapter service to the external reference.

To specify routing rules:

Connect the ProcessOrders Oracle Mediator to the WriteCommonOrder reference, as shown in Figure 44-15.

Figure 44-15 ProcessOrders Mediator Connected to the WriteCommonOrder Reference

Description of "Figure 44-15 ProcessOrders Mediator Connected to the WriteCommonOrder Reference"
Double-click the ProcessOrders Oracle Mediator.
To the right of the Transform Using field, click the icon.

The Request Transformation Map dialog appears.
Select Create New Mapper File and click OK.

A listOfOrder_To_listOfOrder.xsl file appears in the XSLT Mapper.
Drag and drop the imp1:listOfOrder source element onto the imp1:listOfOrder target element.

The Auto Map Preferences dialog appears.
From the During Auto Map options, deselect Match Elements Considering their Ancestor Names.
Click OK.

The listOfOrder_To_listOfOrder.xsl file appears, as shown in Figure 44-16.

Figure 44-16 imp1:listOfOrder To imp1:listOfOrder Transformation

Description of "Figure 44-16 imp1:listOfOrder To imp1:listOfOrder Transformation"
In the Components window, select Advanced.
Click DVM Functions.
Drag and drop lookupValue on the line connecting the unitsOfMeasure elements, as shown in Figure 44-17.

Figure 44-17 Adding lookupValue Function to imp1:listOfOrder To imp1:listOfOrder.xsl

Description of "Figure 44-17 Adding lookupValue Function to imp1:listOfOrder To imp1:listOfOrder.xsl"
Double-click the lookupvalue icon.

The Edit Function-lookupValue dialog appears.
To the right of the dvmLocation field, click Search.

The SOA Resource Lookup dialog appears.
Select UnitsofMeasure.dvm and click OK.
To the right of the sourceColumnName field, click Search.

The Select DVM Column dialog appears.
Select Siebel and click OK.
In the sourceValue column, enter the following:

/imp1:listOfOrder/imp1:order/imp1:baseData/imp1:unitOfMeasure
To the right of the targetColumnName field, click Search.

The Select DVM Column dialog appears.
Select Common and click OK.
In the defaultValue field, enter "No_Value_Found".
Click Add.

A qualifierColumnName row is added.
In the qualifierColumnName field, enter "StandardCode".
Click Add.

A qualifierValue row is added.
In the qualifierValue field, enter the following:

/imp1:listOfOrder/imp1:order/imp1:baseData/imp1:standard.
Click Add to insert another qualifierColumnName row.
In the qualifierColumnName field, enter "TradingPartner".
Click Add to insert another qualifierValue row.
In the qualifierValue field, enter the following:

/imp1:listOfOrder/imp1:order/imp1:baseData/imp1:tp.

The Edit Function-lookupValue dialog appears, as shown in Figure 44-18.

Figure 44-18 Edit Function-lookupValue Function Dialog: Hierarchical Lookup Use Case

Description of "Figure 44-18 Edit Function-lookupValue Function Dialog: Hierarchical Lookup Use Case"
Click OK.

The transformation appears, as shown in Figure 44-19.

Figure 44-19 Complete imp1:listOfOrder To imp1:listOfOrder Transformation

Description of "Figure 44-19 Complete imp1:listOfOrder To imp1:listOfOrder Transformation"
From the File menu, select Save All and close the listOfOrder_To_listOfOrder.xsl file at the top.

44.5.1.7 Task 7: How to Configure an Application Server Connection

An application server connection is required for deploying your SOA composite application. For information on creating an application server connection, see Creating an Application Server Connection.

44.5.1.8 Task 8: How to Deploy the Composite Application

Deploying the HierarchicalValue composite application to an application server consists of the following steps:

Creating an application deployment profile.
Deploying the application to the application server.

For detailed information about these steps, see How to Deploy a Single SOA Composite in Oracle JDeveloper.

44.5.2 How to Run and Monitor the HierarchicalValue Application

After deploying the HierarchicalValue application, you can run it by copying the input XML file sampleorder.xml to the input folder. This file is available in the samples folder. On successful completion, a file named common_order_1.xml is written to the specified output directory.

For monitoring the running instance, you can use Oracle Enterprise Manager Fusion Middleware Control at the following URL:

http://hostname:port/em

where hostname is the host on which you installed the Oracle SOA Suite infrastructure.

For detailed information about these steps, see How to Deploy a Single SOA Composite in Oracle JDeveloper.

44.6 Creating a Domain Value Map Use Case For Multiple Values

This section provides a tutorial demonstrating how to create a domain value map with multiple values to look up. This use case demonstrates the integration scenario for using a domain value map lookup between two endpoints to look up multiple values. For example, if the inbound value is State, then the outbound values are Shortname of State, Language, and Capital. The multivalue lookup use case consists of the following steps:

Files are retrieved from a directory by an adapter service named readFile.
The readFile adapter service sends the file data to an Oracle Mediator named LookupMultiplevaluesMediator.
The LookupMultiplevaluesMediator Oracle Mediator then transforms the message to the structure required by the adapter reference. During transformation, Oracle Mediator looks up the multivalue domain value map for an equivalent value of the Longname and Shortname domains.
The LookupMultiplevaluesMediator Oracle Mediator sends the message to an external reference named writeFile.
The writeFile reference writes the message to a specified output directory.

To download the sample files mentioned in this section, see Oracle SOA Suite samples page.

44.6.1 How to Create the Multivalue Use Case

This section provides the design-time tasks for creating, building, and deploying your SOA composite application. Perform these tasks in the order in which they are presented.

44.6.1.1 Task 1: How to Create an Oracle JDeveloper Application and Project

To create an Oracle JDeveloper application and project:

In Oracle JDeveloper, click File and select New.

The New Gallery dialog appears.
In the New Gallery, expand the General node, and select the Applications category.
In the Items list, select SOA Application and click OK.

The Create SOA Application wizard appears.
In the Application Name field, enter Multivalue and then click Next.

The Name your project page appears.
In the Project Name field, enter Multivalue and click Next.

The Configure SOA settings page appears.
From the Composite Template list, select Empty Composite and then click Finish.

The Applications window of Oracle JDeveloper is populated with the new application and project, and the SOA Composite Editor contains a blank composite.
From the File menu, select Save All.

44.6.1.2 Task 2: How to Create a Domain Value Map

After creating an application and a project for the use case, create the domain value map.

To create a domain value map:

In the Applications window, right-click the Multivalue project and select New.
In the New Gallery dialog, expand the SOA Tier node, and then select the Transformations category.
In the Items list, select Domain Value Map(DVM) and click OK.

The Create Domain Value Map(DVM) File dialog appears.
In the File Name field, enter multivalue.dvm.
In the Domain Name fields, enter Longname, Shortname, Language, and Capital.
In the Domain Value field corresponding to the Longname domain, enter Karnataka.
In the Domain Value field corresponding to the Shortname domain, enter KA.
In the Domain Value field corresponding to the Language domain, enter Kannada.
In the Domain Value field corresponding to the Capital domain, enter Bangalore.
Click OK.

The Domain Value Map Editor appears.
Click Add and then select Add Row.

Repeat this step to add two more rows.

Enter the information shown in Table 44-7 in the newly added rows of the domain value map table:

Table 44-7 Information for Rows of Domain Value Map Table

Longname	Shortname	Language	Capital
`Karnataka`	`KA`	`Kannada`	`Bangalore`
`Tamilnadu`	`TN`	`Tamil`	`Chennai`
`Andhrapradesh`	`AP`	`Telugu`	`Hyderbad`
`Kerala`	`KL`	`Malayalam`	`Trivandram`

The Domain Value Map Editor appears, as shown in Figure 44-20.

Figure 44-20 Multivalue Domain Value Map

Description of "Figure 44-20 Multivalue Domain Value Map"

From the File menu, select Save All and close the Domain Value Map Editor.

44.6.1.3 Task 3: How to Create a File Adapter Service

After creating the domain value map, create a file adapter service named readFile to read the XML files from a directory.

Note:

Mediator may process the same file twice when run against Oracle RAC planned outages. This is because a file adapter is a non-XA compliant adapter. Therefore, when it participates in a global transaction, it may not follow the XA interface specification of processing each file only once.

To create a file adapter service:

From the Components window, select SOA.
Select File Adapter and drag it to the Exposed Services swimlane.
If the Adapter Configuration wizard Welcome page appears, click Next.

The Service Name page appears.
In the Service Name field, enter readFile and then click Next.

The Adapter Interface page appears.
Click Define from operation and schema (specified later) and then click Next.

The Operation page appears.
In the Operation Type field, select Read File and then click Next.

The File Directories page appears.
In the Directory for Incoming Files (physical path) field, enter the directory from which you want to read the files.
Click Next.

The File Filtering page appears.
In the Include Files with Name Pattern field, enter *.xml and then click Next.

The File Polling page appears.
Change the Polling Frequency field value to 1 second and then click Next.

The Messages page appears.
Click Search.

The Type Chooser dialog appears.
Click Import Schema File.

The Import Schema File dialog appears.
Click Search and select the input.xsd file in the Samples folder.
Click OK.
Expand the navigation tree to Type Explorer > Imported Schemas > input.xsd.
Select Root-Element and click OK.
Click Next.

The Finish page appears.
Click Finish.
From the File menu, select Save All.

Figure 44-21 shows the readFile service in the SOA Composite Editor.

Figure 44-21 readFile Service in the SOA Composite Editor

Description of "Figure 44-21 readFile Service in the SOA Composite Editor"

44.6.1.4 Task 4: How to Create the LookupMultiplevaluesMediator Mediator

To create the LookupMultiplevaluesMediator Mediator:

Drag and drop a Mediator icon from the Components window to the Components section of the SOA Composite Editor.

The Create Mediator dialog appears.
In the Name field, enter LookupMultiplevaluesMediator.
From the Template list, select Define Interface Later.
Click OK.

An Oracle Mediator with the name LookupMultiplevaluesMediator is created.
In the SOA Composite Editor, connect the readFile service to the LookupMultiplevaluesMediator Oracle Mediator, as shown in Figure 44-22.

This specifies the file adapter service to invoke the LookupMultiplevaluesMediator Oracle Mediator while reading a file from the input directory.

Figure 44-22 readFile Service Connected to the LookupMultiplevaluesMediator Mediator

Description of "Figure 44-22 readFile Service Connected to the LookupMultiplevaluesMediator Mediator"
From the File menu, select Save All.

44.6.1.5 Task 5: How to Create a File Adapter Reference

To create a file adapter reference:

From the Components window, select SOA.
Select File Adapter and drag it to the External References swimlane.

The Adapter Configuration wizard Welcome page appears.
Click Next.

The Service Name page appears.
In the Service Name field, enter writeFile and then click Next.

The Adapter Interface page appears.
Click Define from operation and schema (specified later) and then click Next.

The Operation page appears.
Click Next.

The Operation page appears.
In the Operation Type field, select Write File.
Click Next.

The File Configuration page appears.
In the Directory for Outgoing Files (physical path) field, enter the name of the directory where you want to write the files.
In the File Naming Convention field, enter multivalue_%SEQ%.xml and click Next.

The Messages page appears.
Click Search.

The Type Chooser dialog appears.
Navigate to Type Explorer > Project Schema Files > output.xsd, and then select Root-Element.
Click OK.
Click Next.

The Finish page appears.
Click Finish.

Figure 44-23 shows the writeFile reference in the SOA Composite Editor.

Figure 44-23 writeFile Reference in SOA Composite Editor

Description of "Figure 44-23 writeFile Reference in SOA Composite Editor"
From the File menu, select Save All.

44.6.1.6 Task 6: How to Specify Routing Rules

You must specify the path that messages take from the readFile adapter service to the external reference.

To specify routing rules

Connect the LookupMultiplevaluesMediator Mediator to the writeFile reference, as shown in Figure 44-24.

Figure 44-24 LookupMultiplevaluesMediator Mediator Connected to the writeFile Reference

Description of "Figure 44-24 LookupMultiplevaluesMediator Mediator Connected to the writeFile Reference"
Double-click the LookupMultiplevaluesMediator Mediator.
To the right of the Transform Using field, click the icon.

The Request Transformation Map dialog appears.
Select Create New Mapper File and click OK.

An Input_To_Output_with_multiple_values_lookup.xsl file appears in the XSLT Mapper.
Drag and drop the imp1:Root-Element source element to the ns2:Root-Element target element.

The Auto Map Preferences dialog appears.
From the During Auto Map options list, deselect Match Elements Considering their Ancestor Names.
Click OK.

The Input_To_Output_with_multiple_values_lookup.xsl file appears in the XSLT Mapper, as shown in Figure 44-25.

Figure 44-25 imp1:Root-Element To ns2:Root-Element Transformation

Description of "Figure 44-25 imp1:Root-Element To ns2:Root-Element Transformation"
In the Components window, select Advanced.
Click DVM Functions.
Drag and drop lookupValue1M in the center panel, as shown in Figure 44-26.

Figure 44-26 Adding lookupValue Function to imp1:Root-Element to ns2:Root-Element

Description of "Figure 44-26 Adding lookupValue Function to imp1:Root-Element to ns2:Root-Element"
Double-click the lookupvalue1M icon.

The Edit Function-lookupValue1M dialog appears.
To the right of the dvmLocation field, click Search.

The SOA Resource Lookup dialog appears.
Select multivalue.dvm and click OK.
To the right of the sourceColumnName field, click Search.

The Select DVM Column dialog appears.
Select Longname and click OK.
In the sourceValue column, enter the following:

/imp1:Root-Element/imp1:Details/imp1:Longname.
To the right of the targetColumnName field, click Search.

The Select DVM Column dialog appears.
Select Shortname and click OK.
Click Add.

A targetColumnName row is added.
In the targetColumnName field, enter "Language".
Click Add to insert another targetColumnName row.
In the targetColumnName field, enter "Capital".

The Edit Function-lookupValue dialog appears, as shown in Figure 44-27.

Figure 44-27 Edit Function-lookupValue Function Dialog: Multiple Value Lookup Use Case

Description of "Figure 44-27 Edit Function-lookupValue Function Dialog: Multiple Value Lookup Use Case"
Click OK.

The Transformation appears, as shown in Figure 44-28.

Figure 44-28 Complete imp1:Root-Element To ns2:Root-Element Transformation

Description of "Figure 44-28 Complete imp1:Root-Element To ns2:Root-Element Transformation"
From the File menu, select Save All and close the Input_To_Output_with_multiple_values_lookup.xsl file.

44.6.1.7 Task 7: How to Configure an Application Server Connection

An application server connection is required for deploying your SOA composite application. For information on creating an application server connection, see Creating an Application Server Connection.

44.6.1.8 Task 8: How to Deploy the Composite Application

Deploying the Multivalue composite application to an application server consists of the following steps:

Creating an application deployment profile.
Deploying the application to the application server.

For detailed information about these steps, see How to Deploy a Single SOA Composite in Oracle JDeveloper.

44.6.2 How to Run and Monitor the Multivalue Application

After deploying the Multivalue application, you can run it by copying the input XML file sampleinput.xml to the input folder. This file is available in the samples folder. On successful completion, a file with name multivalue_1.xml is written to the specified output directory.

For monitoring the running instance, you can use Oracle Enterprise Manager Fusion Middleware Control at the following URL:

http://hostname:port/em

where hostname is the host on which you installed the Oracle SOA Suite infrastructure.

In Oracle Enterprise Manager Fusion Middleware Control, you can click Multivalue to see the project dashboard.

To view the detailed execution trail, click the instance ID in the instance column. The Flow Trace page appears.

44.7 Preloading DVM Cache for Faster First-Use

When a DVM is first called into use, the DVM gets loaded into the cache from the MDS. Subsequent lookups are faster, as the DVM is picked from the cache.

If you have a lot of records in your DVMs, you may want to preload the DVMs into the cache during server startup, so that the DVMs are readily available for first use.

You can choose to preload the DVM cache at server startup using the MBean property LoadDVMsAtStartup in the System MBean Browser of Oracle Enterprise Manager Fusion Middleware Control. Setting LoadDVMsAtStartup to true loads all the DVMs into the cache at server startup. The default value for LoadDVMsAtStartup is false.

44.7.1 How to Preload DVM Cache at Server Startup

To preload DVM cache at server startup:

Log in to Oracle Enterprise Manager Fusion Middleware Control.
From the SOA Infrastructure menu, select SOA Administration > Common Properties.
At the bottom of the SOA Infrastructure Common Properties page, click More SOA Infra Advanced Configuration Properties.
Click LoadDVMsAtStartup.
In the Value field, select true.
Click Apply.
Click Return.