Skip navigation.

eDocs Home > BEA AquaLogic Service Bus 2.0 Documentation > Transforming Data Using the XQuery Mapper > Transforming Data Using XQuery

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.0 and the XQuery Mapper plug-in for Eclipse are installed.

Note: For the AquaLogic Service Bus 2.0 release, Eclipse 3.0 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. From the Windows Start Menu, choose Programs—>BEA Products —>Tools—>XQuery Mapper
  2. From the Eclipse menu bar, open the XQuery Transformation Perspective by choosing Window—>Open Perspective—>Other—>XQuery Transformation.

    3. 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 to 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 or you can launch it from the Windows file system.

Before creating XQuery transformations, you will import your project specific XML and/or non-XML schema 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 Importing Schema Files.

The Sample Project contains the following folders and 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, 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:

  3. Choose Simple—>Project.
  4. Click Next.
  5. Enter a Project Name.

    6. For example, TestProject1

  6. Verify that Use Default is checked.
  7. Click Finish.

 

Importing Schema Files

Schema files can be 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. After schema files are imported, they are available in the New XQuery Transformation wizard as shown in the following figure.

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.

  4. After choosing an Import Type, click Next.
  5. Depending on the Import Type selected, browse to locate the appropriate file.

    6. For example, if importing from a local file system, you are prompted to browse for the locally stored file.

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

Importing MFL Schemas

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

To Import MFL Schemas

  1. Launch XQuery Mapper Perspective in Eclipse.

    2. For more information about launching Eclipse and XQuery Perspective, see Launching the XQuery Mapper.

  2. In the Navigator window, select a project into which you want to import a schema.
  3. Choose File—>Import. 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.
  4. Choose an Import Type and click Next.
  5. Depending on the Import Type selected, the wizard prompts you to browse for the import file.

    6. For example, if importing from a local file system you will be prompted to browse for the locally stored file.

  6. 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 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. 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 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 can be of the following combinations:

To Select Source and Target Data

  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.

  3. Enter a file name for the transformation.

    4. For example, Transform1

  4. Click Next.

    5. The Source Types page opens. This page allows you to select source types for the transformation.

  5. In the Available Source Types pane choose the source data type:
  6. Select source data elements.

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


     
  7. After selecting the source input parameter, click Add.

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

  8. Repeat for additional source types. Multiple source types can be specified.
  9. Click Next.

    10. The Target Types page opens. This page allows you to select the target data for the transformation.

  10. In the Available Target Types pane choose the source data:
  11. Select the target data.
  12. Click Add.

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

    Only one target data type can be specified.

  13. 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 .xq file for which you are creating a map.

    3. This assumes that the map file has been created as described in Using the Design View to Create Data Transformations.

  3. To create an Element to Element link, drag an element from the Source pane to an element in the Target pane.

    4. For example, if creating an Element to Element link between the source element name and the target element 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


     
  4. Repeat the preceding step until all the desired elements are mapped.
  5. Save your work.

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 name and name, 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


     
  4. Repeat the preceding step until all the desired attributes are mapped.

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 Using the Design View to Create Data Transformations.

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

    4. For example, if creating a Repeating Group to Repeating Group link between name and name, 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


     
  4. Repeat the preceding step until all the desired elements and attributes are mapped.

 

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. Open the XQuery file for which you are editing.
  3. Click the Source tab.

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

  4. Optionally, fix errors indicated by red underline.

    5. If desired, you can delete all the XQuery code in the Source view of the XQ file by removing all the XQuery source code after the namespace declaration(s) and recreating your links in the Design view.

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

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. Open the XQuery file for which you are editing.
  2. In the Design View, select or create a link between a source and target node.

    3. Keep the link selected.

  3. Select the Target Expression tab.

    4. By default the General option is selected and the XQuery code for the link is displayed in the General Expression pane.

  4. Select the Target Expression tab.
  5. Edit the generated XQuery code.

    6. 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 constructs 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 XQuery 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 to the query. 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.
  2. To view Expression Functions, choose Windows—>Show View—>Expression Functions.
  3. To view Expression Variables, choose Windows—>Show View—>Expression Variables.

To Invoke an XQuery Function

  1. Open an XQuery.
  2. In the Design tab, select or create the link to add the function call.

    3. The link between these two nodes becomes green.

  3. In the bottom pane of the Design tab, choose the Target Expression tab.

    4. If the Target Expression tab is not visible, from the menu bar, choose View—>Windows—>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.

  4. Click Delete.

    5. The text in the General Expression pane is removed.

  5. Collapse and expand the folders to find the desired function.

    6. For this example, from the String Functions folder select the upper-case function.

  6. In the XQuery Functions pane, select the desired function, and drag it into the General Expression pane.

    7. For the following step, leave the parameter selected (in this example: $string-var) in the General Expression pane selected.

  7. Select a source parameter using one of the following options:
  8. Repeat until all the parameters in the function are assigned.
  9. Click Apply.

    10. During run time for this example, the upper-case function will convert all the characters of the $quoteDoc/name 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 XQ 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. The Property Editor displays a read-only view of the schema properties for the selected element(s).

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

The following functionality is available in the Test tab:

 

Validating During Design Time

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

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

If you click Validate in either the Source Data and 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 validating done during design time in the Test View is not the same as the schema validating that occurs during run time. The validating 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-7 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 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 xf: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 dialog box 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 dialog box 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 target node.


 

After the target node has been dropped on the source 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, and Local Elements

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:schemons: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: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


 

localElement and anotherLocalElement

Local Element

Data Links


 

globalElement

Global Type

Data Links


 

globalType


 

 

Skip navigation bar  Back to Top Previous Next