Using Iterative Queries

If you expect a declarative query to return a very large result set, you can use the implementation-specific iterative query feature. The DeclarativeQueryManagerImpl.executeQuery method can take an argument that specifies a set of parameters. This method has the following signature:

public BulkResponse executeQuery(Query query,
        java.util.Map queryParams,
        IterativeQueryParams iterativeParams)
    throws JAXRException

You can specify parameters that cause each query to request a different subset of results within the result set. Instead of making one query return the entire result set, you can make each individual query return a manageable set of results.

Suppose you have a query string that you expect to return up to 100 results. You can create a set of parameters that causes the query to return 10 results at a time. First, you create an instance of the class IterativeQueryParams, which is defined in the package org.freebxml.omar.common. The two fields of the class are startIndex, the starting index of the array, and maxResults, the maximum number of results to return. You specify the initial values for these fields in the constructor.

int maxResults = 10;
int startIndex = 0;
IterativeQueryParams iterativeQueryParams =
     new IterativeQueryParams(startIndex, maxResults);

Execute the queries within a for loop that terminates with the highest number of expected results and that advances by the maxResults value for the individual queries. Increment the startIndex field at each loop iteration.

for (int i = 0; i < 100; i += maxResults) {
    // Execute query with iterative query params
    Query query = dqm.createQuery(Query.QUERY_TYPE_SQL,
        queryStr);
     iterativeQueryParams.startIndex = i;
    BulkResponse br = dqm.executeQuery(query, null,
        iterativeQueryParams);
    Collection objects = br.getCollection();
    // retrieve individual objects ...
}

The Registry is not required to maintain transactional consistency or state between iterations of a query. New objects might be added to the complete result set between iterations, or existing objects might be removed from the result set. Therefore, you might notice that a result set element is skipped or duplicated between iterations.

Using Iterative Queries: Example

For an example of the use of an iterative query, see JAXRQueryIterative.java in the directory <INSTALL>/registry/samples/query-iterative/src. This program finds all registry objects whose names match a given string and then iterates through the first 100 of them.

To Run the JAXRQueryIterative Example

Steps

1. Go to the directory <INSTALL>/registry/samples/query-iterative.

2. Type the following command, specifying a string value:

   asant run -Dname=string