Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite
11g Release 1 (11.1.1.5.0)

Part Number E10224-09
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

44 Working with Domain Value Maps

This chapter describes how to use domain value maps to map the vocabulary used by different domains.

This chapter includes the following sections:

44.1 Introduction to Domain Value Maps

Domain value maps operate on actual data values that transit through the infrastructure at runtime. They enable you to map from one vocabulary used in a given domain to another vocabulary used in a different domain. For example, one domain may represent a city with a long name (Boston), while another domain may represent a city with a short name (BO). In such cases, you can directly map the values by using domain value maps. 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


Each domain value map typically holds a specific category of mappings among multiple applications. For example, one domain value map may hold mappings for city codes and another may hold mappings for state codes.

Domain value map values are static. You specify the domain value map values at design time using Oracle JDeveloper, and then at runtime, the domain value map columns are looked up for values.

For information about editing domain value maps at runtime with Oracle SOA Composer, see Chapter 45, "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 Chapter 46, "Working with Cross References."

44.1.1 Domain Value Map Features

This section describes domain value map functionality.

44.1.1.1 Qualifier Support

Qualifiers qualify mappings. A mapping may not be valid unless qualified with additional information. For example, a domain value map containing a city code-to-city name mapping may 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 qualify when the mapping becomes valid, as 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


You can also specify multiple qualifiers for a domain value map. For example, as shown in Table 44-3, BELG to Belgrade mapping can also be 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 Order Support

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. In Table 44-3, the state qualifier can have a higher order than the country qualifier, as a matching state indicates a more exact 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 a "". It proceeds until a match is found, or until a match is not found with all qualifiers set to a "". Figure 44-1 describes the hierarchical lookup performed for the following lookup in Table 44-3.

State=Arkansas, Country=Canada, CityCode=KN_USA

In this example, the State qualifier has a qualifier value of 1 and the Country qualifier has a qualifier value 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 follows
Description of "Figure 44-1 Hierarchical Lookup Example"

When 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.

When 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 Mapping Support

You can map one value 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 three 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 of Oracle JDeveloper, and then at runtime, use it to look up column values.

44.2.1 How to Create Domain Value Maps

You can create a domain value map by using the Create Domain Value Map(DVM) File dialog in Oracle JDeveloper.

To create a domain value map:

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

    The New Gallery dialog is displayed.

  2. Expand the SOA Tier node, and then select the Transformations category.

  3. In the Items list, select Domain Value Map(DVM) and click OK.

    The Create Domain Value Map(DVM) File dialog is displayed.

  4. In the File Name field, enter the name of the domain value map file. For example, specify CityCodes to identify a domain value map for city names and city codes.

  5. In the Description field, enter a description for the domain value map. For example, Mappings of city names and city codes. This field is optional.

  6. In the Domain Name field, enter a name for each domain. For example, you can enter CityCode in one Domain Name field and CityName in another. Each domain name must be unique in a domain value map.

    Note:

    You can later add more domains to a domain value map by using the Domain Value Map Editor.
  7. In the Domain Value field, enter a value corresponding to each domain. For example, enter BO for the CityCode domain and Boston for the CityName domain, as shown in Figure 44-2.

    Figure 44-2 Populated Create Domain Value Map File Dialog

    Description of Figure 44-2 follows
    Description of "Figure 44-2 Populated Create Domain Value Map File Dialog"

  8. Click OK.

    The Domain Value Map Editor is displayed.

44.2.2 What Happens When You Create a Domain Value Map

A file with extension .dvm is created and appears in the Application Navigator, as shown in Figure 44-3.

Figure 44-3 A Domain Value Map File in Application Navigator

Description of Figure 44-3 follows
Description of "Figure 44-3 A Domain Value Map File in Application Navigator"

All .dvm files are based on the schema definition (XSD) file shown in Example 44-1.

Example 44-1 XSD File for Domain Value Map Files

<?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 have created a domain value map, you can edit it and make adjustments to the presentation of data in the Domain Value Map Editor.

44.3.1 How to Add Columns to a Domain Value Map

A domain value map column defines the domain whose values you want to map with other domains.

