User’s Guide

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

XQuery Implementation

ALSB uses the BEA AquaLogic Data Services Platform implementation of the XQuery engine which fully supports all of the language features that are described in the World Wide Web (W3C) specification for XQuery with one exception: modules. For more information about the XQuery 1.0 and XPath 2.0 functions and operators (W3C Working Draft 23 July 2004), see the following URL:

http://www.w3.org/TR/2004/WD-xpath-functions-20040723/

ALSB supports the following XQuery functions:

Note: All of the BEA function extensions use the following function prefix fn-bea: In other words, the full XQuery notation for an extended function is of this format:
fn-bea: function_name.

 


Supported Function Extensions from AquaLogic Data Services Platform

ALSB supports all function extensions that BEA AquaLogic Data Services Platform provides except for the following:

BEA recommends that you do not use the following functions in ALSB—they are better covered by other language features:

For a list of all AquaLogic Data Services Platform function extensions and a description of each function, see BEA XQuery Implementation in the XQuery Developer's Guide.

 


Function Extensions from ALSB

ALSB provides the following XQuery functions:

fn-bea:lookupBasicCredentials

The fn-bea:lookupBasicCredentials function returns the user name and unencrypted password from a specified service account. You can specify any type of service account (static, pass-through, or user-mapping). See Service Account in Using the AquaLogic Service Bus Console.

Use the fn-bea:lookupBasicCredentials function as part of a larger set of XQuery functions that you use to encode a user name and password in a custom transport header or in an application-specific location within the SOAP envelope. You do not need to use this function if you only need user names and passwords to be located in HTTP Authentication headers or as WS-Security user name tokens. ALSB already retrieves user names and passwords from service accounts and encodes them in HTTP Authentication headers or as WS-Security user name tokens when required.

The function has the following signature:

fn-bea:lookupBasicCredentials( $service-account as xs:string ) as UsernamePasswordCredential

where $service-account is the path and name of a service account in the following form:

project-name[/folder[...]]/service-account-name

The return value is an XML element of this form:

<UsernamePasswordCredential
   xmlns="http://www.bea.com/wli/sb/services/security/config">
   <username>
name</username>
   <password>
unencrypted-password</password>
</UsernamePasswordCredential>

You can store the returned element in a user-defined variable and retrieve the user name and password values from this variable when you need them.

For example, your ALSB project is named myProject. You create a static service account named myServiceAccount in a folder named myFolder1/myFolder2. In the service account, you save the user name of pat with a password of patspassword.

To get the user name and password from your service account, invoke the following function:

fn-bea:lookupBasicCredentials( myProject/myFolder1/myFolder2/myServiceAccount )

The function returns the following element:

<UsernamePasswordCredential
   xmlns="http://www.bea.com/wli/sb/services/security/config">
   <username>pat</username>
   <password>patspassword</password>
</UsernamePasswordCredential>

fn-bea: uuid()

The function fn-bea:uuid() returns a universally unique identifier. The function has the following signature:

fn-bea:uuid() as xs:string

You can use this function in the proxy pipeline to generate a unique identifier. You can insert the generated unique identifier into an XML document as an element. You cannot generate a unique identifier to the system variable. You can use this to modify a message payload.

For example, suppose you want to generate a unique identifier to add to a message for tracking purposes. You could use this function to generate a unique identifier. The function returns a string that you can add it to the SOAP header.

fn-bea:execute-sql()

The fn-bea:execute-sql() function provides low-level database access from XQuery within ALSB message flows--see Accessing Databases Using XQuery. The query returns a sequence of flat row elements with typed data.

The function has the following signature:

fn-bea:execute-sql( $datasource as xs:string, $rowElemName as xs:QName, $sql as xs:string, $param1, ..., $paramk) as element()*

where

The return value is a sequence of flat row elements with typed data and automatically translates values between SQL/JDBC and XQuery data models. Data Type mappings that the XQuery engine generates or supports for the supported databases can be found in the XQuery-SQL Mapping Reference.

When you execute the fn-bea:execute-sql() function from an ALSB message flow, you can store the returned element in a user-defined variable.

Use the following examples to understand the use of the fn-bea:execute sql() function in ALSB:

Example 1: Retrieving the URI from a Database for Dynamic Routing

ALSB proxy services support specification of the URI to which messages are to be routed at run time (dynamically)—see Using Dynamic Routing. Listing 9-1 is an example use of the fn-bea:execute-sql() function to retrieve the URI from a database in a dynamic routing scenario.

