Web applications frequently allow users to browse large virtual lists, such as query result sets, which can not practically be transmitted to the client. Access to the list is usually read-only and bi-directional, and the list is often discarded after the first few elements are examined. Using entity beans to represent elements of such lists provides little benefit and drains system resources. In particular, finder methods do not provide caching, scrolling, and random access to result sets, and have limited selection capabilities.

The Value List Handler design pattern provides a more efficient way to iterate a large, read-only list across tiers. A value list handler provides a client with an iterator for a virtual list that resides in another application tier. The iterator typically accesses a local ordered collection of Transfer Objects, representing a subrange of the large list. A Data Access Object usually manages access to the list data, and may provide caching.

See the Core J2EETM Patterns

The sample application catalog is an ordered collection of categories. Each category contains an ordered collection of products, and each product contains an ordered list of items. The catalog can also be searched for items that meet specific criteria.

Because it would be impractical to download the entire catalog each time the user selected a category, product, or item, or performed a search, the sample application manages catalog searching and browsing with the Value List Handler design pattern. The client requests information a page at a time by indicating where in the collection to begin and how many items to return. The client uses the value list handler as an iterator over the resulting collection and displays the result list in the user interface.

Figure 1 below shows a structure diagram of the sample application value list handler CatalogHelper.

Figure 1. Sample application CatalogHelper structure diagram

The CatalogHelper acts and as a value list handler for the client. The Client shown in Figure 1 is a JavaServer Pages^TM (JSP^TM) page, accessed through a Web browser, that accesses an instance of CatalogClientHelper using a useBean tag, as shown in the following excerpt from category.jsp:

        
<jsp:useBean
  id="catalog"
  class="com.sun.j2ee.blueprints.catalog.client.CatalogHelper"
  scope="session"
/>
      

A CatalogHelper instance, maintained in an HTTP session attribute, keeps track of:

1. the current query being executed (if the page represents a search)
2. the start position the list of elements being requested
3. the number of list items to retrieve at a time
4. the locale to be used for displaying the items

The CatalogHelper delegates responsibility for data access to an object that implements interface CatalogDAO (see the Data Access Object design pattern for details). The CatalogDAO retrieves a range of categories, products, items, or query results from the catalog, and returns them as a Page object. A Page is a transfer object that is a collection of other transfer objects. It represents the list of requested elements from the catalog (categories, products, or items). The CatalogHelper returns a Page of catalog entries (built by the CatalogDAO) to the client for display.

Figure 2 is a collaboration diagram of how the CatalogHelper uses a CatalogDAO to access a subrange of query results. Following the figure is a description of the method call sequence.

Figure 2. Collaboration diagram for value list handler CatalogHelper

• 1. A tag in the JSP page requests categories from the CatalogHelper. The tag is from the JavaServer Pages^TM Standard Tag Library (JSTL)
• 2. The CatalogHelper, which is keeping track of the current list position, size, and locale, requests a list of categories from CatalogDAO.getCategories.
• 3. The CatalogDAO, which in this scenario is implemented by class GenericCatalogDAO, executes the query shown, producing a ResultSet.
• 4. The GenericCatalogDAO then constructs a new Page object that contains the requested subrange of the larger list in the ResultSet. The Page is returned to the CatalogHelper, where it is used for display by the JSP page.

This implementation illustrates several interesting points about the Value List Handler pattern:

• Using a Data Access Object maximizes flexibility. The Data Access Object pattern used by the Value List Handler is an abstract API that encapsulates and hides the data access mechanism. At runtime, the sample application uses a factory object to select and load the class that implements interface CatalogDAO. This allows the data access mechanism to change--and new mechanisms to be added -- with no changes to client code. See the Data Access Object pattern description for further details.
• The CatalogHelper may or may not use the Fast Lane Reader design pattern. The CatalogHelper class has a property, useFastLane, that indicates whether to access the catalog directly in the EIS tier, instead of accessing it through the Enterprise JavaBeans^TM (EJB^TM) tier. When useFastLane is true, the CatalogHelper access the catalog using an object that implements interface CatalogDAO. When useFastLane is false, it accesses the catalog using a CatalogLocal enterprise bean. See the Fast Lane Reader design pattern for details.
• A value list handler may provide an internal or external iterator. The CatalogHelper provides an external iterator interface because it keeps track of the catalog page size and position. The iterator could also have been internal, providing only nextPage and prevPage methods while tracking position and size internally. (See Design Patterns for a description of internal and external iterators [ GHJV95 ]). The choice of an internal or external iterator interface is a design decision that depends on application requirements.
• Caching can improve performance. Application performance can often be improved by caching value lists. The sample application could have cached catalog lists, but this data is not cached in the current implementation. The CatalogHelper could improve performance by maintaining a cache of previously-requested lists. However, the Java Pet Store does cache page views using a custom tag CacheTag.
• The Value List Handler pattern is appropriate for both remote and local architectures. While the Value List Handler pattern was originally created to maximize performance in remote architectures, it is appropriate for local architectures as well. Modeling pages of information as sublists of a larger virtual list is a natural design concept, and it leads to a clean implementation. Where there are many repeated lookups of the same information, value lists are natural candidates for cache objects. Finally, the Value List Handler pattern provides more flexible query functionality than does using an EJB finder method. All of these benefits apply to both local and remote architectures.