To add a column to a domain value map:

  1. Click Add.

  2. Select Add Column.

    The Create DVM Column dialog is displayed.

  3. In the Name field, enter a column name.

  4. In the Qualifier field, select True to set this column as a qualifier. Otherwise, select False.

  5. In the Qualifier Order field, enter a qualifier number. This field is enabled only if you selected True in the Qualifier field.

  6. Click OK.

44.3.2 How to Add Rows to a Domain Value Map

A domain value map row contains the values of the domains.

To add a row to a domain value map:

  1. In the Domain Value Map Editor, click Add.

  2. Select Add Row.

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

You can use the dvm:lookupValue and dvm:lookupValue1M XPath functions to 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.

  • Example 44-2 shows an example of dvm:lookupValue function syntax.

    Example 44-2 dvm:lookupValue Function Syntax

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

    Example 44-3 provides an example of dvm:lookupValue function use.

    Example 44-3 dvm:lookupValue Function Use

    dvm:lookupValue('cityMap.dvm','CityCodes','BO', 'CityNames',
    'CouldNotBeFound')
    
  • Example 44-4 shows another example of dvm:lookupValue function syntax.

    Example 44-4 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
    

    Example 44-5 provides another example of dvm:lookupValue function use.

    Example 44-5 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. Example 44-6 provides details.

Example 44-6 dvm:lookupValue1M Function Syntax

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.

Example 44-7 shows an example of dvm:lookupValue1M function use.

Example 44-7 dvm:lookupValue1M Function Use

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

The result is shown in Example 44-8.

Example 44-8 dvm:lookupValue1M Function Result

<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 an Oracle Mediator service component. Transformations are performed by using the XSLT Mapper, which is displayed when you create an XSL file to transform the data from one XML schema to another.

For information about the XSLT Mapper, see Chapter 37, "Creating Transformations with the XSLT Mapper."

To use the lookupValue1M function in a transformation:

  1. In the Application Navigator, double-click an XSL file to open the XSLT Mapper.

  2. In the XSLT Mapper, expand the trees in the Source and Target panes.

  3. In the Component Palette, click the down arrow, and then select Advanced.

  4. Select DVM Functions, as shown in Figure 44-4.

    Figure 44-4 Domain Value Map Functions in the Component Palette

    Description of Figure 44-4 follows
    Description of "Figure 44-4 Domain Value Map Functions in the Component Palette"

  5. Drag and drop lookupValue1M onto the line that connects the source to the target.

    A dvm:lookupValue1M icon appears on the connecting line.

  6. Double-click the lookupValue1M icon.

    The Edit Function – lookupValue1M dialog is displayed, as shown in Figure 44-5.

    Figure 44-5 Edit Function – lookupValue1M Dialog

    Description of Figure 44-5 follows
    Description of "Figure 44-5 Edit Function – lookupValue1M Dialog"

  7. 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-6.

    Figure 44-6 Populated Edit Function – lookupValue1M Dialog

    Description of Figure 44-6 follows
    Description of "Figure 44-6 Populated Edit Function – lookupValue1M Dialog"

  8. Click OK.

    The XSLT Mapper is displayed with the lookupValue1M function icon.

  9. From the File menu, select Save All.

For more information about selecting deployed domain value maps, see Section 40.7.3, "Deploying and Using Shared Metadata Across 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 Section 19.2.2.9, "How to Assign Values."

To use the lookupValue function in the Expression Builder dialog:

  1. In the Functions list, select DVM Functions.

  2. Double-click the dvm:lookupValue function to add it to the expression field.

  3. 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-7, 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-7 Domain Value Map Functions in the Expression Builder Dialog

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

44.4.4 What Happens at Runtime

At runtime, a BPEL process service component or an Oracle 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 use case demonstrates the hierarchical lookup feature of domain value maps. The hierarchical lookup use case consists of the following steps:

  1. Files are retrieved from a directory by an adapter service named ReadOrders.

  2. The ReadOrders adapter service sends the file data to an Oracle Mediator named ProcessOrders.

  3. The ProcessOrders Oracle Mediator then transforms the message to the structure required by the adapter reference. During transformation, Oracle Mediator looks up the UnitsOfMeasure domain value map for an equivalent value of the Common domain.

  4. The ProcessOrders Oracle Mediator sends the message to an external reference named WriteOrders.

  5. The WriteOrders reference writes the message to a specified output directory.

For downloading the sample files mentioned in this section, visit the following URL:

