Data Services Developer's Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Working with the XQuery Editor

BEA Aqualogic Data Services Platform services provide a framework for creation and maintenance of functions that access and transform available data. You can use the XQuery Editor to create such functions.

A valid query function is always associated with a return type. In Source View a return type is described for each function. It typically matches the XML type — or schema — that defines the shape of your data service.

Once created, your query functions can be called by client applications. Details on the various methods of invoking AquaLogic Data Services Platform functions can be found in the AquaLogic Data Services Platform Client Application Developer's Guide.

You can also use the XQuery Editor to create standalone, queries that can be run in Test View (see Testing Query Functions and Viewing Query Plans).

Topics discussed in this chapter include:


Role of the XQuery Editor

Using the XQuery Editor you can create query functions using an intuitive, drag-and-drop approach. During the creation process you can easily move back and forth between the editor to Source View.

Figure 6-1 Sample Parameterized Function in the XQuery Editor

Sample Parameterized Function in the XQuery Editor

The XQuery Editor relies on data services functions for the metadata necessary to represent various types of data. (For detailed information on importing metadata see Obtaining Enterprise Metadata.)

Sample Parameterized Function in the XQuery Editor

A data service may represent a physical data source or it may represent logical data that has previously been created. Data service and custom XQuery library functions are both represented from the Data Services Palette (Figure 6-2), a WebLogic Workshop pane available when XQuery Editor View is active.

Figure 6-2 Data Service Functions Available to the RTL Sample Application

Data Service Functions Available to the RTL Sample Application

Notice in Figure 6-2 that there are two different type of function representations: Functions represent by a straight (green) arrow are read functions, while functions represented by a more stylized (blue) arrow are navigation functions.

Essentially you create a query function by:

As you work graphically you are automatically creating an XQuery in Source View.

Once created, you can execute your function using Test View (see Testing Query Functions and Viewing Query Plans). When you execute your query function, underlying data sources are accessed and the results appear. If you have appropriate permissions, data can be updated directly after the query is run.

Data Source Representations

Metadata representations of source are available to the XQuery Editor from the Data Services Palette. The Data Services Palette lists available data services and their read and relationship functions. Any such function can be dragged into the XQuery Editor work area where it will be transformed into a for clause.

Read functions and Web services often have input parameters. For example, the logical data service Customer (customer.ds) can be represented in the XQuery Editor by its read functions: getCustomer() and getPaymentList( ). If you drag the getCustomer(  ) item from the Data Services Palette to the XQuery Editor, the source representation shown in Figure 6-3 appears in the work area.

Figure 6-3 Data Service Function From the Data Services Palette

In some cases you may want to use a physical or logical data source representation several times in a query.

See Obtaining Enterprise Metadata and Designing Data Services for details on creating physical and logical data services.

XQuery Editor Options

When you create a new function in your data service and then click on the name of your new function (Figure 6-1), you will automatically be placed in the XQuery Editor. Alternatively, click the XQuery Editor View tab and select your function from the drop-down menu. Initially your XQuery will have only a return type, assuming that your data service is associated with an XML type (see Associating an XML Type).

Figure 6-4 Right-click Menu Options in the XQuery Editor

Right-click Menu Options in the XQuery Editor

Several right-click menu options are available when you click in any unoccupied part of the work area.

Table 6-5 XQuery Editor Right-click Menu Options
Edit in Source View
Opens Source View to the section containing the currently selected function.
Default layout
The elements in the XQuery Editor are rearranged according to a pre-established formula including docking the return type to the right side of the work area.
Add Parameter
Adds a simple or complex parameter to your work area. Complex parameters require you to select a schema file and global type. See Parameter Nodes.
Show Condition Lines
Hides/displays lines that identify conditions such as where clause predicates. By default condition lines are shown.
Remove Selected Item(s)
Deletes selected items from the work area.
Collapse All
Collapses all nodes in the work area including the return type.
Expand All
Expands all nodes in the work area.


Creating a Simple Data Service Function

Creating a data service — as you will if you follow the steps in this section — is a good way to get the feel of working with the XQuery Editor, as well as other aspects of data services.

Tip: Changes made in the XQuery Editor are immediately reflected in Source View.

The goal of this exercise is to quickly create a logical data service, including creating an XML type for your data service, using the XQuery Editor. The basic steps are:

Tip: The quickest way to change something you have done in the XQuery Editor is to use the Edit Arrow symbol Undo command (or Ctrl-Z). Prior to saving your application you can undo any number of previous steps. Thus it is often preferable to use Undo rather than redrawing mappings, zone settings, or conditions.

In the sample it is assumed that you have the RTLApp sample installed and running, as well as its server.

Importing Metadata from Physical Data Sources

