Skip navigation.

Transforming Data Using the XQuery Mapper

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

Transforming Data Using XQuery

This section describes how to use the BEA XQuery Mapper to graphically create data transformations. Using the graphical interface, you can map source elements in schemas to target elements in schemas. After doing so, the XQuery Mapper generates an XQuery, which is saved as an .xq file.

This section includes the following topics:

 


Launching the XQuery Mapper

When you install BEA AquaLogic Service Bus, Eclipse 3.1 and the XQuery Mapper plug-in for Eclipse are installed.

Note: For the AquaLogic Service Bus 2.1 release, Eclipse 3.1 is supported only on Windows platforms.

As part of your XQuery Mapper installation, a sample project containing default schema is provided. For more information about the Sample Project, see XQuery Mapper Sample Project.

To Launch Eclipse

  1. Start the XQuery Mapper in one of the following ways:
  2. From the Eclipse menu bar, open the XQuery Transformation Perspective by choosing
  3. Window—>Open Perspective—>Other—>XQuery Transformation.

    Note: The XQuery Transformation Perspective launches automatically when you open an XQuery file. However, if the XQuery Mapper is open (and an XQuery file is not) you must manually launch the XQuery Transformation Perspective.

 


XQuery Mapper Sample Project

After launching the sample project, you can use the sample schema files to create XQuery Transformations as described in Examples: Manipulating and Constraining Data Using XQuery.

To learn more, see the following topics:

To Launch the Sample Project

You can open the Sample Project from within Eclipse.

The Sample Project contains the following folders and files:

Before creating XQuery transformations, you can create or import your project specific XML schema, WSDL, or MFL files.You can import files from any location to the XQuery Mapper. Before importing files into Eclipse, it is recommended that you create a folder directory structure that meets your business needs. For more information, see Creating and Importing Schema Files.

 


Creating a New XQuery Mapper Project

You create a new project using the Eclipse New Project wizard. This wizard prompts you to select from a variety of new project types. For XQuery Mapper purposes, you can choose Simple, which allows you to create a basic project.

To Create a New XQuery Mapper Project

  1. Launch the XQuery Mapper Perspective in Eclipse as described in Launching the XQuery Mapper.
  2. Choose File—>New—>Project.
  3. The New Project wizard opens. The wizard prompts you to select one of the following:

  4. Choose Simple—>Project.
  5. Click Next.
  6. Enter a Project Name.
  7. For example, TestProject1

  8. Verify that the Use Default check box is selected.
  9. Click Finish.

 


Creating and Importing Schema Files

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

This section includes the following topics:

Importing XML Schemas

XML schemas are created and stored outside of Eclipse. However, they can also be created using the XML Schema Editor. After schema files are imported or created, they are available in the New XQuery Transformation wizard as shown in the following figure. For information about creating XML Schema, see: Creating XML Schema Files Using XML Schema Editor.

Figure 2-1 New XQuery Transformation Wizard

New XQuery Transformation Wizard


 

To Import XML Schemas

  1. Launch the XQuery Mapper Perspective in Eclipse, as described in Launching the XQuery Mapper.
  2. In the Navigator window, select the project into which you want to import the schema.
  3. Choose File—>Import.
  4. The Eclipse Import wizard is displayed. Using this wizard, schemas can be imported from a variety of sources. The import source you select depends on where the schema is stored.

  5. After choosing an Import Type, click Next.
  6. Depending on the Import Type selected, browse to locate the appropriate file.
  7. For example, if importing from a local file system, you are prompted to browse for the locally stored file.

  8. After locating and selecting the input schema files, click Finish.

Creating XML Schema Files Using XML Schema Editor

You can create an XML schema file using the XML Schema Editor that is shipped with Eclipse.