https://soasamples.samplecode.oracle.com/#mediator

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:

  1. In Oracle JDeveloper, click File and select New.

    The New Gallery dialog appears.

  2. In the New Gallery, expand the General node, and select the Applications category.

  3. In the Items list, select SOA Application and click OK.

    The Create SOA Application wizard appears.

  4. In the Application Name field, enter Hierarchical and then click Next.

    The Name your project page appears.

  5. In the Project Name field, enter HierarchicalValue and click Next.

    The Configure SOA settings page appears.

  6. In the Composite Template list, select Empty Composite and then click Finish.

    The Application Navigator of Oracle JDeveloper is populated with the new application and the project, and the SOA Composite Editor contains a blank composite.

  7. 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, you must create a domain value map.

To create a domain value map:

  1. In the Application Navigator, right-click the HierarchicalValue project and select New.

  2. In the New Gallery dialog, expand the SOA Tier node, and then select the Transformations category.

  3. In the Items list, select Domain Value Map(DVM) and click OK.

    The Create Domain Value Map(DVM) File dialog is displayed.

  4. In the File Name field, enter UnitsOfMeasure.dvm.

  5. In the Domain Name fields, enter Siebel and Common.

  6. In the Domain Value field corresponding to the Siebel domain, enter Ea.

  7. In the Domain Value field corresponding to the Common domain, enter Each.

  8. Click OK.

    The Domain Value Map Editor is displayed.

  9. Click Add and then select Add Column.

    The Create DVM Column dialog is displayed.

  10. In the Name field, enter TradingPartner.

  11. In the Qualifier list, select true.

  12. In the QualifierOrder field, enter 1 and click OK.

  13. Repeat Step 9 through Step 12 to create another qualifier named StandardCode with a qualifier order value of 2.

  14. Click Add and then select Add Row.

    Repeat this step to add two more rows.

  15. 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-8.

    Figure 44-8 UnitsOfMeasure Domain Value Map

    Description of Figure 44-8 follows
    Description of "Figure 44-8 UnitsOfMeasure Domain Value Map"

  16. 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, you must 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:

  1. From the Component Palette, select SOA.

  2. Select File Adapter and drag it to the Exposed Services swimlane.

  3. If the Adapter Configuration wizard Welcome page appears, click Next.

    The Service Name page is displayed.

  4. In the Service Name field, enter ReadOrders and then click Next.

    The Operation page is displayed.

  5. In the Operation Type field, select Read File and then click Next.

    The File Directories page is displayed.

  6. In the Directory for Incoming Files (physical path) field, enter the directory from which you want to read the files.

  7. Click Next.

    The File Filtering page is displayed.

  8. In the Include Files with Name Pattern field, enter *.xml and then click Next.

    The File Polling page is displayed.

  9. Change the Polling Frequency field value to 10 seconds and then click Next.

    The Messages page is displayed.

  10. Click Search.

    The Type Chooser dialog is displayed.

  11. Click Import Schema File.

    The Import Schema File dialog is displayed.

  12. Click Search and select the Order.xsd file in the Samples folder.

  13. Click OK.

  14. Expand the navigation tree to Type Explorer > Imported Schemas > Order.xsd.

  15. Select listOfOrder and click OK.

  16. Click Next.

    The Finish page is displayed.

  17. Click Finish.

  18. From the File menu, click Save All.

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

    Figure 44-9 ReadOrders Service in the SOA Composite Editor

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

44.5.1.4 Task 4: How to Create ProcessOrders Oracle Mediator Component

