Creating Transformations with the XQuery Mapper

41 Creating Transformations with the XQuery Mapper

This chapter describes how to create, edit, and test XQuery transformations using the XQuery Mapper in JDeveloper. The XQuery Mapper enables you to transform data between various XML and non-XML types, enabling you to integrate heterogeneous applications rapidly. You can use the XQuery (.xqy) files created using XQuery Mapper as resources in Oracle BPEL Process Manager, Oracle Mediator, or Oracle Service Bus.

This chapter includes the following sections:

41.1 Introduction to the XQuery Mapper

The XQuery Mapper supports XQuery 1.0. The older XQuery 2004 is also supported.

The XQuery Mapper includes the following views:

XQuery Mapper Graphical View
XQuery Mapper Source Editor

Note:

The XQuery Mapper graphical view is not supported for XQuery 2004 files. Only the source view is supported for this older XQuery version.

When you create a new XQuery file, it opens in the graphical view by default. The graphical view can also be accessed by clicking the XQuery Mapper tab at the bottom of the XQuery map.

Figure 41-1 shows the graphical view of the XQuery mapper.

Figure 41-1 XQuery Mapper

Description of "Figure 41-1 XQuery Mapper"

The left pane of the XQuery Mapper includes the input sources or parameters for the XQuery function. If your XQuery file has multiple functions, you can choose the function to display using the toolbar over the mapper panes.

The right pane includes the target schema tree, which corresponds to the XQuery function's result type. The center pane helps you map the source and the target schema elements using XQuery functions.

41.1.1 About the Source and Target Trees

The left pane of the XQuery Mapper shows the source tree, and the right pane shows the target tree. Tree nodes can be XML elements, attributes, and some other XQuery constructs.

XML elements are identified by the <> icon. Attributes use a different icon, and attribute names are prefixed with the @ symbol, as they appear in an XPath expression. The element or attribute multiplicity is shown using the following standard suffixes:

?: Zero or one occurrence of an element/attribute.
+: One or more occurrences of an element/attribute.
*: Zero or more occurrences of an element/attribute.

The source tree shows the input sources or parameters for the selected XQuery function. The root level elements represent the input parameters for the function. If a root node is a complex element, then its child elements and attributes appear under the root node.

The target tree can include XML elements, attributes, and some programming control structures. The elements and attributes can appear in the following forms:

Grayed Font: An element that is part of the target schema, but not defined yet. Once you map a grayed element to a source element, it appears in normal font.
Normal Font: An element that either corresponds to an element constructor in the source, or copied implicitly from the source data.
Underlined Font: An element that is incompatible with the specified target schema. This element may appear because of an incorrect element name used in an element constructor, or because of a sequence assignment with an incorrect schema type.

The target tree can also contain programming control structures like If-Then-Else, Union operator, and comma operator:

If-Then-Else Operator: The If-Then-Else operator shows up as a node called Conditional. The Conditional node has nested branches for If Then and Else. You can choose the Make Conditional option from the context menu of a node to make it conditional.
Union Operator (and other sequence combining operators): These cannot be created in the graphical view of the XQuery Mapper. However, if the source view contains such an operator, it is represented in the target tree with a node called All, and the operands are represented as subnodes of the all node.
Comma Operator: The comma operator shows up as a node called List. The subnodes represent the comma-limited operands of the comma operator. You can choose the Clone option from the context menu of target tree node to apply a comma operator.

41.1.2 Using the XQuery Mapper Toolbar

The XQuery Mapper toolbar is located above the XQuery Mapper panes. The toolbar contains various tools to work with the graphical mapper. Figure shows the XQuery Mapper toolbar.

Figure 41-2 XQuery Mapper Toolbar

Description of "Figure 41-2 XQuery Mapper Toolbar"

The XQuery Mapper toolbar contains the following tools:

