Filtering, Sorting, and Truncating XML Data

When designing your data service, you can specify read functions that filter data service return values. However, instead of trying to create a read function for every possible client requirement, you can create generalized read functions to which client applications can apply custom filtering or ordering criteria at runtime.

Objectives

Overview

Data users often want to access information in ways that are not anticipated in the design of a data service. The filtering and ordering API allow client applications to control what data is returned by a data service read function call based on conditions specified at runtime.

Although you can specify read functions that filter data service return values, it may be difficult to anticipate all the ways that client applications may want to filter return values. To deal with this contingency, ALDSP lets client applications specify dynamic filtering, sorting, and truncating criteria against the data service. These criteria are evaluated on the Server, before being transmitted on the network, thereby reducing the data set results to items matching the criteria. Where possible, these instances are "pushed down" to the underlying data source, thereby reducing the data set returned to the user.

The advantage of the FilterXQuery class is that you can define client-side filtering operations, without modifying or re-deploying your data services.

11.1 Filtering Data Service Results

With the FilterXQuery class addFilter() method, filtering criteria are specified as Boolean condition statements (for example, ORDER_AMOUNT > 1000). Only items that meet the condition are included in the return set.

The addFilter() method also lets you create compound filters that provide significant flexibility, given the hierarchical structure of the data service return type. In other words, given a condition on a nested element, compound filters let you control the effects of the condition in relation to the parent element.

For example, consider a multi-level data hierarchy for CUSTOMERS/CUSTOMER/ORDER, in which CUSTOMERS is the top level document element, and CUSTOMER and ORDER are sequences within CUSTOMERS and CUSTOMER respectively. Finally, ORDER_AMOUNT is an element within ORDER.

An ORDER_AMOUNT condition (for example, CUSTOMER/ORDER/ORDER_AMOUNT > 1000) can affect what values are returned in several ways:

Instead of writing XQuery functions for each case, you just pass the filter object as a parameter when executing a data service function, either using the Data Service Control or Mediator API.

Objectives

Instructions

Open the DataServiceClient.java file.
Delete the code that removed the line item with line_id = 8 order item delete code.
Delete the invoke and println code from the //Insert Code section:

CustomerProfileDocument[] doc = (CustomerProfileDocument[]) ds.invoke("getCustomerProfile",params);

System.out.println("Connected to Liquid Data 8.2 : CustomerProfile Data Service ...");

Import the FilterXQuery class by adding the following code:

import com.bea.ld.filter.FilterXQuery;
import com.bea.dsp.RequestConfig;

Create a filter instance of the FilterXQuery, plus specify a condition to filter orders greater than $1,000, by adding the following code:

//Create a filter and condition

FilterXQuery filter = new FilterXQuery();

filter.addFilter(

"CustomerProfile/customer/orders/order", "CustomerProfile/customer/orders/order/total_order_amount",

">", "1000");

Apply the filter to the data service, by adding the following code:

// Apply the filter

  RequestConfig config = new RequestConfig();

  config.setFilter(filter);

  CustomerProfileDocument doc[] = (CustomerProfileDocument[]) ds.invoke("getCustomerProfile",params, config);

Change the //Show Customer Data code to the following:

// Show Customer Data

    System.out.println("======================= Customers =====================");

    Customer customer = doc[0].getCustomerProfile().getCustomerArray(0);

    System.out.println("Connected to ALDSP: CustomerProfile Data Service ...");

Figure 11-1 Filter Code

Filter Code

Click the DataServiceClient.java file's Start icon (or press Ctrl + F5).
Use the Mediator API to view the results in the Output window and/or a standalone Java environment. The return results should be similar to those displayed in Figure 11-2.

Figure 11-2 Filtered Data Results

Filtered Data Results

11.2 Sorting Data Service Results

With the FilterXQuery class sortfilter.addOrderBy() method, you can specify criteria for organizing the data service return results. For example, to sort the order amount results in ascending order, you would use a sort condition similar to the following:

Objectives

Instructions

Open the DataServiceClient.java file.
Create a sort instance of the FilterXQuery, by adding the following code before the //Apply Filter section:

// Create a sort

FilterXQuery sortfilter = new FilterXQuery();

Add a sort condition, using the addOrderBy() method, to sort orders based on total_order_amount (ascending) as shown:

sortfilter.addOrderBy(

"CustomerProfile/customer/orders/order",

"total_order_amount",

FilterXQuery.ASCENDING);

Apply the sort filter to the data service by adding the following code:

// Apply the sort

filter.setOrderByList(sortfilter.getOrderByList());

Figure 11-3 Sort Code

Sort Code

Click the Start icon (or press Ctrl + F5) for the DataServiceClient.java file.
Use the Mediator API to view the results in the Output window and/or a standalone Java environment. The data results should be similar to those displayed in Figure 11-4.

Figure 11-4 Filtered and Sorted Data Results

Filtered and Sorted Data Results

11.3 Truncating Data Service Results

The FilterXQuery class also provides the filter.setLimit() method, which lets you limit the number of return results. For example, to limit the return results to two line items, you would use a truncate condition similar to the following:

Objectives

Instructions

Open the DataServiceClient.java file.
Add a truncate condition, using the setLimit() method to limit the result set to a maximum of two order lines for each order, as shown:

// Truncate result set

  filter.setLimit("CustomerProfile/customer/orders/order/order_line","2");

Figure 11-5 Truncate Code

Truncate Code

Click the Start icon (or press Ctrl + F5) for the DataServiceClient.java file.
Use the Mediator API to view the results in the Output window and/or a standalone Java environment. The data results should be similar to those displayed in Figure 11-6.