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

Part Number E10224-20
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
PDF · Mobi · ePub

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

47.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 47-1 shows a point-to-point mapping for cities between two domains:

Table 47-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 Chapter 48, "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 49, "Working with Cross References."

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

47.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 47-2.

Table 47-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 47-3, the mappings are also qualified with a state name.

Table 47-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.

47.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 47-3, the state qualifier would probably be 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 47-1 describes the steps of a hierarchical lookup performed for the following lookup (based on the values in Table 47-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 47-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 47-1 Hierarchical Lookup Example

Description of Figure 47-1 follows
Description of "Figure 47-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 47-4 provides a summary of these steps.

Table 47-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


47.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 47-5.

Table 47-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


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

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

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

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

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

  5. In the Description field, enter a description for the domain value map. This field is optional.

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

  7. 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 47-2.

    Figure 47-2 Populated Create Domain Value Map File Dialog

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

  8. Click OK.

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

47.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 Application Navigator, as shown in Figure 47-3.

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

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

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

Example 47-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>

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

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

  1. If the map file is not open in the Domain Value Map Editor, double-click the DVM file in the Application Navigator.

  2. In the Map Table, click Add and then select Add Domain.

    The Create Domain dialog appears.

  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.

    Tip:

    For more information about qualifier domains and qualifier order, see Section 47.1.1.1, "Qualifier Domains" and Section 47.1.1.2, "Qualifier Hierarchies.".

  5. 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 47-4 Domain Value Map - Create Domain Dialog

    Description of Figure 47-4 follows
    Description of "Figure 47-4 Domain Value Map - Create Domain Dialog"

  6. Click OK.

    A new column appears in the Map Table.

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

  1. In the Domain Value Map Editor, select the name of the domain you want to modify.

  2. Click Edit Domain/Values.

    The Edit Domain dialog appears.

    Figure 47-5 Domain Value Map - Edit Domain Dialog

    Description of Figure 47-5 follows
    Description of "Figure 47-5 Domain Value Map - Edit Domain Dialog"

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

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

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

  2. Enter the values for each domain in the new row.

  3. Repeat the above steps to create additional rows. When you are done making changes, click Save All on the Oracle JDeveloper toolbar.

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

  1. In the Domain Value Map Editor, select the row containing the values you want to modify.

  2. Click Edit Domain/Values.

    The Edit Domain Values dialog appears.

    Figure 47-6 Domain Value Map - Edit Domain Values

    Description of Figure 47-6 follows
    Description of "Figure 47-6 Domain Value Map - Edit Domain Values"

  3. Modify any of the fields on the dialog, and then click OK.

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

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

47.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 47-2 shows an example of dvm:lookupValue function syntax.

    Example 47-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 47-3 provides an example of dvm:lookupValue function use.

    Example 47-3 dvm:lookupValue Function Use

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

    Example 47-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 47-5 provides another example of dvm:lookupValue function use.

    Example 47-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.

47.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 47-6 provides details.

Example 47-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 47-7 shows an example of dvm:lookupValue1M function use.

Example 47-7 dvm:lookupValue1M Function Use

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

The result is shown in Example 47-8.

Example 47-8 dvm:lookupValue1M Function Result

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

47.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 Chapter 40, "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 47-7.

    Figure 47-7 Domain Value Map Functions in the Component Palette

    Description of Figure 47-7 follows
    Description of "Figure 47-7 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 appears, as shown in Figure 47-8.

    Figure 47-8 Edit Function – lookupValue1M Dialog

    Description of Figure 47-8 follows
    Description of "Figure 47-8 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 47-9.

    Figure 47-9 Populated Edit Function – lookupValue1M Dialog

    Description of Figure 47-9 follows
    Description of "Figure 47-9 Populated Edit Function – lookupValue1M Dialog"

  8. Click OK.

    The XSLT Mapper appears with the lookupValue1M function icon.

  9. From the File menu, select Save All.

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

47.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 20.3.2.10, "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 47-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 47-10 Domain Value Map Functions in the Expression Builder Dialog

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

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

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

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

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

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

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

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

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

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

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

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

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

  9. Click Add and then select Add Column.

    The Create DVM Column dialog appears.

  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 Domain Values.

    Repeat this step to add two more rows.

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

    Table 47-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 47-11.

    Figure 47-11 UnitsOfMeasure Domain Value Map

    Description of Figure 47-11 follows
    Description of "Figure 47-11 UnitsOfMeasure Domain Value Map"

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

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

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

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

    The Operation page appears.

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

    The File Directories page appears.

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

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

    The File Polling page appears.

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

    The Messages page appears.

  10. Click Search.

    The Type Chooser dialog appears.

  11. Click Import Schema File.

    The Import Schema File dialog appears.

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

  17. Click Finish.

  18. From the File menu, click Save All.

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

    Figure 47-12 ReadOrders Service in the SOA Composite Editor

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

47.5.1.4 Task 4: How to Create ProcessOrders Mediator Component

To create a 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 appears.

  2. In the Name field, enter ProcessOrders.

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

  4. Click OK.

    A 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 47-13.

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

    Figure 47-13 ReadOrders Service Connected to the ProcessOrders Mediator

    Description of Figure 47-13 follows
    Description of "Figure 47-13 ReadOrders Service Connected to the ProcessOrders Mediator"

  6. From the File menu, select Save All.

47.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 appears.

  3. Click Next.

    The Service Name page appears.

  4. In the Service Name field, enter WriteCommonOrder.

  5. Click Next.

    The Operation page appears.

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

  7. Click Next.

    The File Configuration page appears.

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

  10. Click Search.

    The Type Chooser dialog appears.

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

  12. Click OK.

  13. Click Next.

    The Finish page appears.

  14. Click Finish.

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

    Figure 47-14 WriteCommonOrder Reference in the SOA Composite Editor

    Description of Figure 47-14 follows
    Description of "Figure 47-14 WriteCommonOrder Reference in the SOA Composite Editor"

  15. From the File menu, select Save All.

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

    Figure 47-15 ProcessOrders Mediator Connected to the WriteCommonOrder Reference

    Description of Figure 47-15 follows
    Description of "Figure 47-15 ProcessOrders 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 appears.

  4. Select Create New Mapper File and click OK.

    A listOfOrder_To_listOfOrder.xsl file appears in the XSLT Mapper.

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

    The Auto Map Preferences dialog appears.

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

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

    Description of Figure 47-16 follows
    Description of "Figure 47-16 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 47-17.

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

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

  11. Double-click the lookupvalue icon.

    The Edit Function-lookupValue dialog appears.

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

    The SOA Resource Lookup dialog appears.

  13. Select UnitsofMeasure.dvm and click OK.

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

    The Select DVM Column dialog appears.

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

  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 47-18.

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

    Description of Figure 47-18 follows
    Description of "Figure 47-18 Edit Function-lookupValue Function Dialog: Hierarchical Lookup Use Case"

  28. Click OK.

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

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

    Description of Figure 47-19 follows
    Description of "Figure 47-19 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.

47.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 43.7.1.1, "Creating an Application Server Connection."

47.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 43.7.1, "How to Deploy a Single SOA Composite in Oracle JDeveloper."

47.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 43.7.1, "How to Deploy a Single SOA Composite in Oracle JDeveloper."

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

  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.

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

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

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

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

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

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

  11. Click Add and then select Add Row.

    Repeat this step to add two more rows.

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

    Table 47-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 47-20.

    Figure 47-20 Multivalue Domain Value Map

    Description of Figure 47-20 follows
    Description of "Figure 47-20 Multivalue Domain Value Map"

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

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

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

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

    The Adapter Interface page appears.

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

    The Operation page appears.

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

    The File Directories page appears.

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

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

    The File Polling page appears.

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

    The Messages page appears.

  11. Click Search.

    The Type Chooser dialog appears.

  12. Click Import Schema File.

    The Import Schema File dialog appears.

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

  18. Click Finish.

  19. From the File menu, select Save All.

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

    Figure 47-21 readFile Service in the SOA Composite Editor

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

47.6.1.4 Task 4: How to Create the LookupMultiplevaluesMediator Mediator

To create the LookupMultiplevaluesMediator 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 appears.

  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 47-22.

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

    Figure 47-22 readFile Service Connected to the LookupMultiplevaluesMediator Mediator

    Description of Figure 47-22 follows
    Description of "Figure 47-22 readFile Service Connected to the LookupMultiplevaluesMediator Mediator"

  6. From the File menu, select Save All.

47.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 appears.

  3. Click Next.

    The Service Name page appears.

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

    The Adapter Interface page appears.

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

    The Operation page appears.

  6. Click Next.

    The Operation page appears.

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

  8. Click Next.

    The File Configuration page appears.

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

  11. Click Search.

    The Type Chooser dialog appears.

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

  13. Click OK.

  14. Click Next.

    The Finish page appears.

  15. Click Finish.

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

    Figure 47-23 writeFile Reference in SOA Composite Editor

    Description of Figure 47-23 follows
    Description of "Figure 47-23 writeFile Reference in SOA Composite Editor"

  16. From the File menu, select Save All.

47.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 Mediator to the writeFile reference, as shown in Figure 47-24.

    Figure 47-24 LookupMultiplevaluesMediator Mediator Connected to the writeFile Reference

    Description of Figure 47-24 follows
    Description of "Figure 47-24 LookupMultiplevaluesMediator Mediator Connected to the writeFile Reference"

  2. Double-click the LookupMultiplevaluesMediator Mediator.

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

    The Request Transformation Map dialog appears.

  4. Select Create New Mapper File and click OK.

    An Input_To_Output_with_multiple_values_lookup.xsl file appears 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 appears.

  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 47-25.

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

    Description of Figure 47-25 follows
    Description of "Figure 47-25 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 47-26.

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

    Description of Figure 47-26 follows
    Description of "Figure 47-26 Adding lookupValue Function to imp1:Root-Element to ns2:Root-Element"

  11. Double-click the lookupvalue1M icon.

    The Edit Function-lookupValue1M dialog appears.

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

    The SOA Resource Lookup dialog appears.

  13. Select multivalue.dvm and click OK.

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

    The Select DVM Column dialog appears.

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

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

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

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

  23. Click OK.

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

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

    Description of Figure 47-28 follows
    Description of "Figure 47-28 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.

47.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 43.7.1.1, "Creating an Application Server Connection."

47.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 43.7.1, "How to Deploy a Single SOA Composite in Oracle JDeveloper."

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