Function Selector: The function selector box is identified by a green icon with the letter f on it. You can use the Function Selector to select the function to display in the source pane. This is useful if your XQuery map contains multiple functions.
Add New Function: The Add New Function button is identified by the green plus (+) sign. Use Add New Function to add a new function to the XQuery map file.
Rename Function: The Rename Function button is to the right of the Add New Function button. Use the Rename Function button to rename a function in the XQuery map file.
Delete Function: The Delete Function is identified by a red cross (X) sign. Use Delete Function to delete a function from the XQuery map file.
Import Library Module: The Import Library Module button is to the right of the Delete Function button. Use Import Library Module to import a library XQuery function into the map. You must specify the library module files to be imported.
Mapping Mode: The XQuery mapper can use different mapping modes. These modes affect the XQuery expressions created when the user drags and drops a line from a source node to a target node. The next three buttons are used to select the corresponding mapping mode:
- Value Mapping: Constructs target XML elements and attributes from the input source, and copies the input source values, using XML constructors. For example:
  
  <ID>{fn:data($pParam1/ID)}</ID>
  
  The above code creates the ID element in the target from the ID element in the input source parameter.
  
  Value mapping is the default mapping mode.
- Overwrite Mapping: The XML elements from the input source parameters are copied to the result sequence. Any existing mapping are replaced with the new mapping. For example:
  
  {
  
  $pParam1/Items
  
  }
  
  The above code copies the Items subtree, together with its child elements and attributes, to the target tree.
- Append Mapping: This mode works like overwrite mapping, except that any existing mappings are not overwritten. New additional mapping are created.
See Using the XQuery Mapper for more information on using the mapping modes.
Show/Hide Target Type Differences: Use the Show/Hide Target Type Differences button to manage the visibility of XML elements and attributes in the right target tree. You can choose to hide elements and attributes that haven't been mapped yet.
Search: Use the Search field to search for elements, attributes, data types, and so on in the source and target trees. Use the Up and down arrows to look for the next and previous items respectively.

41.1.3 Using the Properties Window

The Properties window displays the XQuery expression for the node selected in the target tree. XQuery expressions created using drag and drop can be edited in the Properties window. The Properties window can also be used to create more complex XQuery expressions.

The Properties window is located below the XQuery Mapper, by default. If the Properties window is not visible, click Properties under the JDeveloper Window menu to display the Properties window.

Tip:

When working with the XQuery Mapper, you might want to move the Properties window from the bottom right hand corner of the screen to the bottom of the screen, directly below the mapper window. A larger Properties window makes it easy to edit XQuery expressions and view the variable tree.

You can directly edit the XQuery expression, for the selected target node, in the Properties window. You can also drag XQuery functions, constructs, and operators from the Components window into your XQuery expression in the Properties window. The Components window is located to the right of the XQuery Mapper, by default. If you cannot see the Components window, select Window > Components from the Oracle JDeveloper menu bar.

To save the changes, click the Commit button in the top left corner of the Properties window. The XQuery is recompiled, and the XQuery Mapper view is updated.

If you make an error when editing the XQuery expression, click Revert to mapper sources, in the top left area of the Properties window, to undo the changes and start again.

The Properties window also includes a variable tree on the left hand side. The variable tree shows all variables, both local variables and XQuery function parameters, that are visible in the current scope. The scope is determined by the node highlighted in the target tree pane. You can drag and drop nodes from the variable tree into your XQuery expression in the right pane.

Figure 41-3 shows the Properties window. The Properties window is highlighted in red. The comment node is shown selected in the target tree. The corresponding variable tree and XQuery expression (fn:data($pParam1/Comment)) appears in the Properties window.

Figure 41-3 Properties Window

Description of "Figure 41-3 Properties Window"

41.1.4 Using the Components Window

The Components window contains all the XQuery functions and operators that you can use in your XQuery maps. These functions and operators can be dragged and dropped to the center pane of the XQuery Mapper. You can also drag and drop a function onto a target tree node, if the target tree node has already been created using the Insert context menu option.

Note:

You can also drag functions and operators to an XQuery expression in the Properties window, as described in the preceding section.

When a function is dragged and dropped on an existing link between a source and target node, for example, it becomes a part of the expression corresponding to that link. Some functions without parameters must be dragged to an empty area of the center pane, and associated with a target node. Functions can also be chained together.

The Components window organizes the XQuery function and operators into the following categories:

