Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Service Bus
11g Release 1 (11.1.1.3)
E15866-01
  Go To Table Of Contents
Contents

Previous
Previous
 
Next
Next
 

6 Transforming Data Using XQuery Mapper

You can use the graphical interface of XQuery Mapper to create data transformations, by mapping elements in source schemas to elements in a target schema. XQuery Mapper generates an XQuery, which is saved as an .xq file.

The procedure to transform data using XQuery Mapper is described in the following sections:

6.1 Launching XQuery Mapper

In Oracle Enterprise Pack for Eclipse, open the XQuery transformation perspective by choosing Window > Open Perspective > XQuery Transformation from the Eclipse menu.

The XQuery transformation perspective launches automatically when you open an XQuery file. If, however, XQuery Mapper is open and no XQuery file is open, you must launch the XQuery transformation perspective manually.

6.2 Importing the XQuery Mapper Sample Project

The XQuery Mapper sample project includes sample schema and XML files, which you can use to create XQuery transformations as described in Chapter 7, "Examples: Data Transformation Using XQuery Mapper."

Use the following procedure to import the sample project.

  1. From the Eclipse menu bar, choose File > Import.

  2. In the Import window, select General > Existing Projects into Workspace, then click Next.

  3. In the Select root directory field, click Browse, then select the following folder: OSB_ORACLE_HOME/eclipse/plugins/com.bea.alsb.common.mapper_version/samples, and click OK.

  4. In the Import window, select Copy projects into workspace, and click Finish.

  5. Enter a name for your sample project and click Finish.

    The samples project is created and displayed in the Project Explorer view. The project contains the following folders:

    • schemas folder: Contains the XML schema (.xsd) files of the sample project.

    • XML folder: Contains test XML files required by some of the samples.

    • XQueryTransformations folder: This is the folder in which you will create the XQuery files for the samples.

To learn more about creating projects and importing the files you need for those projects, see the following topics:


Note:

You can import project-specific XML schemas, Web Service Definition Language (WSDL) files, and Message Format Language (MFL) files from any location. Before you import the files, it is recommended that you create a folder structure that meets your business needs. For more information, see Section 6.4, "Importing and Creating Schema Files."

6.3 Creating an XQuery Mapper Project

To create an XQuery Mapper project:

  1. Switch to the XQuery transformation perspective by choosing Window > Open Perspective > XQuery Transformation.

  2. Choose File > New > Project.

    The New Project wizard is displayed.

  3. Choose General > Project and click Next.

  4. Enter a name for the project.

  5. Ensure that the Use default location check box is selected.

  6. Click Finish.

6.4 Importing and Creating Schema Files

Schema files can be created in and imported from any location. The following schema types are supported:

6.4.1 Importing XML Schemas and MFL Files

To import schemas and MFL files:

  1. Switch to the XQuery transformation perspective by choosing Window > Open Perspective > XQuery Transformation.

  2. In the Navigator view, select the project into which you want to import the XML schema or MFL file.

  3. Choose File > Import.

    The Import wizard is displayed.

  4. You can import XML schemas and MFL files from a variety of sources. Select the appropriate source and click Next.

  5. Browse for and select the required file, and click Finish.

After the schemas files or MFL files are imported, they are available in the New XQuery Transformation wizard.

The following figure shows how the imported XML schemas are displayed in the New XQuery Transformation wizard.

Figure 6-1 New XQuery Transformation

Description of Figure 6-1 follows
Description of "Figure 6-1 New XQuery Transformation"

6.4.2 Creating XML Schemas

You can create XML schemas by using the XML Schema Editor.

  1. Switch to the XQuery transformation perspective by choosing Window > Open Perspective > XQuery Transformation.

  2. In the Navigator view, select the project in which you want to create the schema files.

  3. Select File > New > Other.

    The New screen is displayed.

  4. Expand the XML node.

  5. Select XML Schema and click Next.

  6. Select the parent folder in which you want to create the schema file.

  7. Enter a name for the schema file and click Finish.

The schema file is created in the specified project. You can now specify the details of the schema and save the file.

For information about using the XML Schema Editor, see Introduction to the XSD Editor at http://www.eclipse.org/webtools/community/tutorials/XMLSchemaEditor/XMLSchemaEditorTutorial.html.