To Create an XML Schema File

  1. Launch the XQuery Mapper Perspective in Eclipse, as described in Launching the XQuery Mapper.
  2. In the Navigator window, select the project into which you want to create the schema file.
  3. Select New—>Other ...
  4. The New wizard appears.

  5. Choose either AquaLogic Service Bus or XML wizard type.
  6. Choose XML Schema, then click Next.
  7. Choose the parent folder in which you want to create the schema file.
  8. Enter a name for the schema file.
  9. For example, NewXMLSchema

  10. Click Finish.

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

Note: For more information about using the XML Schema Editor, see the XML Schema Editor Tutorial, which is available at the following URL:

http://www.eclipse.org/webtools/community/tutorials/XMLSchemaEditor/XMLSchemaEditorTutorial.html

Creating WSDL Files Using WSDL Editor

You can create a WSDL file using the WSDL Editor that is shipped with Eclipse. The XML schema defined in the WSDL files can be used in the transformation.

To Create a WSDL File

  1. Launch the XQuery Mapper Perspective in Eclipse, as described in Launching the XQuery Mapper.
  2. In the Navigator window, select the project into which you want to create the WSDL file.
  3. Select New—>Other ...
  4. The New wizard appears.

  5. Choose either AquaLogic Service Bus or XML wizard type.
  6. Choose WSDL, then click Next.
  7. Choose the parent folder in which you want to create the WSDL file.
  8. Enter a name for the WSDL file.
  9. For example, NewWSDLFile

  10. Click Next.
  11. Enter the target namespace and prefix of the WSDL file.
  12. If required, select the Create WSDL Skeleton check box.
  13. After choosing the protocol and the binding options, click Finish.

The WSDL file is created in the specified project.

Note: For more information about using the WSDL Editor, see the WSDL Editor Tutorial, which is available at the following URL:

http://www.eclipse.org/webtools/community/tutorials/WSDLEditor/WSDLEditorTutorial.html

Importing MFL Schemas

After MFL files are imported, the files are available in the New XQuery Transformation Wizard.

To Import MFL Schemas

  1. Launch the XQuery Mapper Perspective in Eclipse, as described in Launching the XQuery Mapper.
  2. In the Navigator window, select a project into which you want to import the schema.
  3. Choose File—>Import.
  4. The Import wizard opens. Using this wizard, schema can be imported from a variety of sources. The import source you select depends on where the schema is stored.

  5. Choose an Import Type, then click Next.
  6. Depending on the Import Type selected, the wizard prompts you to browse for the import file.
  7. For example, if importing from a local file system you will be prompted to browse for the locally stored file.

  8. After locating and selecting the input schema files, click Finish.

To Create MFL Files

MFL files are created using the Format Builder tool, which can be launched from the Windows Start menu or from Eclipse.

For more information about Format Builder, see the Format Builder Online Help.

 


Selecting Source and Target Data Types to Generate XQuery

Click the Design tab to open the XQuery Mapper Design view, which allows you to create transformation maps by selecting source and target data types. In the Design view, you can graphically link Source and Target elements. After creating links between source and target elements, an XQuery file (or map) is generated. The generated XQuery file has an .xq extension. The XQuery file (or map) is displayed in the Design view. The generated XQuery code is visible by clicking the Source tab.

Source and target data types can be of the following combinations:

To Select Source and Target Data Types

  1. Select the project for which you are creating a map.
  2. Right-click and choose New—>XQuery Transformation.
  3. The New XQuery Transformation wizard opens.

  4. Enter a file name for the transformation.
  5. For example, Transform1

  6. Click Next.
  7. The Source Types page opens. This page allows you to select source types for the transformation.

  8. In the Available Source Types pane choose the source data type:
  9. Select source data elements.
  10. For example, if adding input data from Schemas/Dates.xsd, first select it, then traverse its contents to select date as your input element, as shown in the following figure.

    Figure 2-2 Selecting Source Types

    Selecting Source Types


     
  11. After selecting the source input parameter, click Add.
  12. The elements and attributes that make up the selected element are displayed in the Selected Source Types pane.

  13. Repeat for adding more source types. Multiple source types can be specified.
  14. Click Next.
  15. The Target Types page opens. This page allows you to select the target data types for the transformation.

  16. In the Available Target Types pane choose the target data type:
  17. Select the target type.
  18. Click Add.
  19. The elements and attributes that make up the selected element are displayed in the Selected Target Types pane.

    Note: Only one target data type can be specified.

  20. Click Finish.

 


