Client Application Developer’s Guide

Advanced Topics

This chapter describes miscellaneous features that are related to client programming with BEA AquaLogic Data Services Platform. It includes the following topics:

ALDSP Control Source Upgrade

You need to upgrade ALDSP 8.x controls to 9.x using source upgrade. After the upgrade, a version of ALDSP Control.jar is placed in the WEB-INF/lib folder. The Control.jar file contains control runtime classes.

While performing the upgrade, ensure that the domain to which the Web-App is to be deployed includes the following files:

Source upgrade also upgrades the schemas used by ALDSP Control.

For more information on upgrading ALDSP Control, refer to Upgrading an ALDSP Control from 2.5 to 3.0 section in the Installation Guide.

Accessing Metadata Using Catalog Services

BEA AquaLogic Data Services Platform maintains metadata about data services, application, functions, and schemas through Catalog Services, which is a system catalog-type data service. Catalog services provide a convenient way for client-application developers to programmatically obtain information about Data Services Platform applications, data services, schemas, functions, and relationships.

Catalog Services are also data services; you can view them using the DSP Console, the ALDSP Palette, and ALDSP Controls.

Some advantages of using Catalog Services are as follows:

This section provides details about installing and using Catalog Services to access metadata for any Data Services Platform application. It includes the following topics:

Installing Catalog Services

You can install Catalog Services as a project for an ALDSP application or as a JAR file that is added to the Library folder in Data Services Studio. The Catalog Services project (_catalogservices) contains data services that provide information about the application, folders, data services, functions, schemas, and relationships available with the application.

DataServiceRef and SchemaRef are additional data services that consist of functions that retrieve the paths to the data services and schemas available with the Data Services Platform application. For more information about the data services and functions available with Catalog Services, refer to Using Catalog Services on page 9-4.

To install Catalog Services as a project:

Using Catalog Services

After installing Catalog Services, the catalog services project, _catalogservices, is created for the Data Services Platform application. All the data services associated with catalog services are available under this project. You can invoke the data service functions to access metadata. The client Mediator API is used to invoke the Catalog Service methods.

The data services available under _catalogservices include:

Application (application.ds)

The following table provides the declaration and description for the getApplication()function in Application.ds.

DataService (DataService.ds)

Table 9-3 provides declaration and description information for the functions available in DataService.ds.

DataServiceRef (DataServiceRef.ds)

The following table provides the declaration and description for the functions available in DataServiceRef.ds.

Folder (folder.ds)

The following table provides the declaration and description for the functions available in Folder.ds.

Function (Function.ds)

The following table provides the declaration and description for the functions in Function.ds.

Relationship (Relationship.ds)

The following table provides the declaration and description for the functions available in Relationship.ds.

Schema (Schema.ds)

The following table provides the declaration and description for the functions available in Schema.ds

SchemaRef (SchemaRef.ds)

The following table provides the declaration and description for the functions available in SchemaRef.ds.

Filtering, Sorting, and Fine-tuning Query Results

The Filter API enables client applications to apply filtering conditions to the information returned by data service functions. In a sense, filtering allows client applications to extend a data service interface by allowing the application to specify more about how data objects are to be instantiated and returned by functions.

The Filter API alleviates data service designers from having to anticipate every possible data view that clients may require and to implement a data service function for each view. Instead, designers can choose to specify a broader, more generic interface for accessing a business entity and allow client applications to control views as desired through filters.

Using the API, you can specify that only objects that meet a particular condition in the function return set be returned to the client. A filter is therefore similar to a WHERE clause in an XQuery or SQL statement—it applies conditions to a possible result set. You can apply multiple filter conditions using AND and OR operators.

The effects of a filter can vary, depending on the desired results. Consider, for example, the CUSTOMERS data object shown in Figure 9-10. The data object contains multiple complex elements (CUSTOMER and ORDERS) and several simple elements, including ORDER_AMOUNT.

You can apply a filter to any element in this hierarchy. For example, you could apply a filter to return all CUSTOMER objects but filter ORDERS than have an ORDER_AMOUNT greater than 1000. Similarly, you could apply a filter to return only the CUSTOMER objects that have at least one large order.

You can also use a filter to specify the order criteria (ascending or descending) in which results should be returned from the data service. Finally, you can use a filter to set the maximum number of results to be returned.

Introducing the Filter API

You specify filters using the FilterXQuery object, which includes the following methods enabling you to add a filter, create a filter to apply later, specify the sort order, and set a limit on the number of results returned:

addFilter()

The addFilter() method enables you to create a filter and add it to the list of filters. The addFilter() method has several signatures with different parameters, including the following:

