Managing a large list

The Actuate Information Delivery API provides the ability to retrieve a large number of objects from a data source. To manage a large list efficiently, the API provides five parameters that provide state information, configure the number of objects to return at one time, and manage the search result in other ways:

FetchSize indicates the number of records to retrieve and return in the result set at one time. If you do not specify a FetchSize, BIRT iHub uses the default value of 500. If you set FetchSize to 0 or less, no records return.

FetchHandle returns in a search response when the result set exceeds the FetchSize. FetchHandle returns in the response to a Select or Get request, such as SelectFiles or GetFolderItems. Use FetchHandle to retrieve more results in the set. In the second and subsequent calls for data, you must specify the same search criteria that you used in the original call. All Get and Select requests support FetchHandle except SelectFileType.

FetchDirection supports navigating through a result set when the results exceed the FetchLimit. FetchDirection supports getting the next or previous set of results in a response when the result set exceeds the FetchSize. To page forward through the result list, set FetchDirection to True. To page in reverse, set FetchDirection to False. The default setting is True. You can set FetchDirection in all Get and Select requests except SelectFileType.

Differentiate fetch direction from sort order. Fetch direction specifies whether to get the next or previous set of results in a result set. Sort order specifies the order of the data returned by a query. Use the SortOrder attribute in SortColumn and the GroupSortOrder attribute in Grouping to specify the sort order of data returned by a query.

In Get and Select requests, CountLimit indicates how many objects to count. For example, if the total possible count is 1,000 records, you can limit the count result to the first 100 records. A CountLimit of -1 counts everything in the result set. The default CountLimit is equal to the FetchSize. The count is independent of how many items a response returns.

TotalCount is the response to a CountLimit. In Get and Select responses, TotalCount indicates the size of the counted result set. TotalCount does not return for NameList or IdList requests.

Table 4‑2 CountLimit and TotalCount settings
Setting	Result
CountLimit = 0	Does not count. Returns a TotalCount of zero.
CountLimit = -1	Counts all objects.
CountLimit > 0	Counts up to the specified limit. In this case, TotalCount returns as the lesser of the CountLimit or the total result set.

The following example shows how these mechanisms appear in the search request. In this example, the result counts up to 600 items, retrieving 100 at a time: