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.

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.

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.

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.

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.

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.

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.

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.

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.

1. 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"
2. Under File Name, enter the name for the XQuery map file to be created. The file must have a .xqy extension.
3. 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.
4. 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.

5. 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.
6. Under Function Name, enter the name of the function to be created in the XQuery file.
7. 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.

8. 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"
9. Under Name, enter the name of the function parameter.
10. 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.

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

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

13. 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.
14. Under Occurrence, optionally change the multiplicity of the parameter. The resultant XQuery expression appears under Result XQuery Expression.
15. Click OK to close the Function Parameter Type dialog box.
16. Click OK to close the Function Parameter dialog box.
17. 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.

18. Click OK to close the Function Result Type dialog box.
19. 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";

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

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

1. Make sure that Value Mapping mode is selected in the XQuery toolbar.
2. Select the source leaf element whose value needs to be copied.
3. 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.

1. Make sure that Overwrite Mapping mode is selected in the XQuery toolbar.
2. Select the source element. The element can have child elements, or can also be a leaf element.
3. 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.

1. Make sure that Append Mapping mode is selected in the XQuery toolbar.
2. Select the source element. The element can have child elements, or can also be a leaf element.
3. 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.

1. Make sure that Value Mapping mode is selected in the XQuery toolbar.
2. Select the non-leaf source element.
3. 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> 

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

1. Make sure that your XQuery main module map file is open in the XQuery Mapper.
2. Click the XQuery Source tab at the bottom left of the XQuery Mapper window to switch to the source editor.
3. Right-click anywhere in the source editor window. A context menu appears.
4. Select Import library module from the context menu. The Select XQuery Library Files dialog appears.
5. 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.

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

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

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

1. Make sure that the XQuery main module is open in the XQuery Mapper.
2. 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.
3. 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"
4. 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.

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

7. 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.
8. If you want to save the settings made in the Run XQuery dialog, click Save Configuration.
9. If you want to delete any previously saved configuration settings, click Delete Configuration.
10. Click Run to run the XQuery.