XQuery Functions: Includes various categories of XQuery functions, like aggregate functions, date functions, mathematical functions, string functions, and so on.
XQuery Constructs: Includes standard XQuery constructs like If-Then-Else and FLWOR constructs.
XQuery Operators: Includes various categories of XQuery operators, like logical operators, node comparison operators, and so on.
User-Defined Functions: Includes all the functions that you have defined in the current XQuery map file, and any functions from imported library modules.
My Components: Includes your favorite components that you can add to this category. It also includes the recently used functions.

41.1.5 Source Editor

The source editor enables you to edit the XQuery map directly, and also allows you to perform tasks that cannot be directly performed in the graphical view.

Click the XQuery Source tab at the bottom left of the XQuery Mapper graphical view to display the source editor. Figure 41-4 shows the XQuery Mapper source editor.

Figure 41-4 XQuery Mapper Source Editor

Description of "Figure 41-4 XQuery Mapper Source Editor"

The XQuery source view provides code editing features like code highlighting, code completion, error highlighting, and code folding. You can also use Ctrl + click (click the left mouse button while holding down the Ctrl key) on a function name, variable name, schema, or schema element to navigate to the corresponding declaration for the function, variable, schema, or schema element respectively.

41.2 Creating an XQuery Map File

Use Oracle JDeveloper to create XQuery maps. XQuery maps are included in the project as .xqy files.

XQuery maps can be created as main modules and library modules. A main module is an executable XQuery file. A library module is used to group and store XQuery functions. When you import a library module into a main module, all functions in the library module become available in the main module.

41.2.1 How to Create an XQuery Main/Library Module

To create an XQuery Main/Library Module:

Click the File menu. Select one of the following:
- To create an XQuery main module, select New > XQuery File ver 1.0. The Create XQuery Map Main Module dialog box appears.
  
  Figure 41-5 Create Main Module Dialog
  
  Description of "Figure 41-5 Create Main Module Dialog"
- To create an XQuery library module, select New > XQuery Library ver 1.0. The Create XQuery Map Library Module dialog box appears.
  
  Figure 41-6 Create Library Module Dialog
  
  Description of "Figure 41-6 Create Library Module Dialog"
Under File Name, enter the name for the XQuery map file to be created. The file must have a .xqy extension.
Under Directory Name, specify the directory in which the map file should be created. This is usually the Transformations directory in your project folder. You can click the tree icon on the right to browse and select the directory of your choice.
If you are creating a library module, select the target namespace for the library module under Target Namespace URI. Optionally edit the Prefix for the namespace.

Every function defined in a library module automatically uses the library's target namespace.
Select Generate Function to create a function in the XQuery file. If you do not select this, an empty XQuery file is created, and you can add functions later.
Under Function Name, enter the name of the function to be created in the XQuery file.
If you are creating a main module, select these additional fields for the function:
- NS URI specifies the namespace for the function. NS URI is automatically populated. You can also select a different namespace.
- Prefix specifies the namespace prefix of the function. Prefix is populated automatically. You can also edit the suggested namespace prefix.
Add parameters for the function under the Sources section. To add a parameter, click the Add Source button identified by the green plus sign (+). The Function Parameter dialog box appears.

Figure 41-7 Function Parameter Dialog

Description of "Figure 41-7 Function Parameter Dialog"
Under Name, enter the name of the function parameter.
Select Set a Namespace to specify a namespace for the function parameter:

Under NS URI, select the namespace for the function parameter. The namespace prefix appears in the Prefix field. You can optionally edit this.
Under Sequence Type, click the button identified by the pencil icon to specify the data type for the parameter. The Function Parameter Type dialog box appears.

Figure 41-8 Function Parameter Type Dialog

Description of "Figure 41-8 Function Parameter Type Dialog"

Use the XML Schema tab to specify an XML schema type as the data type for the function parameter. The Untyped tab can be used to specify an untyped (non-XML schema based) form of the parameter. You use an XML schema type in this procedure.
In the Function Parameter Type dialog, click the button to the right of Schema Object Reference (identified by the tree icon) to select a schema object as the data type.