In this section you create a new data service-enabled project and import metadata for the data sources you plan to use in your logical data service.

  1. In RTLApp create a new project of data services type. Name the project myLogicalDS, then click Create. (For details on creating AquaLogic Data Services Platform projects and applications see AquaLogic Data Services Platform-Based BEA WebLogic Applications.)
  2. Right-click on your new data service and select Import Source Metadata. (If your ldplatform samples server is not already running you will need to start it now.)
  3. Select Relational as the data source type, click Next.
  4. Choose cgDataSource from the drop-down list of available relational data sources.
  5. Allow the default Select All radio button to remain selected. Click Next.
  6. From the RTLCUSTOMER database select the CUSTOMER table.
  7. Add it as a selected database object.
  8. Repeat steps 5 and 6 for CUSTOMER_ORDER table in the RTLAPPLOMS database.
  9. Click through the remaining default options in the wizard to created two new data services.

Creating Your Logical Data Service

In this section you create a logical data service that provides client applications with the ability to retrieve customer-order information. In this section you will:

Here are the specific steps involved:

  1. Right-click again on the myLogicalDS project and choose New Arrow symbol Data Service.
  2. Name the data service myLogicalDS, then click Create.
  3. Note: At this point your data service has no XML type (schema).
  4. Click on the titlebar of your new data service; select Add function. Name your new function CustOrder. Enter the XQuery Editor by clicking on the newly assigned name.
  5. Drag the CUSTOMER_ORDER( ) function from ApparelDB:CUSTOMER_ORDERS in the work area (Figure 6-6).
  6. From your Data Services Palette drag the CUSTOMER( ) function from the CUSTOMER data service in the CustomerDB folder into the XQuery editor work area.
  7. Figure 6-6 XQuery Editor With Two Data Sources and an Empty Return Type

    XQuery Editor With Two Data Sources and an Empty Return Type

    The existence of the two incomplete for clauses, $CUSTOMER and $CUSTOMER_ORDER, is accounted for by the return type's two empty elements.

    Next, you need to populate your function's return type. CUSTOMER_ORDER should be set up as a child of CUSTOMER so that information will be return in the following shape:

  8. Holding down the Ctrl key map the CUSTOMER* element in the CUSTOMER for node to the topmost empty element in the return type.
  9. Figure 6-7 Return Type After An Induced Mapping of the Customer For Node

    Return Type After An Induced Mapping of the Customer For Node

  10. In your return type right-click on the new CUSTOMER root element and select Expand Complex Mapping. This maps all the elements in your CUSTOMER node to corresponding elements in your return type.
  11. As the returned document is to list all customer orders associated with a specific customer, you need to create a subordinate complex element. One way to do this is to simply add the CUSTOMER_ORDER type as a subordinate to CUSTOMER, as shown in the next step.

  12. Holding down Shift+Ctrl keys, select the root element in the $CUSTOMER_ORDER for node and drag it over the CUSTOMER root element in your return type.
  13. Figure 6-8 Append Mapping of the $CUSTOMER_ORDER to the Return Type

    Append Mapping of the $CUSTOMER_ORDER to the Return Type

    The CUSTOMER_ORDER elements will appear as subordinate to CUSTOMER (Figure 6-9).

    Figure 6-9 Subordinate Node Added to the Return Type

    Subordinate Node Added to the Return Type

    If you try to run a query at this point it will fail for several reasons:

    • Your data service has no associated XML type (schema).
    • Your project (or application) needs to be build to create the proper SDO infrastructure.
    • No where clause connecting the customer ID keys in the two data source representations has been created.
    • The master-detail structure of the document has not been created.
    • Similarly, if you attempt to map source elements to CUSTOMER_ORDER, you will not be successful. This is because the implicit assumption behind the mapping of a complex element is that all the child elements are mapped to the return type.

      These issues are resolved through the steps that follow.

  14. In your CUSTOMER_ORDER node select the zone icon (see Figure 6-10) and drag it over the CUSTOMER_ORDER element in your return type. (Notice that now when you mouse over the CUSTOMER_ORDER note, only the subordinate CUSTOMER_ORDER node is highlighted.) This action creates an inner zone in your return type which in source becomes an inner for clause for your query. An inner zone corresponds to the detail part of a relational master-detail ordering. (For more information on return type zones see Setting Zones in Your Return Type.)
  15. Figure 6-10 Creating a Zone Supporting CUSTOMER_ORDER

    Creating a Zone Supporting CUSTOMER_ORDER

  16. Right-click on CUSTOMER_ORDER and choose Expand Complex Mapping so that individual elements are mapped.
  17. Create a join between your two data source representations by dragging the CUSTOMER_ID element in the CUSTOMER node to the C_ID element in the CUSTOMER_ORDER node. A dotted green line connecting the two elements appears.
  18. Data service functions that are added to the XQuery Editor workspace have namespaces. Since all elements in a return type need to share the same namespace, minor editing is necessary. Double-click on the second complex element (CUSTOMER_ORDER) and change:
  19. ns0:customer