To create an Oracle Mediator named ProcessOrders:

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

    The Create Mediator dialog is displayed.

  2. In the Name field, enter ProcessOrders.

  3. From the Template list, select Define Interface Later.

  4. Click OK.

    An Oracle Mediator with name ProcessOrders is created.

  5. In the SOA Composite Editor, connect the ReadOrders service to the ProcessOrders Oracle Mediator, as shown in Figure 44-10.

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

    Figure 44-10 ReadOrders Service Connected to the ProcessOrders Oracle Mediator

    Description of Figure 44-10 follows
    Description of "Figure 44-10 ReadOrders Service Connected to the ProcessOrders Oracle Mediator"

  6. 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:

  1. From the Component Palette, select SOA.

  2. Select File Adapter and drag it to the External References swimlane.

    The Adapter Configuration wizard Welcome page is displayed.

  3. Click Next.

    The Service Name page is displayed.

  4. In the Service Name field, enter WriteCommonOrder.

  5. Click Next.

    The Operation page is displayed.

  6. In the Operation Type field, select Write File.

  7. Click Next.

    The File Configuration page is displayed.

  8. In the Directory for Outgoing Files (physical path) field, enter the name of the directory in which you want to write the files.

  9. In the File Naming Convention field, enter common_order_%SEQ%.xml and click Next.

    The Messages page is displayed.

  10. Click Search.

    The Type Chooser dialog is displayed.

  11. Navigate to Type Explorer > Project Schema Files > Order.xsd, and then select listOfOrder.

  12. Click OK.

  13. Click Next.

    The Finish page is displayed.

  14. Click Finish.

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

    Figure 44-11 WriteCommonOrder Reference in the SOA Composite Editor

    Description of Figure 44-11 follows
    Description of "Figure 44-11 WriteCommonOrder Reference in the SOA Composite Editor"

  15. 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:

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

    Figure 44-12 ProcessOrders Oracle Mediator Connected to the WriteCommonOrder Reference

    Description of Figure 44-12 follows
    Description of "Figure 44-12 ProcessOrders Oracle Mediator Connected to the WriteCommonOrder Reference"

  2. Double-click the ProcessOrders Oracle Mediator.

  3. To the right of the Transform Using field, click the icon.

    The Request Transformation Map dialog is displayed.

  4. Select Create New Mapper File and click OK.

    A listOfOrder_To_listOfOrder.xsl file is displayed in the XSLT Mapper.

  5. Drag and drop the imp1:listOfOrder source element onto the imp1:listOfOrder target element.

    The Auto Map Preferences dialog is displayed.

  6. From the During Auto Map options, deselect Match Elements Considering their Ancestor Names.

  7. Click OK.

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

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

    Description of Figure 44-13 follows
    Description of "Figure 44-13 imp1:listOfOrder To imp1:listOfOrder Transformation"

  8. In the Component Palette, select Advanced.

  9. Click DVM Functions.

  10. Drag and drop lookupValue on the line connecting the unitsOfMeasure elements, as shown in Figure 44-14.

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

    Description of Figure 44-14 follows
    Description of "Figure 44-14 Adding lookupValue Function to imp1:listOfOrder To imp1:listOfOrder.xsl"

  11. Double-click the lookupvalue icon.

    The Edit Function-lookupValue dialog is displayed.

  12. To the right of the dvmLocation field, click Search.

    The SOA Resource Lookup dialog is displayed.

  13. Select UnitsofMeasure.dvm and click OK.

  14. To the right of the sourceColumnName field, click Search.

    The Select DVM Column dialog is displayed.

  15. Select Siebel and click OK.

  16. In the sourceValue column, enter the following:

    /imp1:listOfOrder/imp1:order/imp1:baseData/imp1:unitOfMeasure

  17. To the right of the targetColumnName field, click Search.

    The Select DVM Column dialog is displayed.

  18. Select Common and click OK.

  19. In the defaultValue field, enter "No_Value_Found".

  20. Click Add.

    A qualifierColumnName row is added.

  21. In the qualifierColumnName field, enter "StandardCode".

  22. Click Add.

    A qualifierValue row is added.

  23. In the qualifierValue field, enter the following:

    /imp1:listOfOrder/imp1:order/imp1:baseData/imp1:standard.

  24. Click Add to insert another qualifierColumnName row.

  25. In the qualifierColumnName field, enter "TradingPartner".

  26. Click Add to insert another qualifierValue row.

  27. 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-15.

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

    Description of Figure 44-15 follows
    Description of "Figure 44-15 Edit Function-lookupValue Function Dialog: Hierarchical Lookup Use Case"

  28. Click OK.

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

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

    Description of Figure 44-16 follows
    Description of "Figure 44-16 Complete imp1:listOfOrder To imp1:listOfOrder Transformation"

  29. 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 Section 40.7.1.1.1, "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 Section 40.7.1, "Deploying 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 Section 40.7.1, "Deploying a Single SOA Composite in Oracle JDeveloper."