Using the Design View to Create Data Transformations

This section includes the following topics:

Creating Basic Element Transformations

A basic element transformation involves mapping a source element to a target element. The source and target elements may or may not have the same name, type, or scope. There are many different types of basic element transformation.

The following list provides examples:

To Create an Element to Element Transformation

  1. Select the project for which the map is being created.
  2. Open the XQuery file for which you are creating a map.
  3. This assumes that the map file has been created as described in Selecting Source and Target Data Types to Generate XQuery.

  4. To create an Element to Element link, drag an element from the Source pane to an element in the Target pane.
  5. For example, if creating an Element to Element link between the source element customer-name and the target element customer-name simply drag it from the Source pane to the Target pane as shown in the following figure.

    Figure 2-3 Element to Element Links

    Element to Element Links


     
  6. Repeat the preceding step until all the desired elements are mapped.
  7. Save your changes.

Creating Basic Attribute Transformations

A basic attribute transformation involves mapping a source attribute to a target attribute. The source and target attributes may or may not have the same name, type, or scope. There are many different types of basic attribute transformation.

The following list provides examples:

To Create an Attribute to Element Transformation

  1. Select the project for which the map is being created.
  2. Open the XQuery file for which you are creating a map.
  3. Create an Attribute to Element link by dragging an attribute from the Source pane to an element in the Target pane.
  4. For example, if creating an Attribute to Element link between the street attribute and the street element, drag it from the Source pane to the Target pane as shown in the following figure.

    Figure 2-4 Attribute to Element Link

    Attribute to Element Link


     
  5. Repeat the preceding step until all the desired attributes are mapped.
  6. Save your changes.

Creating Complex Map Transformations

Complex map transformations involve mapping from a complex source (for example, a repeating element) to a complex target (for example, a non-repeating element). The following list provides examples:

To Create a Repeating Group to Repeating Group Transformation

  1. Select the project for which the map is being created.
  2. Open the XQuery file for which you are creating a map.
  3. This assumes that the map file has been created as described in Selecting Source and Target Data Types to Generate XQuery.

  4. To create an Repeating Group to Repeating Group link, drag an element or attribute from the Source pane to an element or attribute in the Target pane.
  5. For example, if creating a Repeating Group to Repeating Group link between product and product, drag it from the Source pane to the Target pane as shown in the following figure.

    Figure 2-5 Repeating Group to Repeating Group Link

    Repeating Group to Repeating Group Link


     
  6. Repeat the preceding step until all the desired elements and attributes are mapped.
  7. Save your changes.

 


Editing Map Transformations

After creating the initial transformation you may want to change, update, or delete it in the Source tab.

This section contains the following topics:

Viewing and Editing Generated XQuery Files

After creating links between source data and target data, an XQuery file is generated to represent the relationship. To learn about the XQuery language supported with XQuery Mapper, see the following URL:

http://www.w3.org/XML/Query

To Open, View, and Edit an XQuery File

  1. Select the project that contains the generated XQuery file.
  2. Double-click the XQuery file that you want to edit.
  3. Click the Source tab.
  4. The XQuery code is displayed. Invalid XQuery code is underlined in red.

  5. Optionally, fix errors indicated by red underline.
  6. If desired, you can delete all the XQuery code in the Source view of the XQ file by removing all the XQuery source code inside the function, except the root element, and recreating your links in the Design view.

  7. Save your changes.

 


Using the Constraints Tab

The Constraints tab of the XQuery Mapper allows you to constrain or manipulate the relationship between source and target repeating elements.

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

Note: For more information about these options, see Using the Union Option of the Constraints Tab.