Finishing Up

Now the default name for your new schema matches the name of your data service; the default namespace is the qualified name (qname) of the root element of your return type.

  1. Click on the titlebar of your return type and select Save and Associate XML Type from the right-click menu. In order to complete this operation you need to provide the location of your new schema file, its namespace, and a name for the root element in your return type. In each case a default setting is provided, as shown in Figure 6-11.
  2. Figure 6-11 Save and Associate XML Type Dialog

    Save and Associate XML Type Dialog

  3. Since the proposed qualified namespace of your new XML type is identical to the qualified name of your CUSTOMER data service, a type conflict will occur unless you modify either the namespace or the root name. Change the name from CUSTOMER to CUST_ORDER_DETAIL, then click OK. (This will also change the root name of your return type.)
  4. Open Design View. Notice that you now have an XML type.
  5. Build your project (or application).
  6. Execute your query through Test View. Results should show customer orders nested for each customer. (See partial results in Figure 6-12.)
  7. Figure 6-12 Test Results

    Test Results

Although there are several ways to go about accomplishing the same task. It is also important to be aware that there were points along the way where an effort to build or deploy your application would not have been successful because the query or the return type was not fully formed. Thus the order in which steps are accomplished can be significant.


Key Concepts of Query Function Building

The following terms and concepts are introduced in this section:

Data Sources

AquaLogic Data Services Platform supports multiple data sources including:

For details on importing data source metadata from these sources into AquaLogic Data Services Platform-based projects see Obtaining Enterprise Metadata.

Source Schemas and Return Types

The XQuery Editor uses XML schema representations as:

For more information see XML Types and Return Types.

XQuery Editor Components

Using the XQuery Editor, query functions can be built up graphically using a combination of graphical gestures and functions, including:

The following topics describe XQuery clauses as rendered in the XQuery Editor. (For information on the XQuery engine used by AquaLogic Data Services Platform and specific uses of XQuery in Source View see the AquaLogic Data Services Platform XQuery Developer's Guide. This document also contains references to the most up-to-state XQuery W3C specifications.)

Return Type Node

Query functions always map to a single return type. If your data service is associated with a return type, that type will appear in the Return node.

Figure 6-13 Sample Return Type

Sample Return Type

The return type can be thought of as extending the XML type to in support of:

When you click on a simple element in the return type, the expression on that element's constructor appears.

For Clause Nodes

A for clause node represents a named XQuery for clause construct. For and let clause nodes are always based data service functions.

Figure 6-14 Sample For Statement Node

Sample For Statement Node

By default, whenever you add a data service to the XQuery Editor work area, it is represented in a for node. The for node typically represents looping over a query function using either:

Parameterized Input

A for node, representing a parameterized query function, provides both Input and Output sections. As you would expect, parameters are mapped to the Input elements while Output elements either serve as input to other nodes or to the return type.

Figure 6-15 Example of Parameterized For Node

	Example of Parameterized For Node

For and Let Node Options

Table 6-16 shows options available when you right-click on the title of a for or let node.

Table 6-16 For or Let Node Right-click Options
Brings up a dialog which allows you to rename your node. Names cannot contain spaces.
Removes the node and any mappings in or out of the node from the work area.
Convert to let/for Clause
Changes the clause from a for to a let or from a let to a for. This operation is reversible.
Go to definition
Opens the data service that is represented by the node. The data service is opened to the current function in XQuery Editor View. However, if the function represents a physical data service (termed external in Source View), then the function definition in Source View appears. You can use the back arrow to return to your initial data service.
Relationship Functions
Relationship functions associated with the data service are listed. Selecting a relationship function allows your for or let node to serve as input for the relationship. See Adding Relationship Functions to an Existing Data Service for an illustration and code sample.
View Source
Shows the source underlying the currently selected node.

Converting Between For and Let Clauses

For and let clauses (see Let Statement Nodes) have many interchangeable characteristics.

The following code shows the conversion of the DataServices/RTLServices/Case/getCaseByCustID() function expression from a for clause:

declare function ns1:getCaseByCustID($cust_id as xs:string) as element(ns0:CASE)* {
for $x0 in ns1:getCase()
where $cust_id eq $x0/CustomerID
return $x0

to a let clause:

declare function ns1:getCaseByCustID($cust_id as xs:string) as element(ns0:CASE)* {
let $x0 := ns1:getCase()
where $cust_id eq $x0/CustomerID
return $x0

Let Statement Nodes

A let clause binds a sequence of elements (graphically contained in a node) to a variable that in turn becomes available to the FLWR expression.

Options available for use with for clauses are also available for let clauses. See For and Let Node Options.

Figure 6-17 Let Statement in the RTLServices/OrderSummaryView Data Service

Let Statement in the RTLServices/OrderSummaryView Data Service

When examining a let clause, you can read the assign string (:=) as the "be bound to". For example, in the following let clause:

let $x := (1, 2, 3)

Can be read as "let the variable named x be bound to the sequence containing the items 1, 2, and 3."

See also Converting Between For and Let Clauses.

Parameter Nodes

Parameter nodes enable you to associate a parameter with a for or let clause. Parameter nodes are created in the XQuery Editor work area (Figure 6-4). Three right-click menu options are available: Rename, Delete, and View Source.

Figure 6-18 XQuery Editor Add Parameter Dialog Box

XQuery Editor Add Parameter Dialog Box

You can create parameters that range from simple data elements to elements of any complexity.

Adding a Parameter Requiring a Simple Type

You can create a simple type parameter by selecting the type from the drop-down list and clicking Ok.

Figure 6-19 Setting a Simple Parameter Types

Setting a Simple Parameter Types

The act of mapping a parameter to a for or a let node containing an Input creates a parameterized query and also establishes a where condition. In Figure 6-20 the customer_id string parameter is dragged over the element in the ADDRESS node which is to be associated with the parameter through a where clause.

Figure 6-20 Parameter Mapped to a For Node

Parameter Mapped to a For Node

The corresponding Source View code highlights the parameter:

declare function ns5:getCaseView($custID as xs:string) as element(ns6:CaseView) {
for $Case in ns7:getCaseByCustID($custID)
return <CASE>
<CaseID> {fn:data($Case/CaseID)} </CaseID>
<CaseType> {fn:data($Case/CaseType)} </CaseType>
<ProductID> {fn:data($Case/ProductID)} </ProductID>
<Status> {fn:data($Case/Status)} </Status>
<StatusDate> {fn:data($Case/StatusDate)} </StatusDate>

When you invoke your function from an application — or execute your function in Test View — you will supply a value for your parameter.

Adding a Complex Parameter

Complex parameters are established by identifying a schema and a global element. Some schemas have only one global element.

Figure 6-21 Setting a Complex Parameter Type

Setting a Complex Parameter Type

The resulting parameter can be associated with any for or let node. See also Parameterized Input.

Using the Parameter Dialog to Create a WHERE Clause

You can use the parameter dialog to create a where clause condition simply by dragging the simple or complex parameter over an element in a for or let clause. In Figure 6-22 the newly created parameter productID is mapped to PRODUCT_ID. Since the $PRODUCT for node is selected, the where clause is in scope.

Figure 6-22 Parameterized Where Clause

Parameterized Where Clause

Adding Relationship Functions to an Existing Data Service

There are several ways to add relationship functions to existing data services. The recommended way is to use the right-click menu option available from for and let nodes, since this will created more appropriately nested clauses than simply dragging a relationship function from the Data Services Palette into the work area.

For example, if you want to create a logical data service that was a union of customer order and order line items, you could start with a customer order and add the related line item data.

Figure 6-23 takes the RTLApp DataServices/ApparelDB/CUSTOMER_ORDER() function and shows the process of adding the related getCUSTOMER_ORDER_LINE_ITEM() function.

Figure 6-23 Adding a Relationship Function

Adding a Relationship Function

The function initially appears as:

declare function tns:newFunction() as element(ns30:CUSTOMER_ORDER9)* {
    return $CUSTOMER_ORDER

Adding the relationship function changes it to:

declare function tns:newFunction() as element(ns30:CUSTOMER_ORDER9)* {

To complete this simple example you would need to add elements from the related data service to your return type and complete your mappings, as well as any transformations.

Group By Statement Nodes

The Group By node represents a single group by clause with zero or more grouping expressions. The top part of the Group By node defines variables available to the generated group by expression. The bottom part defines the grouping expression itself.

Group By expressions are often used with aggregation functions such as grouping customers by total sales. A for or let clause supports multiple group by elements.

You can generate a Group By node by right-clicking on any element in a for or let node and selecting Create Group By from the right-click menu.

Figure 6-24 Creating a Group By Expression

Creating a Group By Expression

In Figure 6-24 output will be grouped by the C_ID (customer ID) element. Once a GroupBy node is created, mappings to target objects — such as the return type — are done through the new node.

Figure 6-25 Projecting Total Orders Grouped by Customer ID

Projecting Total Orders Grouped by Customer ID

The default name of the group by node will be a unique name based on the local name of the for/let node. Thus the CUSTOMER_ORDER for clause becomes the basis for CUSTOMER_ORDER_group0. Group By nodes cannot be renamed from the XQuery Editor.

As seen in Figure 6-25, any node mappings are automatically transferred to the Group By node.

The resulting source is:

declare function tns:getCustomerOrderAmount() as element(ns5:CUSTOMER_ORDER)* {


If you delete a Group By node any mappings from the parent node will need to be redrawn.

Creating Multiple Group By Elements

In the example you can add additional grouping expressions simply by dragging new elements over the "By" separator, (Figure 6-26).

Figure 6-26 Adding a Second Group By Element

Adding a Second Group By Element

The act of dragging the element over an existing group by expression, adds a second group by expression, as shown in Figure 6-27.

Figure 6-27 The New Group By Expression Element

The effect of adding the second group by in the above example is to group total orders by their status value.

<ns0:CUSTOMER_ORDER5 xmlns:ns0="ld:DataServices/ApparelDB/CUSTOMER_ORDER5">
<ns0:CUSTOMER_ORDER5 xmlns:ns0="ld:DataServices/ApparelDB/CUSTOMER_ORDER5">
Using Multiple Group Nodes

You can create additional multiple Group By expressions to enable creation of logic such as:

Group by A, then
 Group by B

In order to do this you need to introduce an additional for or let clause to establish the parent-child structure that will support the needed logic.

To creating a second-level group by:

  1. Creating a child for clause. Right-click on the root element in your primary group by node and select Create For Clause.
  2. Create a new zone (see Setting Zones in Your Return Type) in your return type. There are several ways to do this. One is to Add a Child Element.
  3. Right-click on the new child element and select Mark as Zone.
  4. Set the zone of your new for clause to the new child element. Do this by dragging the zone symbol over your new child element. You will know you have succeeded when the newChildElement displays an array symbol.
  5. NewChildElement * empty

    And, when you mouse over the new child element, it will be highlighted, indicating that it is a zone unto itself.

  6. Create a group by right-clicking on the grouping element in the new for clause node.
  7. Replace the new child element by dragging the group by element over the new child element while holding down the control key. This effectively overwrites the element with the group by expression.
  8. Save and associate your new return type so that it become the XML type of your data service.

You can use Test View to verify your work.

Distinct By Statement Nodes

The Distinct By node represents a single distinct by clause.

Distinct by is useful:

Setting Conditions

Several types of conditions can be graphically applied to for and let clauses. You can create these conditions using a multifunction editor that appears at the bottom of XQuery Editor work area. (Figure 6-28).

Figure 6-28 Multifunction Condition Editor

Multifunction Condition Editor

To add or modify constraints for a for or let node first select the node, then click anywhere in the multifunction editor. Everything but your selected expression will become unavailable, as indicated by the "grayed out" appearance of unselected objects.

Condition types are:

Figure 6-29 provides a closer look at the multifunction dialog which includes the ability to:

Functions from the XQuery Function Palate can be dragged into the multifunction box and then edited.

Figure 6-29 Detail of Multifunction Box

Detail of Multifunction Box

The Where Clause

The where clause places a condition on a for and/or let clause. A where clause can be any query expression, including another FLWR expression. The where clause typically filters the number of matches in a FLWR loop.

A common use of the where clause is to specify a join between two sources. For example, consider the following query:

for $x in (1, 2, 3), $y in (2, 3, 4)
where $x eq $y

The where clause in this query filters (or joins or constraints) the results that match two sequences specified in the for clause. In this case, the numbers 2 and 3 match, and the query returns the following results:


To effect this in the XQuery Editor you would select the for or let clause to which the where condition applies. Then, in the where condition field, you enter:

$x eq $y

You can type in the name of an element or drag it from the a node in the work area into the multifunction editor.

The eq XQuery operator can be entered directly or selected from the conditional pop-up list (Figure 6-30).

Figure 6-30 Conditional Operator Selection List

Conditional Operator Selection List

Here is a more complete example involving an XQuery function (see Using XQuery Functions). It involves finding all customers whose first name is Jack.

Using a Where Clause as a Filtering Device

The following example illustrates the use of a where clause in the multifunction editor:

  1. Using the RTLApp sample application DataServices project create a new data service. Choose any name.
  2. Select the Add Function option from the Data Service menu. Use any name.
  3. Click on the new function name to enter the XQuery Editor.
  4. From the Data Services Palette (View Arrow symbol Windows Arrow symbol Data Services Palette) select the CUSTOMER() function from the CustomerDB/CUSTOMER data service; drag it into the work area.
  5. Associate the empty return type with the CUSTOMER elements by mapping the top node CUSTOMER element to the empty element in the return type while holding down the Control key (Ctrl-map).
  6. In your return type select Expand Complex Mapping from the right-click menu associated with the top element in your return type (now CUSTOMER).
  7. In the return type title select the Save and Associate right-click menu option associated with the return type title.
  8. You can create a valid XML type (schema file) for your new data service by associating your return type with your data service. The name of the global element in your return type or the alias assigned to the namespace or both needs to be changed because there already is a schema named CUSTOMER that was based on the physical data source you started with. (For details on Save and Associate see Creating a Simple Data Service Function.)

    If you change the name field CUSTOMER to CUSTOMER_WHERE and click Ok you will notice that the name of the complex element in your return type will change.

  9. Click on the title bar of the Customer node. This highlights the multifunction editor.
  10. Click on the Where clause icon (Figure 6-33). A field for the where clause appears.
  11. Click on FIRST_NAME in the CUSTOMER node.
  12. Add an equals operator following by "Jack" so that the entire clause appears as:
  13. $CUSTOMER/FIRST_NAME eq "Jack"

    Notice that the clause becomes red whenever your expression is invalid.

  14. In Test View run your new function. Notice in your results that the where conditions are fulfilled.

See also Using the Parameter Dialog to Create a WHERE Clause.

The Order By Clause

The order by clause indicates output order for a given set of data.

Unless otherwise specified, the order data appears will follow the XML tree. This is known as the document order. The order by keyword indicates that the content should be sorted in ascending order by the identified element(s).

XQuery keywords such as descending are supported. For example, an XQuery can be written that orders the customers by last name in descending order:

for $customer in document('customers.xml')//customer
order by last_name descending

In the XQuery Editor you would select the for or let clause to which the order by condition applies and in the order by condition field enter:

last_name descending

You can type in the name of an element or drag it from the work area into the multifunction editor Figure 6-29.

Creating Join Conditions

Join conditions are represented as equality relationships in where clauses. Therefore you can create such an equality relationship by dragging and dropping the eq function onto a row in the Conditions tab and then selecting two source elements/attributes into the same row.

Using XQuery Functions

AquaLogic Data Services Platform contains a full set of built-in XQuery functions. Most XQuery functions in the XQuery Function Palette are standard XQuery functions supported by the W3C. However, there are several BEA-specific functions as well as several extensions to the language. (For details on the BEA implementation of the 1.0 XQuery engine see XQuery Developer's Guide. For more detailed information on standard XQuery functions, see the W3C XQuery 1.0 and XPath 2.0 Functions and Operators specification.)

The functions available from the XQuery Functions palette help you create conditions around for and let clauses. XQuery functions can be used in several contexts:

Using XQuery Functions in Where Clauses

To create a where clause condition that filters customers a query returns you can follow these steps:

  1. Follow steps 1-7 under Using XQuery Functions in Where Clauses on page 6-36.
  2. Click on the title bar of your CUSTOMER node.
  3. Click the Where icon (see The Where Clause) to create a new where condition.
  4. Open the XQuery Function palette (View Arrow symbol Windows Arrow symbol XQuery Function Palette).
  5. Drag the fn:string-length() as xs:integer function from the XQuery Palette into the Where condition.
  6. Figure 6-31 XQuery Palette

    XQuery Palette

  7. Using the condition and expression built-in line editor highlight the function argument ($arg).
  8. Click on $CUSTOMER/LAST_NAME. The string appears as:
  9. Where fn:string-length($CUSTOMER/LAST_NAME)
  10. Add <5 as the predicate so the string appears as:
  11. Where fn:string-length($i/ORDERID)>5
    Figure 6-32 Editing an XQuery Function

    Editing an XQuery Function

  12. Click the checkmark in the editor.
  13. If you mouse over the title of your for clause, you can see that the condition has been associated with the fragment. You can also verify this change in source view.

    Figure 6-33 Mouseover of Node Title Displays Its Conditions

    Mouseover of Node Title Displays Its Conditions

    When you run the function only records with LAST_NAMEs shorter than five characters will appear.

Automatic type casting generally ensures that input parameters used in functions and mappings are appropriate to the function in which they are used.

Transforming Data Using XQuery Functions

There are many transformational XQuery functions. In the following example the concat() function is used to quickly enrich data returned from a physical data service by adding functionality to the expression associated with an element returned by the function.

  1. Follow steps 1-7 under Using XQuery Functions in Where Clauses on page 6-36.
  2. Open the XQuery Function palette.
  3. In the return type add a child element.
  4. Rename it to NAME_ID_STATEMENTSTATUS. Initially no type is assigned to the element. This will be derived from the element or function mapped to it.
  5. Click on your new element.
  6. Then click in the expression field of the multifunction editor.
  7. Drag the fn:concat($arg1,$arg2,...) function into the expression field.
  8. Figure 6-34 Creating a Concatinated Element in the Return Type

    Creating a Concatinated Element in the Return Type

  9. Highlight the first argument ($arg1) and click on FIRST_NAME in the $CUSTOMER node. Similarly, select $arg2 and click on LAST_NAME. Select the ellipses and then click on ONLINE_STATEMENT.
  10. The concat() function requires that all input parameters be of type string. Since ONLINE_STATEMENT of type short, it needs to be cast as a string. You can do this through the editor. Similarly, you can add spaces and a small legend to make the results more readable.
  11. When your editing is complete, the XQuery function will appear as:

    {fn:concat( $CUSTOMER/FIRST_NAME, '  ',$CUSTOMER/LAST_NAME,' | ',($CUSTOMER/ONLINE_STATEMENT cast as xs:string),' (online=1; printed=0)')}
  12. Check the green box to accept your changes.
  13. Since you made changes to the return type schema, rebuild your application.
  14. Notice also (Figure 6-35) how the new functionality is reflected in the source-to-target mapping.

    Figure 6-35 XQuery Editor Work Area After Adding an Element Containing a Function to the Return Type

    XQuery Editor Work Area After Adding an Element Containing a Function to the Return Type

  15. When you run you program in Test View results will now include the following type of information:
        Jack Black | 1 (online=1; printed=0)

Setting Expressions

The Expression editor is most commonly used to edit return type expressions. For example, if the return type contains:

ORDERID xsd:int

The editor can be used to limit the scope of the expression to a single customer:

Expression>{fn:data($o/ORDERID)} eq "1001"

Prototypes of functions available from the XQuery Function Palette can be dragged into the editor or you can use the build-in line editor to enter them yourself.

Figure 6-36 Expression Editor

Expression Editor

Operation of the Expression editor is similar to that for the multifunction box. When you select a element other workspace artifacts are grayed out. However, you can drag elements from any part of the work area into the Expression Editor.

XQuery operators are available as a drop down list, as shown in Figure 6-30, or you can simply type them in.


Managing Query Components

If you think of selected data elements as nouns (what you want to work on), the functions as verbs (the action), then the mapping among the data elements creates a logical sentence that expresses the query.

Results and query performance can change significantly depending on how you:

Although you can simply type in an XQuery and run it from Test View, the more common way to create a query is build it up through the following operations:

Note: Some operations are not deterministic. For example if a node has elements mapped to a return type, deleting the node before removing the mappings may create error conditions. Instead you can use Undo and then delete the mappings or you can make the necessary changes in Source View.


Working With Data Representations and Return Type Elements

Mapping elements involves establishing a visual relationship between data source elements and the return type or an intermediary node requiring input parameters.

There are two types of schema elements: simple and complex. Complex elements contain elements and/or attributes.

Figure 6-37 Expanded Schema Showing Complex and Simple Elements

Expanded Schema Showing Complex and Simple Elements

To expand a complex element, click on the plus sign (+) to the left of its name. (If you double click on the name itself, you will enter edit mode.)

Mapping to Return Types

As shown in Creating a Simple Data Service Function, the XQuery Editor automatically generates queries based on graphical mappings into a return type.

The XQuery Editor supports two types of mappings: value mappings and complex element mappings. Value mappings map (assign) only the value of an element or attribute from a source to the value of its target element or attribute. Element mappings allow mapping source elements (simple or complex) to target.

In order to map an element to a return type, that element needs to be in scope. If the element you are attempting to map is not in scope, a message will appear indicated that the mapping is invalid (see XX). Invalid mappings occur whenever the underlying for or let statement would not be able to validly handle the association of the data element(s) with the return type schema.

Figure 6-38 Invalid Mapping Attempt Flagged by Alert

Invalid Mapping Attempt Flagged by Alert

For more information on element scoping and other related issues see XML Types and Return Types and Editing XML Types and Return Types.

Mapping Elements and Attributes to the Type

A questionmark symbol [?] next to an element name represents an optional element, meaning that it is not required by the query. Primary keys are never optional.

Complex Element Mappings to a Return Type

You can rapidly map complex elements from source to your return type. This known as an induced mapping is useful where all or part of the return type should match source representations.

There are many situations when you will find it convenient to map elements into your type, including:

If the match is not exact, mapping a complex element to your return type will be appended.

There are several benefits of mapping or projecting elements:

Figure 6-39 shows the results of the mapping of a complex element to a return type.

Figure 6-39 Example of Mapping of a Complex Element

Example of Mapping of a Complex Element

Note: You cannot map multiple elements to a single target element.
Source-to-Target Mapping Options

Three source-to-return type gesture mappings are available — value mappings, overwrite mappings, and append mappings.

Note: Any changes you make to a return type should be propagated to your data services XML type using the Save and Associate XML Type right-click option, available from the return type titlebar.

Removing Mappings

You can delete mappings between elements by selecting the mapping line (link) and pressing Delete. Alternatively, use the Delete key.

Modifying a Return Type

The shape of the information returned by your query is determined by its return type. Using a combination of mapping techniques and return type options you can:

You should only modify a return type if you intend to propagate the change to the data service's XML type using the Save and Associate XML Type command, described in Creating a Simple Data Service Function.

Editing a Return Type

You can edit your return type by right-clicking any element. Editing options for a type in the XQuery Editor are somewhat different options described in Editing an XML Type. For example, in a return type you can create zones automatically add for clauses to your query, allowing for a "master-detail" arrangement of results.

Caution: While it is possible to modify a return type and run a query in an manner, problems will likely arise when your application calls a query with a mismatch between the return clause and the XML type of the data service.

Table 6-41 describes notable return type editing options.

Table 6-41 Notable Return Type Right-click Menu Options
Add Child Element
Creates a child element for the currently selected element.
Add Complex Child Element
Allows you to specify a schema and type for a new complex child element. By default, the type is the root element of the schema. If the schema has several global elements, however, you will first need to specify the element that you want to become the root.
Add Attribute
Creates an attribute for the selected element.
Make Conditional
Inserts an element named Conditional above the currently selected element and clones the element (and children, if any).
Conditional elements can be used in conjunction with if-then-else constructs. Transformational logic can then be developed through the XQuery Editor and mapped to the appropriate branch of the condition.
Duplicates the selected element (and children, if any) to the same level of the schema hierarchy.
If you clone a simple element an unmapped, untyped element of the same name will be created.
Mark as Zone /
Remove Zone
Sets (or removes) a zone setting for the current element and its children (if any).
If the elements are in a zone the query will return them in a master-detail arrangement. See Setting Zones in Your Return Type.
Deletes the selected element and any child elements or attributes.
The Find dialog allows you to search for text strings in the return type with options to match case, match whole words only, use wildcards (*,?), or regular expressions.

A special option, Expand Complex Mappings, is becomes available for use with Induced mappings. See Complex Element Mappings to a Return Type for details.

There are several things to keep in mind when making changes to a return type:

Adding a Complex Child Element

You can add a complex child element to a return type by selecting a schema and identifying a global element (a type). Complex child elements incorporate data service schemas (.xsd file) into the return type.

To add a complex global element to your return type:

  1. Click on the element you want to be the parent of the complex element.
  2. Right-click and select Add Complex Child Element.
  3. In the dialog that appears navigate to the schema you want to use. If your schema only has one global element, then it will be automatically selected. Otherwise, you will need to pick which global element to use.
Note: When you add a complex child element it will be place at the end of its peers in the return type.

Setting Zones in Your Return Type

In AquaLogic Data Services Platform return types zones identify how query results will be arranged. Adding or changes zones through the XQuery Editor is the same as adding or changing the order of subordinate for statements in Source View. (For a detailed example of building a logical data service that makes use of zones to create a nested master-detail arrangement of data see Creating a Simple Data Service Function.

For example in Figure 6-42 the CUSTOMER_ORDER elements for a particular customer will be grouped under that customer.

Figure 6-42 Sample Return Type With Two Zones

Sample Return Type With Two Zones

By default, return types have only a single zone. However, without additional zones elements simply repeat in their natural order. In the simple example shown in Figure 6-42 this would mean that if a customer had more than one order, both the customer information and the order information would be repeated it your report until all matching orders had appeared.

The following slightly simplified XML illustrates a single-zone approach.


Notice the repetition of CUSTOMERNAME and CUSTOMERID.

XQuery source for a similar function clearly shows why this is:

return <ns2:CUSTOMER7>


If you were, however, to create a repeatable zone around the CUSTOMER_ORDER element, a subordinate for clause will be introduced in Source View.

for $CUSTOMER in ns0:CUSTOMER() 
return <ns2:CUSTOMER7>

Specifically the highlighted where clause in the second code fragment mandates that all orders be collected under a single instance of customer.

To create a zone simply right-click on an element and select Mark as Zone. Once created, the zone will appear highlighted whenever you move your cursor into areas under its control (Figure 6-42).

Associating XQuery Editor Nodes With Zones

In XQuery for, let, and group by clauses can enclose other for, let, or group by clauses. Similarly, nodes representing these constructs can be associated with return type zones using the create zone icon in the titlebar of the node (see Figure 6-10 in the XQuery Editor example at the beginning of this chapter). Simply drag the icon over an existing zone to associate the node with the zone.

To verify that the operation is successful mouse-over the zone icon after the association is complete. If successful, the appropriate zone will be highlighted (see Figure 6-42). Alternatively, look at Source View to verify that your operation has been successful or simply run your query under Test View.

Note: The order in which you create zones and other aspects of your XQuery in the XQuery Editor can be significant. For example, zones should be created before creating a where clause associating two nodes.
Removing Zones

To remove a zone, right-click on the parent element in the zone and select the Remove Zone option.

Validating and Saving Your Return Type

You can make changes in your function's return type and, optimally, bring your data service into conformance with the changes that you have made.

Figure 6-43 Return Type Management Options

Return Type Management Options

Several right-click menu options are available for managing the return type, including:

  Back to Top       Previous  Next