44.6 Creating a Domain Value Map Use Case For Multiple Values

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:

  1. Files are retrieved from a directory by an adapter service named readFile.

  2. The readFile adapter service sends the file data to an Oracle Mediator named LookupMultiplevaluesMediator.

  3. 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.

  4. The LookupMultiplevaluesMediator Oracle Mediator sends the message to an external reference named writeFile.

  5. The writeFile reference writes the message to a specified output directory.

For downloading the sample files mentioned in this section, visit the following URL:

https://soasamples.samplecode.oracle.com/#mediator

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:

  1. In Oracle JDeveloper, click File and select New.

    The New Gallery dialog appears.

  2. In the New Gallery, expand the General node, and select the Applications category.

  3. In the Items list, select SOA Application and click OK.

    The Create SOA Application wizard appears.

  4. In the Application Name field, enter Multivalue and then click Next.

    The Name your project page appears.

  5. In the Project Name field, enter Multivalue and click Next.

    The Configure SOA settings page appears.

  6. From the Composite Template list, select Empty Composite and then click Finish.

    The Application Navigator of Oracle JDeveloper is populated with the new application and project, and the SOA Composite Editor contains a blank composite.

  7. 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, you must create a domain value map.

To create a domain value map:

  1. In the Application Navigator, right-click the Multivalue project and select New.

  2. In the New Gallery dialog, expand the SOA Tier node, and then select the Transformations category.

  3. In the Items list, select Domain Value Map(DVM) and click OK.

    The Create Domain Value Map(DVM) File dialog is displayed.

  4. In the File Name field, enter multivalue.dvm.

  5. In the Domain Name fields, enter Longname, Shortname, Language, and Capital.

  6. In the Domain Value field corresponding to the Longname domain, enter Karnataka.

  7. In the Domain Value field corresponding to the Shortname domain, enter KA.

  8. In the Domain Value field corresponding to the Language domain, enter Kannada.

  9. In the Domain Value field corresponding to the Capital domain, enter Bangalore.

  10. Click OK.

    The Domain Value Map Editor is displayed.

  11. Click Add and then select Add Row.

    Repeat this step to add two more rows.

  12. 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-17.

    Figure 44-17 Multivalue Domain Value Map

    Description of Figure 44-17 follows
    Description of "Figure 44-17 Multivalue Domain Value Map"

  13. 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, you must create a file adapter service named readFile to read the XML files from a directory.

Note:

Oracle 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:

  1. From the Component Palette, select SOA.

  2. Select File Adapter and drag it to the Exposed Services swimlane.

  3. If the Adapter Configuration wizard Welcome page appears, click Next.

    The Service Name page is displayed.

  4. In the Service Name field, enter readFile and then click Next.

    The Adapter Interface page is displayed.

  5. Click Define from operation and schema (specified later) and then click Next.

    The Operation page is displayed.

  6. In the Operation Type field, select Read File and then click Next.

    The File Directories page is displayed.

  7. In the Directory for Incoming Files (physical path) field, enter the directory from which you want to read the files.

  8. Click Next.

    The File Filtering page is displayed.

  9. In the Include Files with Name Pattern field, enter *.xml and then click Next.

    The File Polling page is displayed.

  10. Change the Polling Frequency field value to 1 second and then click Next.

    The Messages page is displayed.

  11. Click Search.

    The Type Chooser dialog is displayed.

  12. Click Import Schema File.

    The Import Schema File dialog is displayed.

  13. Click Search and select the input.xsd file in the Samples folder.

  14. Click OK.

  15. Expand the navigation tree to Type Explorer > Imported Schemas > input.xsd.

  16. Select Root-Element and click OK.

  17. Click Next.

    The Finish page is displayed.

  18. Click Finish.

  19. From the File menu, select Save All.

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

    Figure 44-18 readFile Service in the SOA Composite Editor

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

44.6.1.4 Task 4: How to Create the LookupMultiplevaluesMediator Oracle Mediator