This brings up the Type Chooser dialog box. You can choose from Project Schema Files, XML Schema Simple Types, and schemas embedded in Project WSDL Files. Navigate to the desired XML type and click OK to close the Type Chooser dialog box.
In the Function Parameter Type dialog, the Possible Sequence Type Form, Schema Location, and Prefix are automatically populated depending on your choice of Schema Object Reference. Optionally change any values if required.
Under Occurrence, optionally change the multiplicity of the parameter. The resultant XQuery expression appears under Result XQuery Expression.
Click OK to close the Function Parameter Type dialog box.
Click OK to close the Function Parameter dialog box.
In the Create XQuery Map Main Module/Library Module dialog, specify the function's result data type under the Target section. Click the button, with the pencil icon, to the right of the Target field.

The Function Result Type dialog box appears. This dialog box is identical to the Function Parameter Type dialog box. Use instructions under Steps 12 to 14 to specify the function's result data type.
Click OK to close the Function Result Type dialog box.
In the Create XQuery Map Main Module/Library Module dialog box, under the Options section, select Generate XQuery version line to generate a standard line at the beginning of the XQuery file.

For example, the following line might be generated at the beginning of the file:

xquery version "1.0" encoding "utf-8";
Select Use schema type annotations to create a weak-typed XQuery file that uses type annotations in place of schema object references. This may improve the XQuery performance for certain scenarios.

If you deselect this option, XQuery generates a strong-typed XQuery file that can contain references to schema objects.

See Using Type Annotations to Improve XQuery Performance for more information on type annotations.
Click OK. The newly created XQuery map opens up in the XQuery Mapper graphical view. If you want to see the XQuery source editor, click XQuery Source.

41.3 Using the XQuery Mapper

This section contains the following topics:

41.3.1 How to Use Value Mapping to Copy a Leaf Element Value to a Target Leaf Element

To create a value map for a leaf element:

Make sure that Value Mapping mode is selected in the XQuery toolbar.
Select the source leaf element whose value needs to be copied.
Hold down the left mouse button, and drag the mouse pointer to the target leaf element. Release the left mouse button.

A solid line connecting the source and target leaf node appears. The source leaf element is now value-mapped to the target leaf element.

41.3.2 How to Use Overwrite Mapping to Copy an Element Subtree to the Target Tree

To create an overwrite map for an element subtree

Make sure that Overwrite Mapping mode is selected in the XQuery toolbar.
Select the source element. The element can have child elements, or can also be a leaf element.
Hold down the left mouse button, and drag the mouse pointer to the target element. Release the left mouse button.

The source element subtree gets copied to the specified location in the target tree. A solid line connects the root of the copied source subtree to the target subtree. If there are no type mismatches with the target schema, then the copied element and its child elements appear in normal font. If there is a mismatch, the elements show up in underlined font.

41.3.3 How to Use Append Mapping to Copy an Element Subtree to the Target Tree

To create an append map for an element subtree

Make sure that Append Mapping mode is selected in the XQuery toolbar.
Select the source element. The element can have child elements, or can also be a leaf element.
Hold down the left mouse button, and drag the mouse pointer to the target element. Release the left mouse button.

The source element subtree gets appended as the child of the selected element in the target tree. A solid line connects the root of the source subtree to the root of the appended subtree in the target. If there are no type mismatches with the target schema, then the copied element and its child elements appear in normal font. If there is a mismatch, the elements show up in underlined font.

41.3.4 How to Perform Multiple Value Mappings with One Drag and Drop Action

To create multiple value mapping with one drag and drop action

Make sure that Value Mapping mode is selected in the XQuery toolbar.
Select the non-leaf source element.
Hold down the left mouse button, and drag the mouse pointer to the target element. Release the left mouse button.
If the source and target elements have the same schema types, individual mappings are created for all the child elements of the source element and target element. A mapping is also created between the source and target element.

If an element has multiple occurrences, then a FLOWR cycle is automatically created for the element. For example, the code segment below copies each Item iteratively:
```
for $Item in $pParam1/Items/Item
            return <Item PartNum="{fn:data($Item/@PartNum)}">
                <ProductName>{fn:data($Item/ProductName)}</ProductName>
                <Quantity>{fn:data($Item/Quantity)}</Quantity>
                <Price>{fn:data($Item/Price)}</Price>
                <Currency>{fn:data($Item/Currency)}</Currency>
                   </Item> 
```