6.4.3 Creating XML Files from XML Schemas

To create XML files from schemas:

  1. Switch to the XQuery transformation perspective by choosing Window > Open Perspective > XQuery Transformation.

  2. In the Navigator view, select the project in which you want to create the schema files.

  3. Select File > New > Other.

    The New screen is displayed.

  4. Expand the XML node.

  5. Select XML and click Next.

    The Create XML File dialog box is displayed.

  6. Select the Create XML file from an XML schema file option and click Next.

  7. Select the parent folder in which you want to create the XML file.

  8. Enter a name for the XML file and click Next.

  9. Select the XML schema based on which you want to create the XML file and click Next.

  10. Select the root element of the XML file and click Finish.

The XML file is created in the specified folder. You can now specify the details of the file and save it.

For information about using the XML Editor, see Creating XML files Tutorial at http://www.eclipse.org/webtools/community/tutorials/XMLWizards/XMLWizards.html.

6.4.4 Creating WSDL Files

To create a WSDL file:

  1. Switch to the XQuery transformation perspective by choosing Window > Open Perspective > XQuery Transformation.

  2. In the Navigator view, select the project in which you want to create the WSDL files.

  3. Select File > New > Other.

    The New wizard is displayed.

  4. Expand the XML node, select WSDL, and click Next.

  5. Select the parent folder in which you want to create the WSDL file.

  6. Enter a name for the WSDL file and click Next.

  7. Enter the target namespace and prefix of the WSDL file.

  8. If required, select the Create WSDL Skeleton check box.

  9. Select the protocol and the binding option and click Finish.

The WSDL file is created in the specified project.

For information about using the WSDL Editor, see Introduction to the WSDL Editor at: http://www.eclipse.org/webtools/community/tutorials/WSDLEditor/WSDLEditorTutorial.html.

6.4.5 Creating MFL Files