To create the LookupMultiplevaluesMediator Oracle Mediator:

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

    The Create Mediator dialog is displayed.

  2. In the Name field, enter LookupMultiplevaluesMediator.

  3. From the Template list, select Define Interface Later.

  4. Click OK.

    An Oracle Mediator with the name LookupMultiplevaluesMediator is created.

  5. In the SOA Composite Editor, connect the readFile service to the LookupMultiplevaluesMediator Oracle Mediator, as shown in Figure 44-19.

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

    Figure 44-19 readFile Service Connected to the LookupMultiplevaluesMediator Oracle Mediator

    Description of Figure 44-19 follows
    Description of "Figure 44-19 readFile Service Connected to the LookupMultiplevaluesMediator Oracle Mediator"

  6. 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:

  1. From the Component Palette, select SOA.

  2. Select File Adapter and drag it to the External References swimlane.

    The Adapter Configuration wizard Welcome page is displayed.

  3. Click Next.

    The Service Name page is displayed.

  4. In the Service Name field, enter writeFile and then click Next.

    The Adapter Interface page is displayed.

  5. Click Define from operation and schema (specified later) and then click Next.

    The Operation page is displayed.

  6. Click Next.

    The Operation page is displayed.

  7. In the Operation Type field, select Write File.

  8. Click Next.

    The File Configuration page is displayed.

  9. In the Directory for Outgoing Files (physical path) field, enter the name of the directory where you want to write the files.

  10. In the File Naming Convention field, enter multivalue_%SEQ%.xml and click Next.

    The Messages page is displayed.

  11. Click Search.

    The Type Chooser dialog is displayed.

  12. Navigate to Type Explorer > Project Schema Files > output.xsd, and then select Root-Element.

  13. Click OK.

  14. Click Next.

    The Finish page is displayed.

  15. Click Finish.

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

    Figure 44-20 writeFile Reference in SOA Composite Editor

    Description of Figure 44-20 follows
    Description of "Figure 44-20 writeFile Reference in SOA Composite Editor"

  16. 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

  1. Connect the LookupMultiplevaluesMediator Oracle Mediator to the writeFile reference, as shown in Figure 44-21.

    Figure 44-21 LookupMultiplevaluesMediator Oracle Mediator Connected to the writeFile Reference

    Description of Figure 44-21 follows
    Description of "Figure 44-21 LookupMultiplevaluesMediator Oracle Mediator Connected to the writeFile Reference"

  2. Double-click the LookupMultiplevaluesMediator Oracle Mediator.

  3. To the right of the Transform Using field, click the icon.

    The Request Transformation Map dialog is displayed.

  4. Select Create New Mapper File and click OK.

    An Input_To_Output_with_multiple_values_lookup.xsl file is displayed in the XSLT Mapper.

  5. Drag and drop the imp1:Root-Element source element to the ns2:Root-Element target element.

    The Auto Map Preferences dialog is displayed.

  6. From the During Auto Map options list, deselect Match Elements Considering their Ancestor Names.

  7. Click OK.

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

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

    Description of Figure 44-22 follows
    Description of "Figure 44-22 imp1:Root-Element To ns2:Root-Element Transformation"

  8. In the Component Palette, select Advanced.

  9. Click DVM Functions.

  10. Drag and drop lookupValue1M in the center panel, as shown in Figure 44-23.

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

    Description of Figure 44-23 follows
    Description of "Figure 44-23 Adding lookupValue Function to imp1:Root-Element to ns2:Root-Element"

  11. Double-click the lookupvalue1M icon.

    The Edit Function-lookupValue1M dialog is displayed.

  12. To the right of the dvmLocation field, click Search.

    The SOA Resource Lookup dialog is displayed.

  13. Select multivalue.dvm and click OK.

  14. To the right of the sourceColumnName field, click Search.

    The Select DVM Column dialog is displayed.

  15. Select Longname and click OK.

  16. In the sourceValue column, enter the following:

    /imp1:Root-Element/imp1:Details/imp1:Longname.

  17. To the right of the targetColumnName field, click Search.

    The Select DVM Column dialog is displayed.

  18. Select Shortname and click OK.

  19. Click Add.

    A targetColumnName row is added.

  20. In the targetColumnName field, enter "Language".

  21. Click Add to insert another targetColumnName row.

  22. In the targetColumnName field, enter "Capital".

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

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

    Description of Figure 44-24 follows
    Description of "Figure 44-24 Edit Function-lookupValue Function Dialog: Multiple Value Lookup Use Case"

  23. Click OK.

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

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

    Description of Figure 44-25 follows
    Description of "Figure 44-25 Complete imp1:Root-Element To ns2:Root-Element Transformation"

  24. 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 Section 40.7.1.1.1, "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 Section 40.7.1, "Deploying 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 is displayed.