public void addFilter(java.lang.String appliesTo,
                      java.lang.String field,
                      java.lang.String operator,
                      java.lang.String value,
                      java.lang.Boolean everyChild)

This version of the method takes the following arguments:

createFilter()

The createFilter() method enables you to create a filter that you can later apply to any of the objects in the hierarchy. The createFilter() method has several signatures with different parameters, including the following:

public void createFilter(java.lang.String field,
                         java.lang.String operator,
                         java.lang.String value,
                         java.lang.Boolean everyChild)

This version of the method takes the following arguments:

addOrderBy()

The addOrderBy() method enables you to add a sort criteria (either ascending or descending) to the specified object. The addOrderBy() method has the following signature:

public void addOrderBy(java.lang.String appliesTo,
                       java.lang.String field,
                       java.lang.String sort)

The method takes the following arguments:

setLimit()

The setLimit() method enables you to specify the maximum number of entries to return of the specified object. The setLimit() method has the following signature:

public void setLimit(java.lang.String appliesTo,
                     java.lang.String max)

The method takes the following arguments:

Exploring the Filter Operators

Table 9-11 describes the operators that you can apply to filter conditions.

Using Filters

Filtering capabilities are available to Mediator and ALDSP Control client applications. To use filters in a mediator client application, import the appropriate package and use the supplied interfaces for creating and applying filter conditions.

Data service control clients get the interface automatically. When a function is added to a control, a corresponding "WithFilter" function is added as well.

The filter package is named as follows:

	com.bea.ld.filter.FilterXQuery; 

To use a filter, perform the following steps:

Filtering Examples

In general, with nested XML data, a condition such as “CUSTOMER/ORDER/ORDER_AMOUNT > 1000” can affect what objects are returned in several ways. For example, it can cause all CUSTOMER objects to be returned, but filter ORDERS that have an amount less than 1000.

Alternatively, it can cause only CUSTOMER objects to be returned that have at least one large order, but containing all ORDERs (small and large) for each such CUSTOMER.

The following examples show how filters can be applied in several different ways:

Specifying a Compound Filter

You can create a filter with two conditions using logical AND and OR operators. Listing 9-1 uses the AND operator to apply a combination of filters to a result set, given a data service instance customerDS.

FilterXQuery myFilter = new FilterXQuery();
Filter f1 = myFilter.createFilter("CUSTOMER_PROFILE/ADDRESS/ISDEFAULT",
		 			FilterXQuery.NOT_EQUAL,"0");
Filter f2 = myFilter.createFilter("CUSTOMER/ADDRESS/STATUS",
					FilterXQuery.EQUAL,
					"\"ACTIVE\"");
Filter f3 = myFilter.createFilter(f1,f2, FilterXQuery.AND);
Customer customerDS = Customer.getInstance(ctx, "RTLApp");
CustomerDS.setFilterCondition(myFilter);

Ordering and Truncating Data Service Results

You can specify the order criteria (ascending or descending) in which results should be returned from the data service. The addOrderBy() method accepts a property name as the criterion upon which the ascending or descending decision is based.

Listing 9-2 provides an example of creating a filter to return customer profiles in ascending order, based on the date each person became a customer.

FilterXQuery myFilter = new FilterXQuery();
myFilter.addOrderBy("CUSTOMER_PROFILE",
			"CustomerSince" ,FilterXQuery.ASCENDING);
ds.setFilterCondition(myFilter);
DataObject objArrayOfCust = (DataObject) ds.invoke("getCustomer", null);

Similarly, you can set the maximum number of results to be returned using the setLimit() method. Listing 9-3 shows how to use the setLimit() method to limit the number of active addresses in the result set to 10, given a data service instance ds.

FilterXQuery myFilter = new FilterXQuery();
Filter f2 = myFilter.createFilter("CUSTOMER_PROFILE/ADDRESS",
                                   FilterXQuery.EQUAL,"\"INACTIVE\"");
myFilter.addFilter("CUSTOMER_PROFILE", f2);
myFilter.setLimit("CUSTOMER_PROFILE", "10");
ds.setFilterCondition(myFilter);

Using Ad Hoc Queries to Fine-tune Results from the Client

An ad hoc query is an XQuery function that is not defined as part of a data service, but is instead defined in the context of a client application. Ad hoc queries are typically used in client applications to invoke data service functions and refine the results in some way. You can use an ad hoc query to execute any valid XQuery expression against a data service. The expression can target the actual data sources that underlie the data service, or can use the functions and procedures hosted by the data service.

To execute an XQuery expression, use the PreparedExpression interface, available in the Mediator API. Similar to JDBC PreparedStatement interface, the PreparedExpression interface takes the XQuery expression as a string in its constructor, along with the JNDI server context and application name. After constructing the prepared expression object in this way, you can call the executeQuery( ) method on it. If the ad hoc query invokes data service functions or procedures, the data service’s namespace must be imported into query string before you can reference the methods in your ad hoc query.

Listing 9-4 shows a complete example; the code returns the results of a data service function named getCustomers( ), which is in the namespace:

ld:DataServices/RTLServices/Customer

import com.bea.ld.dsmediator.client.PreparedExpression;

String queryStr = 
      "declare namespace ns0=\"ld:DataServices/RTLServices/Customer\";" +
      "<Results>" +
      "  { for $customer_profile in ns0:getCustomer()" +
      "     return $customer_profile }" +
      "</Results>";
PreparedExpression adHocQuery = 
      DataServiceFactory.prepareExpression(context,"RTLApp",queryStr );
XmlObject objResult = (XmlObject) adHocQuery.executeQuery();

ALDSP passes information back to the ad hoc query caller as an XMLObject data type. Once you have the XMLObject, you can downcast to the data type of the deployed XML schema. Since XMLObject has only a single root type, if the data service function returns an array, your ad hoc query should include a root element as a container for the array.

For example, the ad hoc query shown in Listing 9-4 specifies a <Results> container object to hold the array of CUSTOMER_PROFILE elements that will be returned by the getCustomer() data service function.

Security policies defined for a data service apply to the data service calls in an ad hoc query as well. If an ad hoc query uses secured resources, the appropriate credentials must be passed when creating the JNDI initial context. (For more information, see Obtaining the WebLogic JNDI Context for ALDSP on page 3-44.)

As with the PreparedStatement interface of JDBC, the PreparedExpression interface supports dynamically binding variables in ad hoc query expressions. PreparedExpression provides several methods (bindType( ) methods; see Table 9-12), for binding values of various data types.

To use the bindType methods, pass the variable name as an XML qualified name (QName) along with its value; for example:

adHocQuery.bindInt(new QName("i"),94133);

Listing 9-5 shows an example of using a bindInt() method in the context of an ad hoc query.

PreparedExpression adHocQuery = DataServiceFactory.preparedExpression(
                 context, "RTLApp", 
                "declare variable $i as xs:int external;
                 <result><zip>{fn:data($i)}</zip></result>");
adHocQuery.bindInt(new QName("i"),94133);
XmlObject adHocResult = adHocQuery.executeQuery();

http://www.w3.org/TR/xmlschema-2/#QName

Listing 9-6 shows a complete ad hoc query example, using the PreparedExpression interface and QNames to pass values in bind methods.

import com.bea.ld.dsmediator.client.DataServiceFactory;
import com.bea.ld.dsmediator.client.PreparedExpression;
import com.bea.xml.XmlObject;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.xml.namespace.QName;
import weblogic.jndi.Environment;

public class AdHocQuery
{
   public static InitialContext getInitialContext() throws NamingException {
    Environment env = new Environment();
    env.setProviderUrl("t3://localhost:7001");
    env.setInitialContextFactory("weblogic.jndi.WLInitialContextFactory");
    env.setSecurityPrincipal("weblogic");
    env.setSecurityCredentials("weblogic");
    return new InitialContext(env.getInitialContext().getEnvironment());
   }

   public static void main (String args[]) {
     System.out.println("========== Ad Hoc Client ==========");
     try {
      StringBuffer xquery = new StringBuffer();
      xquery.append("declare variable $p_firstname as xs:string external; \n");
      xquery.append("declare variable $p_lastname as xs:string external;  \n");
 
      xquery.append(
       "declare namespace ns1=\"ld:DataServices/MyQueries/XQueries\"; \n");
      xquery.append(
       "declare namespace ns0=\"ld:DataServices/CustomerDB/CUSTOMER\"; \n\n");

      xquery.append("<ns1:RESULTS>                                    \n");
      xquery.append("{                                                \n");
      xquery.append("    for $customer in ns0:CUSTOMER()              \n");
      xquery.append("    where ($customer/FIRST_NAME eq $p_firstname  \n");
      xquery.append("       and $customer/LAST_NAME eq $p_lastname)   \n");
      xquery.append("    return                                       \n");
      xquery.append("      $customer                                  \n");
      xquery.append(" }                                               \n");
      xquery.append("</ns1:RESULTS>                                   \n");

         PreparedExpression pe = DataServiceFactory.prepareExpression(
                        getInitialContext(), "RTLApp",  xquery.toString());
         pe.bindString(new QName("p_firstname"), "Jack");
         pe.bindString(new QName("p_lastname"),  "Black");
         XmlObject results = pe.executeQuery();
         System.out.println(results);

       } catch (Exception e) {
           e.printStackTrace();
       }
}