You can create MFL files by using the Format Builder tool. In Eclipse, in the Oracle Service Bus perspective, choose (File > New > MFL.

6.5 Selecting Source and Target Data Types

Before you create a data transformation, you must define the source target types and a target data type. The source and target types can be non-XML, XML, and simple data types.

  1. Select the project for which you want to select source and target data types.

  2. Right-click and choose New > XQuery Transformation.

    The New XQuery Transformation wizard is displayed.

  3. Enter a name for the .xq file.

  4. Click Next.

    The Source Types dialog box is displayed.

  5. In the Available Source Types pane select the source data types.

    • If the source is XML data, choose XML.

    • If the source is MFL data, choose Non-XML.

    • If the source data is of standard types, such as boolean, String, and int, then choose Simple.

  6. Select the required source data elements.


    Note:

    For schemas to be displayed in the Available Source Types and Available Target Types pane, the XML and non-XML files that contain these schemas must first be imported into or created in Eclipse.

    The Available Source Types and Available Target Types panes show only schemas that exist in the schemas folder of the XQuery Transformation project. If you prefer to keep your schemas in any other folder, you must specify the path to that folder in the XMLBeans settings for the project (by choosing Project > Properties, the XMLBeans page, and then the Source Paths tab).


    For example, to add input data from schemas/Dates.xsd, select the date element in the schema as the input element and click Add, as shown in the following figure.

    Figure 6-2 Selecting Source Types

    Description of Figure 6-2 follows
    Description of "Figure 6-2 Selecting Source Types"

    The elements and attributes that make up the selected element are displayed in the Selected Source Types pane.

  7. After selecting the required source types, click Next.

    The Target Types dialog box is displayed.

  8. In the Available Target Types pane, select the target data type, and click Add.

    The elements and attributes that make up the selected element are displayed in the Selected Target Type pane.


    Note:

    You can specify only one target data type.

  9. Click Finish.

The .xq file is displayed in the Design view. It shows the source and target data types that you selected.

6.6 Creating Data Transformations

You can perform the following types of data transformations:

6.6.1 Creating Basic Element Transformations

Basic element transformation involves mapping a source element to a target element. The source and target elements may have the same name, type, or scope.

The following are some examples of the types of basic element transformation that you can perform:

  • Element to element: A source element is mapped to a target element.

  • Element combination: Multiple source elements are combined to create a single target element.

  • Element explosion: XQuery string functions are exploded from a single source element to multiple target elements.

6.6.1.1 Prerequisite

The XQuery file is created as described in Section 6.5, "Selecting Source and Target Data Types"

6.6.1.2 Creating Element-to-Element Links

To create element-to-element links:

  1. Select the project for which you want to create element-to-element links, and open the XQuery file in which the transformation must be stored.

  2. Drag the required element from the Source pane to the target element in the Target pane.

    For example, to create a link between the customer-name element in the source schema and the customer-name element in the target schema, drag customer-name from the Source pane to the Target pane. An arrow connects the two elements, as shown in the following figure.

    Figure 6-3 Element-to-Element Links

    Description of Figure 6-3 follows
    Description of "Figure 6-3 Element-to-Element Links"


    Note:

    While dragging from the Source pane to the Target pane, a dashed line appears temporarily between the two elements. For more information about link patterns, Section 6.10.2, "Link Patterns."

  3. After creating the required element-to-element links, save the changes.

6.6.2 Creating Basic Attribute Transformations

Basic attribute transformation involves mapping a source attribute to a target attribute. The source and target attributes may have the same name, type, or scope.

The following are some examples of basic attribute transformations:

  • Element to attribute: A source element is mapped to a target attribute.

  • Attribute to element: A source attribute is mapped to a target element.

  • Attribute to attribute: A source attribute is mapped to a target attribute of the same name.

6.6.2.1 Prerequisite

The XQuery file is created as described in Section 6.5, "Selecting Source and Target Data Types"

6.6.2.2 Creating an Attribute-to-Element Link

To create an attribute-to-element link:

  1. Select the project for which you want to create attribute-to-element links, and open the XQuery file in which the transformation must be stored.

  2. Drag the required attribute from the Source pane to the appropriate element in the Target pane.

    For example, to create a link between the street attribute of the address element in the source schema and the street element of the target schema, drag the street attribute from the Source pane to the Target pane, as shown in the following figure.

    Figure 6-4 Attribute-to-Element Link

    Description of Figure 6-4 follows
    Description of "Figure 6-4 Attribute-to-Element Link"

  3. After creating the required links, save the changes.

Similarly, you can create element-to-attribute and attribute-to-attribute links.

6.6.3 Creating Complex Transformations

Complex transformations involve mapping a complex source (for example, a repeating element) to a complex target (for example, a non-repeating element). The following are some examples of complex transformations:

  • Repeating group to repeating group: The source contains a variable number of instances of a group of elements; each source instance is mapped to an instance of the target group.

  • Repeating group to non-repeating element: The source contains a variable number of instances of a group of elements; each source group is mapped to an instance of the target element.

6.6.3.1 Prerequisite

The XQuery file is created as described in Section 6.5, "Selecting Source and Target Data Types"

6.6.3.2 Creating a Complex Transformation

To create a complex transformation:

  1. Select the project for which you want to create the links, and open the XQuery file in which the transformation must be stored.

  2. Drag the required element or attribute from the Source pane to the appropriate element or attribute in the Target pane.

    For example, to create a link between product (a repeating group in the source schema) and product (a repeating group in the target schema), drag product from the Source pane to the Target pane, as shown in the following figure.

    Figure 6-5 Repeating-Group–to–Repeating-Group Link

    Description of Figure 6-5 follows
    Description of "Figure 6-5 Repeating-Group–to–Repeating-Group Link"

  3. After creating the required links, save the changes.

6.7 Editing Data Transformations

After creating a data transformation in the Design view, you can add, change, and delete XQuery code either by editing code directly in the Source view or by adding complex expressions in the Design view.


Note:

For information about the XQuery language, see http://www.w3.org/XML/Query.

This section contains information about the following topics:

6.7.1 Viewing and Editing XQuery Files

To edit an XQuery file:

  1. Select the project containing the XQuery file that you want to edit.

  2. Double-click the XQuery file.


    Note:

    If the XQuery file is XQuery 2002-compliant, it opens automatically in the XQuery 2002 Transformation Editor, which has only Source and Test views. For more information, see Section 5.2, "Support for XQuery 2002 and 2004."

  3. Select the Source view.

    The XQuery code is displayed. Invalid code is underlined in red.

  4. Make the required changes.


    Note:

    If necessary, you can delete the data transformations in the Source view by deleting all the code within the function except the root element.

  5. Save the changes.

6.7.2 Creating Joins and Unions

The Constraints view in the XQuery transformation perspective allows you to constrain or manipulate the relationship between source and target repeating elements.

The following Constraint Type options are available in the Constraints view:

  • Repeatability/Join option

    When you create transformations between repeating elements, for loops are generated to iterate through the repeating elements. You can limit or constrain the target repeating elements by adding where clauses to the for loops in the Where Clause pane of the Constraints view.

    You can create complex conditions (joined by OR or AND operators) for the where clause, as shown in the following code example:

    ((data($PurchaseOrderDoc/partId) > 200 and data($PurchaseOrderDoc/partId) <= 400))
    

    At run time, the for loop iterates over only those repeating elements that fulfill the complex condition.

    For a detailed example on using the Constraints view, see Section 7.4, "Creating Repeating-Source to Nonrepeating-Target Transformations."

  • Union

    See Section 7.3, "Creating Unions."

6.7.3 Creating If-Then-Else Expressions

The Target Expression view allows you to create if-then-else expressions.

When a query that contains an if-then-else expression is executed, the conditions that make up the if expression are evaluated. Depending on the result, different values are returned for the target node.

Figure 6-6 shows XQuery code that can be used to implement the following logic:

  • If the value of the quantity source node is more than 500, then return 4554 as the value of the ID target node

  • If quantity is less than or equal to 500, then return 5894 as the ID.

Figure 6-6 Example of If-Then-Else Expression

Description of Figure 6-6 follows
Description of "Figure 6-6 Example of If-Then-Else Expression"

You can add multiple expressions to the If condition, as shown in the following figure.

Figure 6-7 If-Then-Else Expression in Target Expression View

Description of Figure 6-7 follows
Description of "Figure 6-7 If-Then-Else Expression in Target Expression View"

You can change the position of a condition by selecting it and then clicking the Move Up or Move Down button. You can also remove a condition by selecting it and then clicking Remove.


Note:

In the Edit If Condition pane, even if you remove all the expressions by using the Remove button, the if-then-else expression is not removed entirely in the Source view. The expressions associated with the if condition are removed, but the then and else expressions are retained, as shown in the following listing.
<ns0:partId> 
  { 
    if (fn:boolean("true")) 
      then 4554 
      else 5894 
  } 
</ns0:partId>

The XQuery always returns the then expression. The else expression is retained in the code so that you can reuse it in the future, if required.


For more information, see Section 7.6, "Creating Nested If-Then-Else Expressions."

6.7.4 Creating For-Let-Where-Order By-Return (FLWOR) Expressions

The Target Expression view allows you to create FLWOR expressions, as shown in the following figure.

Figure 6-8 FLWOR Expression

Description of Figure 6-8 follows
Description of "Figure 6-8 FLWOR Expression"

The following table describes the components of FLWOR expressions.

Table 6-1 Clauses of FLWOR Expressions

Component Description Optional or Mandatory Allowed Nested Expressions

For clause

The For clause iterates over a sequence of input items and returns a value for each item.

At least one For or Let clause

  • If-Then-Else

  • FLWOR

  • Typeswitch

Let clause

The Let clause declares a variable and assigns a value to the variable.

At least one For or Let clause

  • If-Then-Else

  • FLWOR

  • Typeswitch

Where clause

The Where clause specifies the basis for filtering input data. It is similar to the If clause.

Optional


Order By clause

The Order By clause specifies the basis for sorting the output of the query.

Optional

  • If-Then-Else

  • FLWOR

  • Typeswitch

Return expression

The Return expression defines the output of the query.

Mandatory (only one)

  • If-Then-Else

  • FLWOR

  • Typeswitch


You can insert nested expressions under For, Let, Order By, and Return by right-clicking on them and selecting the required expression from the menu.


Note:

In the Design view, if you create a link between repeating elements, a For...Return expression (implicit FLWOR expression) is generated automatically in the Source view. You can add Where clauses to this FLWOR expression by using the Constraints view, but you cannot add Let and Order By clauses. Implicit FLWOR expressions are not shown in the Target Expression view.

For more information, see Section 7.7, "Creating FLWOR Expressions."

6.7.5 Creating Typeswitch Expressions

Typeswitch expressions may be required in the following situations:

  • When an XML schema contains a <choice> element, which allows only one of the elements defined in the <choice> declaration to be present in the containing element, you can use a typeswitch expression to determine the type of the <choice> element that is present in the source XML file and, accordingly, return a value.

  • When an XML schema contains a substitution group, which allows one element to be substituted for another, you can use a typeswitch expression to determine the type of the element that is actually in the source XML file and, accordingly, return a value.

The Target Expression view lets you create typeswitch expressions, as shown in the following figure.

Figure 6-9 Typeswitch Expression

Description of Figure 6-9 follows
Description of "Figure 6-9 Typeswitch Expression"

Table 6-2 describes the components of typeswitch expressions.

Table 6-2 Clauses of Typeswitch Expressions

Component Description Optional or Mandatory Allowed Nested Expressions

Operand expression

The Operand is the expression for which the type is to be evaluated.

Mandatory (only one)


Case clause

Each Case clause specifies the name of the type to be evaluated and the expression to be returned if the evaluation is true.

Mandatory (at least one)

  • If-Then-Else

  • FLWOR

  • Typeswitch

Default clause

The Default clause specifies the return expression that must be used if the value of the operand expression matches none of the types specified in the Case clauses.

Mandatory (only one)

  • If-Then-Else

  • FLWOR

  • Typeswitch


6.7.6 Inserting XQuery Functions

A set of standard W3C XQuery functions and operators is provided in XQuery Mapper. You can add standard XQuery or user-defined functions in XQuery files and data transformation files. For example, you can, use the upper-case XQuery String function to convert the characters in an XML String value to uppercase characters.


Note:

For more information about XQuery and XPath functions and operators (W3C Working Draft 23 July 2004), see http://www.w3.org/TR/2004/WD-xpath-functions-20040723/.

To Insert an XQuery Function: 

  1. Switch to the XQuery transformation perspective by choosing Window > Open Perspective > XQuery Transformation.

    The Expression Functions view is part of the XQuery transformation perspective.

  2. Open the XQuery file in which you want to insert XQuery functions.

  3. In the Design view, select or create a link to add the function call.

    The link becomes green.

  4. Select the Target Expression view.

    If the Target Expression view is not visible, choose Window > Show View > Target Expression.

    In the General Expression pane, the XQuery code linking the selected target and source node is displayed and is selected. Keep this selected for the next step.

  5. Delete the existing XQuery code in the General Expression pane.

  6. Find the function that you want to insert in the Expression Functions view.

    For this example, from the String Functions folder, select the upper-case function, which converts all the characters of the source element to upper case.

  7. Drag the upper-case function to the General Expression pane.

    Leave the parameter of the selected function (the $string-var parameter of the upper-case function in this example) in the General Expression pane selected.


    Notes:

    XQuery functions that are defined by Oracle (example: trim-left) are prefixed with fn-bea:.

    XQuery functions that are not listed in the Expression Functions view but defined in the XQuery specification, can be used with the fn: prefix.


  8. Select a source parameter for the function using one of the following options:

    • From the Source pane of the Design view, select a source element, drag it to the General Expression pane and drop it over the $string-var parameter.

    • From the Expression Variables view, select a source variable, drag it to the General Expression pane and drop it over the $string-var parameter.

  9. After inserting the required functions and assigning parameters to the functions, click Apply in the General Expression pane.

6.7.7 Inserting Expression Variables

The variables (and their subelements) that you can use in an XQuery are displayed in the Expression Variables view.


Note:

If the Expression Variables view is not displayed, choose Window > Show View > Expression Variables.

The following types of variables are displayed in the Expression Variables view:

  • Source: The variables displayed under the Source node in the Expression Variables view are those that are selected for the transformation in the Source Types dialog box of the New XQuery Transformation wizard.

  • Structural Link: The variables displayed under the Structural Link node in the Expression Variables view are the loop iteration variables that are associated with the XQuery for loops generated by structural links.

    These variables are in scope for all the subelements of the node that has the structural link.

You can insert expression variables in the following ways:

  • Drag-and-drop

    Drag the variables or their subelements from the Expression Variables view, and drop them in the Constraints or Target Expression view.

  • Enter $ and choose a variable from the pop-up menu.

    1. Enter the dollar symbol ($) in the required text field. For example, enter $ in the General Expression pane of the Target Expression view.

      A pop-up menu containing a list of the available variables is displayed.

    2. Choose the required variable and then enter a forward slash (/).

      If subelements exist, a pop-menu containing a list of the available subelements is displayed.

    3. Choose the required subelement and then enter a forward slash (/).

      If further subelements exist, a pop-menu containing a list of the available subelements is displayed.

    4. Repeat the previous step until you finish entering the required variable.

6.7.8 Viewing Schema Properties

While editing an XQuery file in the Design view, you can view the schema properties of nodes in the current transformation in the Properties view, without opening the source and target XSD or MFL files.

To display the Properties view, choose Window > Show View > Properties.

  • If you select an element or attribute in the Source, Target, or Expression Variable view, the associated schema properties are displayed in the Properties view.

  • If you select a link, the schema properties of the target and source elements of the link are displayed in the Properties view.

  • To deselect a link (including the target and source nodes of the link), click anywhere in the empty area of the pane between the Source and Target panes of the Design view.


    Note:

    To change the schema properties of an element or attribute, edit the corresponding schema file (XSD for XML schema and MFL for non-XML schema).

6.8 Restricting Output of Optional Elements

If the target schema in a data transformation contains an optional element (minOccurs="0"), you can design the link to the element such that the element is included in the output XML file only if it contains a value (that is, the element is not empty in the source XML file).

Consider the source XML data in the following listing.

Example 6-1 XML Data with Optional Element

<address>
<Address_Line_1>1 Elm Street</Address_Line_1>
<Address_Line_2/>
<City>San Jose</city>
<State>California</State>
<Country>US</Country>
</address>

The Address_Line_2 element is optional and empty. If Address_Line_2 is mapped to a corresponding element in the target schema, then, by default, the output XML file contains an empty Address_Line_2 element.

You can restrict output of such optional elements by right-clicking on the link and selecting Remove Empty Node, as shown in the following figure.

Figure 6-10 Remove Empty Node

Description of Figure 6-10 follows
Description of "Figure 6-10 Remove Empty Node"

The XQuery code underlying the link is enclosed in an if-then-else expression that causes the target element to be produced only if the transformation results in a non-empty value.

You can remove the if-then-else expression by right-clicking on the link and selecting Retain Empty Node, as shown in the following figure.

Figure 6-11 Retain Empty Node

Description of Figure 6-11 follows
Description of "Figure 6-11 Retain Empty Node"


Note:

The Remove Empty Node (or Retain Empty Node) option is displayed only when you right-click on a link to an optional target element.

6.9 Testing Data Transformations

After creating an XQuery transformation in the Design view, you can test whether the expected XML or non-XML output is generated properly in the Test view.

You can use the auto-generated XML files or your own custom XML and non-XML files for testing the transformations.

6.9.1 Features of the Test View

The following figure shows the features of the Test view.

  • Source Variable

The values available in the Source Variables list are based on the source XML schemas of the transformation that you are testing. When you select one of these schemas, an XML file is generated automatically and displayed.


Note:

These XML files are not saved automatically; you can save them by clicking the Export icon.

To use a custom XML file (instead of the auto-generated XML files) or a non-XML file (such as MFL) for testing the transformation, you can import the file by clicking the Import icon.


  • Generate Data

    When you select the Test view, XQuery Mapper generates an initial set of sample data and displays it in the Source Data pane.

    If you want to regenerate the sample data, click Generate Data. You might, for example, want to start testing afresh with new sample data if edits have resulted in XML data that is no longer valid for the input schema.

    If the XQuery that you want to test has multiple source types, you can generate sample data for each source type by selecting the required source type in the Source Variable list and then clicking the Generate Data icon.

    You can also manually edit the generated XML data.


    Note:

    For complex input schemas, the generated XML data may not comply with the schema. Validation errors are underlined in yellow in the Source Data tab. When you place the mouse pointer over an error, details of the error are displayed. You can correct the generated XML data to make it comply with the input schema.

  • Import File

    You can import data from an XML (or non-XML) file and test the transformation using that data.

    In addition, if the XQuery that you want to test has multiple source types, you can import sample data for each source type by selecting the required source type in the Source Variable list and then clicking the Import File icon.

    If the Auto Validate option is selected, then, when you import data, the data is validated against the associated schema. Errors are underlined in yellow. When you place the mouse pointer over an error, details of the error are displayed.


    Note:

    You can import XML data for global types and local elements, but global types and local elements are not validated and no errors or warnings are reported for invalid data. For more information, see Section 6.11, "XML Global Elements, Global Types, Local Elements, and Attributes."

  • Export to File: You can save the data in the Source Data pane or the results of the transformation in the Result Data pane to an XML file.

  • Test XQuery: When you select this option, the XQuery is executed on the data in the Source Data pane and the result of the transformation is displayed in the Results Data pane.

  • Options for validating at design time

    The Auto Validate option in the Source Data pane and the Validate option in the Result Data pane are enabled only if the source parameter or result data is an XML global element.

    The validation options are not available for the following data types:

    • Typed non-XML


      Note:

      In any case, untyped non-XML (raw) data cannot be used in data transformations.

    • XML global type

    • XML local element

    For more information, see Section 6.11, "XML Global Elements, Global Types, Local Elements, and Attributes."

    Selecting the Auto Validate option causes the source data to be validated automatically against the source schema every time the data is changed.

    You can use the Validate option to validate the result of the transformation against the target schema.


    Note:

    The validation at design time in the Test view is not the same as the schema validation that occurs at run time. Validation at design time does not modify the resulting XML document, but it does check for existence of elements and attributes that are defined as required in the schema.

6.10 Graphical Features in Design View

This section provides information to help you use the graphical features of XQuery Mapper and interpret the graphical representations in the Design view of XQuery Mapper.

6.10.1 Right-Click Menu Options

The following table lists the options available in the Design view of XQuery Mapper when you right-click on a link or element.

Table 6-3 Right-Click Menu Options

Menu Option Appears When You ... Result ...

View Code

Right-click on any link or target element

The view switches to the Source view, and the XQuery code for the link is selected.

Create Constant

Right-click on any simple-type target element

Lets you assign a constant value to the target element.

Disable Target Node

Right-click on any link or target element

Blocking XQuery code is added around the XQuery code of the selected link. The blocking code prevents the XQuery code for the link from being executed at run time.

Note: The Disable Target Node menu option is not available for the root node of the target type.

Enable Target Node

Right-click on a disabled link or target element

The blocking XQuery code is removed from around the selected link so that, at run time, the XQuery code for the link is executed.

Remove Empty Node

Right-click on a link to an optional target element.

Surrounds the link with an if-then-else expression that causes the target element to be produced only if the transformation results in a non-empty value.

Retain Empty Node

Right-click on a link (to an optional target element) for which you selected the Remove Empty Node option earlier.

Removes the if-then-else expression that causes the target element to be produced only if the transformation results in a non-empty value.

Redefine Wildcard Node

Right-click on a wildcard (any type) source or target element

Lets you define a specific data type for a wildcard element.

Note: After you redefine a wildcard node (that is, define a specific data type), you cannot use Ctrl+Z to revert to the any type.

Revert to Wildcard Node

Right-click on a wildcard (any type) source or target element, for which you defined a specific data type earlier by using the Redefine Wildcard Node option.

Changes the data type of the element from the specific type that you defined earlier to wildcard (any type).

Induce Map

Right-click on a structural link.

Data links or data structural links are created between the child nodes of the selected structural link if source and target child elements of the link are the same subschema type.

Note: For the Induce Map option to create child links, the target and source child elements must have the same name and data type, and must be in the same order.

Delete Link

Right-click on any link.

  • Design view: The link is deleted.

  • Source view: The XQuery code underlying the link is deleted.

Delete All Links

Right-click anywhere in the empty pane between the Source and Target panes.

  • Design view: The lines representing the transformation between source and target elements/attributes are deleted.

  • Source view: The generated XQuery code is deleted.

Note: Right-clicking anywhere in the empty pane between the Source and Target panes causes all the nodes to be deselected.


6.10.2 Link Patterns

Links in XQuery Mapper are shown in different colors and patterns to help you distinguish easily between different link types. The following table describes the graphical representation of the links that you create in XQuery Mapper.

Table 6-4 Link Patterns

Link Type Description Representation

Data Link

A link that converts the value of the source node directly to the value of the target node.

Link not selected

Thin, solid, light blue, one-way arrow

Link selected

Thick, solid, green, one-way arrow

Implied Link

A data link for which you modified the underlying XQuery code.

A link for which the XQuery code cannot be interpreted by the XQuery Mapper.

Examples:

  • A link for which you inserted the fn:upper-case XQuery function by using the General Expression section of the Target Expression view.

  • The data links generated between a second set of child nodes when a union constraint is applied to a set of two structural links. The child nodes must be of the same subschema.

Link not selected

Thin, solid, light gray, one-way arrow

Link selected

Thick, solid, green, one-way arrow

Structural Link

A link between two parent structures and that does not map data directly.

Link not selected

Thin, dashed, teal, one-way arrow

Link selected

Thick, dotted, green, one-way arrow

Data Structural Link

A data structural link is a combination of a data link and a structural link.

Example: A link between the optional child nodes of a repeating element.

Link not selected

Thin, dashed, light blue, one-way arrow

Link selected

Thick, dashed, green, one-way arrow

Constraint Link

A link that constrains or limits the resulting data of a join between source parent structures. The constraint link is created with two source nodes.

Example: A a join between two source repeating elements to return the data only when the values of a particular source element are equal to each other.

Link not selected

Light blue right bracket

Link selected

Green right bracket

Copy Link

A link between two identical schema substructures. At run time, the source data is copied directly, as a block, to the target data.

A copy link is also generated when you map an untyped XML node to a typed XML complex-type node.

Link not selected

Dashed gold arrow with sloping dashed gold line

Link selected

Dashed green arrow with sloping dashed gold line

6.10.3 Link Colors

When you drag a node from the Source pane to the Target pane, a temporary link (dashed line) appears between the two nodes. The color of the line changes depending on the compatibility between the source and target nodes.

  • Red: The link cannot be created between the source node and the target node because the data type of the target node cannot be converted to the data type of the source node. For example, a node of XML String data type cannot be converted to an XML repeating node. An error message is displayed when you drag the source node over the target node.

  • Orange: The link can be created between the source and target nodes, but the data types are not completely compatible. A warning message describing the incompatibility or any necessary conversion is displayed when you drag the source node over the target node.

  • Green: The link can be created between the source and target nodes. The data type of the target node is compatible with the data type of the source node.

When you finish creating the link, a dotted or dashed line (depending on the source and target nodes) is displayed.

6.11 XML Global Elements, Global Types, Local Elements, and Attributes

An XML schema type or element is considered global if it is a direct child of the schema element and local if it is not a direct child of the schema element (that is, the element is nested within another element).

The following example XML schema illustrates this difference.

Example 6-2 XML Schema with Global and Local Elements

<?xml version="1.0"?> 
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"  
targetNamespace="http://www.acme.org/globalExample"  
xmlns="http://www.acme.org/globalExample"  
elementFormDefault="qualified"  
attributeFormDefault="unqualified"> 
    <xs:element name="globalElement"> 
        <xs:complexType> 
            <xs:sequence> 
                <xs:element name="localElement" 
                    minOccurs="1" maxOccurs="1" 
                    type="xs:string" /> 
            </xs:sequence> 
            <xs:attribute name="attribute" 
                type="xs:string" use="required"/> 
        </xs:complexType> 
    </xs:element> 
    <xs:complexType name="globalType">  
        <xs:sequence> 
            <xs:element name="anotherLocalElement" 
            minOccurs="0" maxOccurs="unbounded"  
            type="xs:string" /> 
        </xs:sequence> 
    </xs:complexType> 
</xs:schema>

In the preceding XML schema, globalElement is global because it is a direct child of the schema element, whereas localElement is local because it is a child of globalElement.

You can also define a global type, as shown by the globalType element toward the end of the preceding XML schema. While you can have only one global element in an XML schema, you can declare many elements (with different names) of the same global type in a single XML schema.

Table 6-5 shows the graphical representations of the different XML components in XQuery Mapper.

Table 6-5 Graphical Representation of XML Components

Component Graphical Representation Name in Preceding Example XML Schema

Global Element

Expandable node with square green icon and component text

globalElement

Local Element

Expandable node with blue circle icon and component text

localElement

Global Type

Expandable node with blue folder icon and child node

globalType

Attribute

Expandable node with square green icon and child node

attribute defined for globalElement