Retrieving Bulk Information - Iterators

Subject

This tutorial describes the concept of an 'Iterator' object in the Whitebeam System. Most templates use a database to store data representing the objects supported by the templates. Potentially large (even as large as everything stored in the database) amounts of data could be returned in response to certain template calls. Iterators overcome the issues associated with potentially large amounts of data by providing a simple mechanism for returning information about individual objects while being able to represent the entire set of objects.

Overview

Most operations performed on Whitebeam Templates result in a reasonably small amount of data being returned to the Presentation Page. There are some requests though that may generate an indeterminate amount of data. Often a lot of this data is then ignored by the Presentation Page in its generation of the users page. A good example is a template method that performs a search of a large set of data - for example a product catalogue. The results may be nothing or could return every item in the catalogue. In the latter case it is highly likely that all bar the first few items will be discarded by the Presentation Page.

It is very costly to generate a huge set of data only to then discard the bulk of those results. The result would be slow page generation.

The Whitebeam System provides an alternative means of accessing these datasets efficiently. Instead of generating the entire dataset and loading it into the Presentation Engine from the template the dataset instead remains in the template as a 'virtual' dataset. In database language the Presentation Page can access specific rows (individual object data) within a conceptual table (the complete set of returned data). As each row is requested the template generates the data for that row. The Presentation Page can modify the current position within the table at any time. In this way the template does not actually have to generate the entire dataset. It has the freedom, for example, to just generate the first 25 rows and not do any more work until the Presentation Page requests the 26^th row.

This process of stepping through the contents of a potentially large table is known as 'iterating' and the mechanism by which this is achieved in the Whitebeam system is via a JavaScript 'Iterator' object. If a template method specifies that it returns an 'iterator' (see rb.page.iterateHeader for an example) then the resulting object will allow the Presentation Page to step through the conceptual table.

The diagram above shows the basic model for an iterator object. The object always has exactly the same set of methods along with a set of data properties. Each property represents a value from one column of the conceptual row.

The properties that exist are determined by reference to a specific data structure definition. The example of rb.page.iterateHeader specified that the iterator properties are defined by rb.page.headerinfo. Think of the method as being analogous to another method that returns the entire table. In this case the method would return an array of 'rb.page.headerinfo'. In the case of an iterator we're returning an iterator over an array of 'rb.page.headerinfo'

In the illustration above the method that returned this iterator would have referenced a type having properties 'A' through to 'F'.

Reading the table rows

Once created iterators are very easy to use. Bear in mind that immediately after it has been created the properties do not yet exist. The most common first operation will be to call the iterators ' getNextRow' method. This causes the Presentation Engine to retrieve the first row from the conceptual table and to store the values for that row in the iterators properties. Occasionally you may not want to start with the first row in the table - for example where you want to show the second 25 results of a search. In this case the call to getNextRow' will be preceded by a call to setNextRow'.

Example

For an example of iterators in use see the documentation for rb.page.iterateHeader .