When creating structural links between repeating elements in the Design view, XQuery for loops are generated to iterate through the repeating elements. You can use the Where Clause Expression pane of the Constraints tab to limit or constrain the target repeating elements by adding where clauses to the XQuery for loops. In the Where Clause Expression pane of the Constraints tab, you can build complex conditions for the where clause of the XQuery for loop. A complex condition is made up of conditions that are joined together by OR or AND operators, for example:

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

During run time, the for loop will iterate only over those repeating elements that meet the complex condition.

For a detailed example on using the Constraints Tab, see Creating a Transformation Between a Repeating Source and Non-Repeating Target.

 


Using the Target Expression Tab

You can view and modify the link between a source and target element using the Target Expression tab. Using the Target Expression tab, you can build complex expressions between a source and target element.

This section contains the following topics:

Using the Target Expression Tab to Edit XQuery Code of a Link

To Edit the XQuery Code of a Link

  1. Double-click the XQuery file that you want to edit.
  2. In the Design View, select or create a link between a source and target node.
  3. Keep the link selected.

  4. Select the Target Expression tab.
  5. By default, the General option is selected and the XQuery code for the link is displayed in the General Expression pane.

  6. Select the Target Expression tab.
  7. Edit the generated XQuery code.
  8. The query is written in the XQuery language. To learn more about the XQuery code, see the following URL:

    http://www.w3.org/XML/Query

Using the Target Expression Tab to Add If-Then-Else Constructs to a Link

You can add an if-then-else construct to a link using the Target Expression tab. When a query is invoked with an if-then-else, the conditions that make up the if expression are evaluated, depending on the result, different values are returned for a target node. For example, if the value of quantity source node is greater than 500 then 4554 is returned as the value of the ID target node, but if the value of quantity source node is less than or equal to 500, then 5894 is returned as the value of the ID target node, as shown in the example in the following figure.

Figure 2-6 If-Then-Else

If-Then-Else


 

In addition to the following procedure for adding a simple if-then-else expression to a link, a more complex example is available. For an example, see Creating a Transformation Between a Repeating Source and Non-Repeating Target.

 


Inserting Calls to XQuery Functions

This section describes how to insert calls to functions into a query using the Target Expression tab.

For more information about the XQuery 1.0 and XPath 2.0 functions and operators, see the following URL: http://www.w3.org/TR/2005/WD-xpath-functions-20050404/

This section contains the following topics:

Invoking XQuery Functions in a Query

A set of standard W3C XQuery functions and operators are provided in the XQuery Mapper. When you create a transformation, a query is written in the XQuery language and this query does the data conversion. In the generated query, you can add standard XQuery or user-defined functions. For example, as part of your transformation you might want to convert the XML String to uppercase characters.

To View the XQuery Functions and Variables in Eclipse

  1. Launch the XQuery Mapper Perspective in Eclipse, as described in Launching the XQuery Mapper.
  2. To view Expression Functions, choose Window—>Show View—>Expression Functions.
  3. To view Expression Variables, choose Window—>Show View—>Expression Variables.

To Invoke an XQuery Function

  1. Double-click an XQuery file.
  2. In the Design tab, select or create a link to add the function call.
  3. The link between these two nodes becomes green.

  4. In the bottom pane of the Design tab, choose the Target Expression tab.
  5. If the Target Expression tab is not visible, from the menu bar, 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.

  6. Press Delete to remove the XQuery code in the General Expression pane.
  7. Collapse and expand the folders in the Expression Functions pane to find the desired function.
  8. For this example, from the String Functions folder, select the upper-case function.

  9. In the Expression Functions pane, select the desired function, and drag it into the General Expression pane.
  10. For the following step, 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.

    Note: XQuery functions like trim-left that have been defined by BEA Systems are prefixed with fn-bea:. XQuery functions that are not listed in the Expression Functions pane, but are defined in the XQuery specification can be used with the fn: prefix.

  11. Select a source parameter using one of the following options:
  12. Repeat until all the parameters in the function are assigned.
  13. Click Apply.

During run time for this example, the upper-case function will convert all the characters of the source element to upper case.

 


Using Expression Variables

Using the Expression Variables view of the XQuery Mapper you can access variables and their sub elements. You can drag-and-drop variables or their sub elements from the Expression Variables view into the Constraints and Target Expression tabs.

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

 


Using the Property Editor When Editing an XQuery file

While editing an XQuery file in the Design tab, the Property Editor allows you to view schema properties about the nodes in the current map without opening the source and target XSD or MFL files. So, you can select the element or attribute in the Source, Target, or Expression Variable pane and view the associated schema properties in the Property Editor. The Property Editor displays a read-only view of the schema properties for the selected element.

To turn on the Property Editor view, choose Window—>Show View—>Properties.

 


Testing Map Transformations

You can use the Test tab in the XQuery Mapper to verify your XQuery transformations.

This section contains the following topics:

For more information about testing XQuery files, see Testing XQuery Files.

XQuery Mapper Testing Functionality Overview

You can use the Test view in the Mapper to validate the transformation defined by you. Select the appropriate icon in the Test view as displayed in the following figure.

Figure 2-7 Test View

Test View


 

The following functionality is available in the Test view:

 


Validating During Design Time

During design time, the Auto Validate icon in the Source Data and the Validate icon in the Result Data panes in the Test View tab of an XQuery file will be enabled only if the selected source parameter or resulting data is a typed global XML element. To learn more, see XML Global Elements, Global Types, Local Elements, and Attributes.

Validate will not be enabled if the selected source parameter or resulting data is one of the following types:

If you select the Auto Validate icon in the Source Data and the Validate icon in the Result Data panes in the Test View tab of an XQuery file, the displayed XML is checked against the schema and any errors are reported during design time. The validation done during design time in the Test View is not the same as the schema validation that occurs during run time. The validation during design time does not modify the resulting XML document, but it does check if any required elements or attributes defined in the schema are not present.

 


Understanding Design View Graphical Representations

Using the design view you can graphically create, alter, or update transformations. This sections provides information about the graphical representations found in the Design tab of the XQuery Mapper.

This section includes the following topics:

Link Menu Options

Menu Option

Invoke by . . .

Result . . .

Delete All Links

In the Design View, right-click on an empty section between the Source and Target panes and from the drop-down menu select Delete All Links.

Note: Right-clicking on an empty section between the Source and Target panes causes all the nodes to be un-selected.

In the Design View, the graphical representations of all the links are deleted and in the Source View the generated XQuery code linking the source nodes to the target nodes is deleted.

Induce Map

In the Design View, right-click on a structural link and from the drop-down menu select Induce Map.

Note: This menu option is only available when a structural link is selected in the Design View.

Data links or data structural links will be created between the child nodes of the selected structural link if source and target child elements of the link are the same subschema type. The target and source child elements must have the same name, must be the data types, and must be in the same order for the Induce Map option to create child links.

View Code

In the Design View, right-click on a link and from the drop-down menu select View Code.

The view changes from the Design View to the Source View and generated XQuery code between the links is displayed. The XQuery code for the selected link is highlighted in blue.

Disable Target Node

In the Design View, right-click on a link and from the drop-down menu select Disable Target Node.

Blocking XQuery code is added around the XQuery code of the selected link that prevents the XQuery code for the link from being executed during run time.

Enable Target Node

In the Design View, right-click on a disabled link and from the drop-down menu select Enable Target Node.

The blocking XQuery code is removed around the selected link. During run time, the XQuery code for the link is executed.

Delete Link

In the Design View, right-click on a selected link and from the drop-down menu select Delete Link.

In the Design View, the graphical representations of the selected link is deleted and in the Source View the generated XQuery code linking the source node to the target node is deleted.


 

Understanding Map Representations