Listing 9-1 Get the URI for a Business Service from a Database
<ctx:route><ctx:service>
{
    fn-bea:execute-sql(
    'ds.myJDBCDataSource', 
    xs:QName('customer'), 
    'SELECT targetService FROM DISPATCH_MAPPING WHERE customer_priority=?',
      xs:string($body/m:Request/m:customer_pri/text())
    )/TARGETSERVICE/text()
}
</ctx:service></ctx:route>

In Listing 9-1:

The DISPATCH_MAPPING table is populated as shown in Listing 9-2:

Listing 9-2 DISPATCH_MAPPING Table
 INSERT INTO DISPATCH_MAPPING (customer_priority, targetService, soapPayload)
 VALUES ('0001', 'system/UCGetURI4DynamicRouting_proxy1', '<something/>');
 INSERT INTO DISPATCH_MAPPING (customer_priority, targetService, soapPayload)
 VALUES ('0002', 'system/UCGetURI4DynamicRouting_proxy2', '<something/>');
Note: The third column in the table (soapPayload) is not used in this scenario.

Executing the fn-bea:execute-sql for Example 3

If the XQuery in Listing 9-1 is executed as a result of a proxy service receiving the request message in Listing 9-3 (note that the value of <customer_pri> in the request message is 0001), the URI returned for the dynamic route scenario is

system/UCGetURI4DynamicRouting_proxy1

(See also Listing 9-2.)

Listing 9-3 Example Request Message $body
<m:Request xmlns:m="http://www.bea.com/alsb/example"> 
<m:customer_pri>0001</m:customer_pri>
</m:Request>

Example 2: Getting XMLType Data from a Database

Data Type mappings that the XQuery engine generates or supports for the supported databases can be found in the XQuery-SQL Mapping Reference. Note that the XMLType column type in SQL is not supported. However, you can access the data in an XMLType column by using the getStringVal() method of the XMLType object to convert it to a String value.

The following scenario outlines a procedure you can use to select data from an XMLType column in an Oracle database.

  1. Use an assign action in a proxy service message flow to assign the results of the following XQuery to a variable ($result).
  2. Listing 9-4 Get XMLType Data from a Database
    fn-bea:execute-sql(
        'ds.myJDBCDataSource', 
        'Rec', 
        'SELECT a.purchase_order.getStringVal() purchase_order from datatypes a'
    )

    where:

    • ds.myJDBCDataSource is the JNDI name to the data source
    • Rec is the $rowElemName—therefore, Rec is the QName given to each element of the resulting element sequence
    • select a.purchase_order.getStringVal() ... is the SQL statement that uses the getStringVal() method of the XMLType object to convert it to a String value
    • datatypes is the table from which the value of the XML is read (the datatypes table in this case contains one row)
    • Note: The following is the table definition for the dataty.pes table:
      create table datatypes 
      (
        purchase_order xmltype
      );
  3. Use a replace action to replace the node contents of $body with the results of the fn-bea:execute-sql() query (assigned to $result in the preceding step):
  4. Replace [ node contents ] of [ undefined XPath ] in [ body ] with 
    [ $result/purchase_order/text() ]

    The following listing shows $body after the replacement.

Note: The datatypes table contains one row (with the purchase order data); the row contains the XML represented in Listing 9-5.
Listing 9-5 $body After XML Content is Replaced with Result of fn-bea:execute-sql()
<soap-env:Body>
  <openuri:orders xmlns:openuri="http://openuri.com/"> 
    <openuri:order> 
      <openuri:customerID>123</openuri:customerID> 
      <openuri:orderID>123A</openuri:orderID> 
    </openuri:order> 
    <openuri:order> 
      <openuri:customerID>345</openuri:customerID> 
      <openuri:orderID>345B</openuri:orderID> 
    </openuri:order> 
    <openuri:order> 
      <openuri:customerID>789</openuri:customerID> 
      <openuri:orderID>789C</openuri:orderID> 
    </openuri:order> 
  </openuri:orders> 
</soap-env:Body>

fn-bea:serialize()

You can use the fn-bea:serialize() function if you need to represent an XML document as a string instead of as an XML element. For example, you may want to exchange an XML document through an EJB interface and the EJB method takes String as argument. The function has the following signature:

fn-bea:serialize($input as item()) as xs:string


  Back to Top       Previous  Next