This chapter provides an overview of domain value maps and how they are used in Service Bus services to associate terms used by different domains to describe like objects. It also describes how to create domain value maps in Service Bus projects.
This chapter includes the following sections:
For more in-depth information about domain value maps, see "Working with Domain Value Maps" in Developing SOA Applications with Oracle SOA Suite.
A domain value map associates values used by one domain for a specific field to the values used by other domains for the same field, providing the capability to map values across vocabularies or systems. For example, you can map country codes, city codes, currency codes, and so on. You might have several domain value maps for one Service Bus project, depending on the number of fields that require mapping. Domain value maps are similar to cross references, but they are based on a static definition. You create and populate domain value maps in the design time, and deploy them to the runtime. Domain value map data is not changed by runtime activities as it is for cross references, but rather the domain value maps are used for lookups only.
Domain value maps can be used across Oracle SOA Suite components. In Service Bus, you can create domain value maps in both JDeveloper and the Oracle Service Bus Console.
In the Service Bus message flow, you can reference domain value maps from XQuery expressions and XSLT transformations using a set of DVM functions to lookup values at runtime based on information in incoming messages. Use these functions so Service Bus knows how to map data coming in from one system to data being sent to another system.
You can access the DVM functions in JDeveloper from the XSLT mapper, the XQuery mapper, and the expression editors. In the Oracle Service Bus Console, the functions are available from the expression and condition editors. For information about the Service Bus DVM functions, see Domain Value Map Functions.
You can create domain value maps in a Service Bus project in JDeveloper, and then use them in XQuery expressions in pipelines and split-joins to map objects between external systems. Since a domain value map typically defines the mapping for only one field, a pipeline or split-join can reference multiple domain value maps.
Create and configure domain value maps using the Create Domain Value Map(DVM) File dialog in 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.
When you create a domain value map, you can specify a name for up to two domains whose values are being mapped, along with the value for each domain. Once you create the map, you can add more domains and values.
To create a domain value map in JDeveloper:
The Create Domain Value Map(DVM) File dialog appears.
The location must be within the directory structure of the current application.
These are the column names for the domain value map, and each represents the same field in different domains.
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.
The Domain Value Map Editor appears with the new domain value map displayed.
If you are using the Oracle Service Bus Console, you can create new domain value maps or you can upload domain value maps that you first created in JDeveloper into a DVM resource.
When you create a DVM, you define the names of up to two end systems that are sharing the data along with the corresponding values for the field covered by the domain value map. After you create the map, you can define additional domains and values in the DVM Definition Editor.
Before you Begin
If you are uploading a domain value map file already created in JDeveloper, as described in Creating Domain Value Maps in JDeveloper, make sure the file is available on your system.
To create a DVM resource in the console:
The Create DVM dialog appears.
To upload an existing domain value map file, click Browse next to the File Upload field and then navigate to and select the file you created in JDeveloper.
The Resource Name field is automatically populated with the file name minus the file extension. You can change this name.
To create a new domain value map, enter a unique name for the DVM resource.
The new domain value map appears on the DVM Definition Editor.
You can define additional domains to map, which are represented as columns in the domain value map. Each new domain can contain values that are either to be included in the lookups at runtime or to be used only to qualify the mapping. Domain 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:
The Add Domain dialog appears.
This field is enabled only if you selected Enable a Qualifier for lookup.
Domain values are displayed in rows in the domain value map, with each row containing the value 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:
A new row appears beneath the existing rows in the Map Table.
If you are using the Oracle Service Bus Console, use the following procedure to modify an existing domain value map.
To edit a domain value map in the console:
In the Project Navigator, expand the project and folders containing the domain value map to edit.
Click the DVM resource name.
To modify the source file, do the following:
Click Edit Source in the toolbar.
The Edit Source dialog appears.
To browse to and select a new cross reference file to upload, click Browse.
To modify the contents of the file, update the code directly in the Contents section of the dialog.
To add domains to the map, see How to Add Domains to a Domain Value Map.
To add domain values, see How to Add Domain Values to a Domain Value Map.
To edit a domain, select the domain in the Map Table and click Edit. In the Update Domain dialog, make any of the changes describe in How to Add Domains to a Domain Value Map.
To change a value, double-click the value name in the Map Table and enter the new value.
In the DVM Definition Editor toolbar, click Save.
To end the session and deploy the configuration to the runtime, click Activate.
If any resources reference the resource you want to delete, remove those references before deleting the resource. You can delete the resource even if it is referenced by other resources, though this might result in conflicts due to unresolved references to the deleted resource.
Before deleting a domain value map, check for resources or dependencies. In the Oracle Service Bus Console, open the DVM in the DVM Definition Editor and click the References icon in the upper right to find out whether any services are using it. In JDeveloper, right-click the DVM and select Explore Dependencies.
To delete a DVM resource:
Use the DVM XPath functions provided with Service Bus to define the domain value lookups that will occur during runtime. The XPath functions provide a variety of ways to perform a lookup for either a single value or multiple values. These XPath functions can be used in the Expression Builder to create an expression or in the XSLT Mapper to create transformations. You can access the Expression Builder dialog through several pipeline activities and split-join operations.
For information about the DVM functions provided with Service Bus, see Domain Value Map Functions. For general information and instructions on using functions in the Oracle Service Bus Console expression and condition editors, see Building Expressions in the Editor Workspace Text Fields.
For information, examples, and instructions on using DVM functions in JDeveloper, see "Using Domain Value Map Functions" in Developing SOA Applications with Oracle SOA Suite. This information is also helpful when working in the Oracle Service Bus Console.