A data link directly transforms data from a source node to a target node. For example, the following figure shows a data link between the priceQuote/customerName element and the quote/name element.

Figure 2-8 Data Links

Data Links


 

Both priceQuote/customerName and quote/name are XML String elements. During run-time, the data from the priceQuote/customerName element is converted to the quote/name element as shown in the preceding figure.

If you modify the XQuery code linking these two elements, the link between these elements changes from a data link (represented as a blue line) to an implied link (represented as a light gray line).

The following table summarizes the different link representations.

Link Type

Is the Link an XQuery Mapper

Generated Link?

Description

Is the Link Currently Selected in the XQuery Mapper?

Representation of Link

Data Link

Link is generated by dragging-and-dropping.

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

Not Selected


 

Data Links


 

Selected

Data Links


 

Structural Link

Link is generated by dragging-and-dropping.

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

Not Selected

Data Links


 

Selected

Data Links


 

Data Structural Link

Link is generated by dragging-and-dropping.

A data structural link is the combination of the following two links:

  • A data link between two nodes—a link that converts the value of the source node directly to the value of the target node.

  • A structural link—a link between two structures.

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

Not Selected

Data Links


 

Selected

Data Links


 


 

Understanding Map Transformation Links

While dragging a node from the Source pane to the Target pane, a temporary link (a dashed line) appears between the two nodes. The color of the dotted line changes depending on the compatibility between the source and target node, as shown in the following table.

Link Type

Is the Link a Mapper

Generated Link?

Description

Is the Link Currently Selected in the Mapper?

Representation of Link

Constraint Link

Link is generated by dragging-and-dropping.

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: You could add a constraint link to a join of two source repeating elements to only return the data when the values of a particular source element are equal to each other.

Not Selected

Data Links


 

Selected

Data Links


 

Copy Link

Link is generated by dragging-and-dropping

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

A copy link is also generated when mapping between a untyped XML node and a typed XML complex-type node.

Not Selected

Data Links


 

Selected

Data Links


 

Implied Link

Link between the nodes is created by writing new XQuery or modifying existing XQuery code.

A link whose XQuery code can not be interpreted by the XQuery Mapper to be another type of link.

Example: A data link that was modified using the General Expression section of the Target Expression tab or the Source View. For example, adding the fn:upper-case function to a link. The data links generated between a second set of child nodes when a union constraint has been applied a set of two structural links. The child nodes must be of the same subschema.

Not Selected

Data Links


 

Selected

Data Links


 

The Color of the Dashed Line is . . .

Means . . .

Red

No link can be created between the source node and the target node. The data type of the target node cannot be converted to the data type of the source node. (The link represents a illegal mapping.) For example, a node of data type XML string can not be converted to an XML repeating node. A red error message will be displayed when you drag the source node over the target node.

Orange

A link can be created between the source node and the target node but the data types are not completely compatible. An orange warning message describing the incompatibility or any necessary conversion will be displayed when you drag the source node over the target node.

Green

A link can be created between the source node and the target node. The data type of the target node is compatible with the data type of the source node.


 

After the source node has been dropped on the target node, a line representing a link will be displayed. Depending on the target and source nodes, a dashed line or a solid line will be displayed.

 


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 while an XML Schema type or element is considered local if it is not a direct child of the schema element (is nested to another element) as shown in the following XML Schema.

<?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 example XML Schema, the globalElement is global because it is a direct child of the schema element while localElement is local because it is child of globalElement.

You can also define a global type as shown by the globalType element at the bottom of the preceding XML Schema. While you can only have 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.

The following table shows the graphical representations of these different XML components in the XQuery Mapper.

Name

Representation in the XQuery Mapper

Name in Preceding Example XML Schema

Global Element

Data Links


 

globalElement and anotherglobaElement

Local Element

Data Links


 

localElement

Global Type

Data Links


 

globalType

Attribute

Data Links


 

attribute defined for globalElement


 

 

Skip navigation bar  Back to Top Previous Next