41.4 Using XQuery Functions

You can add XQuery functions to your existing XQuery map. The Components window contains a list of XQuery functions that you can drag and drop into the source editor or the center pane of the XQuery mapper.

The Components window also includes a set of XQuery constructs, like FLWOR, and XQuery operators, like logical AND. These constructs and operators can only be dragged and dropped into the source editor.

41.4.1 How to Add an XQuery Function in the XQuery Mapper

You can drag and drop an XQuery function from the Components window to the center pane of the XQuery mapper.

41.4.1.1 To add an XQuery function:

Make sure that the Components Window is visible. The default location is the top right hand corner of Oracle JDeveloper.

If the Components Window is not visible, select Components from the Window menu.
In the Component Window, select the XQuery Functions page.
Click the Category that contains your function. For example, to add the concat function, click String Functions.
Drag the desired function from the Components window to the center pane of the XQuery mapper. When you drag the function to the center pane, the output of the function connects to different target nodes, as you move along.

Figure 41-9 shows a function being dragged to the center pane of the XQuery Mapper.

Figure 41-9 Dragging a Function to the Center Pane of the XQuery Mapper

Description of "Figure 41-9 Dragging a Function to the Center Pane of the XQuery Mapper"
Drop the function on the center pane when the function output is shown connected to the desired target node.

Note:

You can also drop a function to an existing map line in the center pane of the XQuery mapper.

The function gets connected to both the source (input) and target (output) nodes.
If the function requires additional input parameters, then a Warning icon appears on the function icon. Drag a line from a source node to the left end of the function to specify an input parameter.
Repeat the previous step for any more source nodes that you must add as input parameters.

41.4.1.2 To edit a function's parameters:

Click the function icon in the center pane. The expression corresponding to the function appears in the Properties window.

The Properties window is located at the lower right-hand corner of Oracle JDeveloper, by default. If the Properties window does not appear, click Properties under the Window menu to display the Properties window. You can optionally choose to drag the Properties window to any convenient location within the JDeveloper window. You can also resize the Properties window, as desired.
Edit the expression that appears in the right pane of the Properties window.

The left pane of the Properties window shows the variable tree that includes all variables visible in the current scope. You can drag and drop variables to the expression on the right to help build your function definition.
Click Commit at the top left corner of the Properties window to save the changes. Alternatively, click Revert to mapper sources to revert changes made in the Properties window.

41.5 Using Library Modules

How to Create an XQuery Main/Library Module discusses the process of creating a library module file. To use a library module, you can import the library module into the main module. This makes all the library module functions available in the main module.

41.5.1 How to Import a Library Module

You can import a library module from the source editor of your main module.

To import a library module:

Make sure that your XQuery main module map file is open in the XQuery Mapper.
Click the XQuery Source tab at the bottom left of the XQuery Mapper window to switch to the source editor.
Right-click anywhere in the source editor window. A context menu appears.
Select Import library module from the context menu. The Select XQuery Library Files dialog appears.
Browse and select the XQuery library module file to be imported. Click OK.

An import statement, corresponding to the library module, is added to the main module source view.

41.6 Working with Zones and FLWOR Constructs

You can create FLWOR (For, Let, Where, Order By, Return) expressions in the Source View. FLWOR expressions are represented as zones in the XQuery Mapper target tree.

Zones identify areas in the target tree that are associated with FLOWR constructs or If-Then-Else conditional constructs. Zones are represented by yellow brackets to the left of the target tree.

If you move the mouse over a yellow line representing a zone, the line turns blue. For FLWOR zones, additional buttons appear, corresponding to the For-Let, Where, and Order By clauses. Figure 41-10 shows a sample XQuery with zones.

Figure 41-10 Zones and FLWOR Zones in XQuery Mapper

Description of "Figure 41-10 Zones and FLWOR Zones in XQuery Mapper"

41.6.1 How to Edit a FLWOR Construct

You can edit a FLWOR construct directly in the source view. You can also perform limited editing of a FLOWR construct in the XQuery Mapper.

To edit a FLWOR construct in XQuery Mapper:

Click on the yellow bracket representing the FLWOR zone to select the zone. The yellow bracket turns blue, and additional buttons appear. These buttons correspond to the different clauses of the FLWOR construct.
Click the FL button to edit the For-Let properties for the FLWOR construct. The Properties window shows the For-Let clause properties.

Click the Help icon in the Properties window to display help on editing the For-Let properties.
Click the W button to edit the Where properties for the FLWOR construct.

The Properties window enables you to directly edit the Where expression. You can also drag and drop variables from the left pane of the Properties window.
Click the O button to edit the Order By properties for the FLWOR construct.

The Properties window enables you to directly edit the Order By expression. You can also drag and drop variables from the left pane of the Properties window.

41.7 Using Type Annotations to Improve XQuery Performance

When an XQuery is run, the XQuery engine performs schema type validations in the XQuery file before running the XQuery. This may cause performance overheads for certain applications.

If you must optimize your XQuery for performance, you can use type annotations to specify schema information in the XQuery file. Type annotations enable you to hide the schema type definitions from the XQuery execution engine. The schema definitions are still visible to the Xquery Mapper, which enables you to edit your XQuery map in the usual fashion.

To use type annotations in your XQuery file, select Use Schema Type Annotations in the Create XQuery Map Main/Library Module dialog when creating a new XQuery file. See How to Create an XQuery Main/Library Module for more information on creating an XQuery file.

Type annotations, in an XQuery file, look similar to standard XQuery comments. While standard XQuery comments are delimited by the parentheses and colon, type annotations use parentheses and double colons. So, for example:

(: This is an XQuery comment :)
(:: This is a type annotation ::)

An XQuery file that uses type annotations has the following version annotation at the beginning of the file, immediately following the version declaration:

(:: OracleAnnotationVersion "1.0" ::)

The following example compares a few XQuery constructs with and without the type annotations.

Schema import (without type annotation):

import schema namespace ns1="http://www.oracle.com/pcbpel/po" at "../Schemas/PurchaseOrder.xsd";

Schema import (with type annotation):

declare namespace ns1="http://www.oracle.com/pcbpel/po";
(:: import schema at "../Schemas/PurchaseOrder.xsd" ::)

Variable declaration (without type annotation):

declare variable $test_param as schema-element(ns1:PurchaseOrder) external;

Variable declaration (with type annotation):

declare variable $test_param as element() 
(:: schema-element(ns1:PurchaseOrder) ::) external;

41.8 Testing Your XQuery Map

You can test run your XQuery map from within Oracle JDeveloper. Testing the XQuery at design time helps prevent runtime errors.

41.8.1 How to Test an XQuery Map

You must be in the Source Editor view to test the XQuery map.

To Test an XQuery Map:

Make sure that the XQuery main module is open in the XQuery Mapper.
If you are not in the Source Editor view, click the XQuery Source tab at the bottom of the XQuery Mapper window to switch to the source editor.
Right-click anywhere in the source editor. Select Run XQuery from the context menu that appears.

The Run XQuery dialog appears. Figure 41-11 shows the Run XQuery dialog.

Figure 41-11 Run XQuery Dialog

Description of "Figure 41-11 Run XQuery Dialog"
Specify values for all source variables that appear in the Source variables section.

For simple data types, you can specify a value directly under the Value field. If your source variable uses a complex schema, click the ellipses (. . .) button to bring up the Edit Variable dialog. You can use an existing XML file to specify test data for the variable, or create an XML file with test data. Click Help for additional help with completing the Edit Variable dialog.
Select Open result in a new tab in JDeveloper if you want to use a new tab to display test results. Select Save target file to save the result file. You must select one, or both, of these options.
Click the Save icon to the right of Target filename to specify a result file into which the result data is saved.

You must specify a Target filename even if you haven't selected Save target file in the preceding step.
Optionally select Autosave configuration to automatically save the configuration settings when the XQuery is run. The next time you try to run the XQuery, the configuration settings are retrieved.
If you want to save the settings made in the Run XQuery dialog, click Save Configuration.
If you want to delete any previously saved configuration settings, click Delete Configuration.
Click Run to run the XQuery.