com.arsdigita.bebop.list
Interface ListModel

All Known Subinterfaces:
SearchAndListModel
All Known Implementing Classes:
ACSObjectCollectionListModel, DataQueryListModelBuilder.DataQueryListModel, IteratorListModel, PageErrorDisplay.StringIteratorModel, SimpleQuestionnaireListModel

public interface ListModel

The abstraction around a list of values used by the List component. Data sources that need to be displayed with a list component need to implement this interface. The ListModel provides a read-only view of the underlying data. The items in the list model can be accessed by calling next() repeatedly and accessing the item with calls to getKey() and getElement(). Initially, the list model is positioned before the first element and calls to getKey() and getElement() should produce a runtime exception until next() is called for the first time.

A ListModel is usually generated for each request that a list component serves. The List component will use its ListModelBuilder to generate a new ListModel whenever it serves a request.

The items a list model iterates over are identified by two separate objects: a key that has to be a unique string representation of the actual list item, and an element, which represents the item itself and is passed directly to the ListCellRenderer. For example, a list model that represents a list of objects that are stored in the database, the key will usually be a suitable representation of the primary key of the object in the database, while the element can be as simple as a string with the "pretty name" of the object. While the element is usually only passed to a ListCellRenderer, the key will often be communicated to other components that need to know which item in the list is currently selected and can be retrieved with a call to List.getSelectedKey(com.arsdigita.bebop.PageState). It is therefore important that all the components that need to work with the key generated by a list model agree on how it represents the underlying (database) object.

Warning: The signature of getKey will be changed to Obejct getKey() after ACS 4.6

Version:
$Id: //core-platform/dev/src/com/arsdigita/bebop/list/ListModel.java#11 $
Author:
David Lutterkort
See Also:
List, ListCellRenderer

Field Summary
static String versionId
           
 
Method Summary
 Object getElement()
          Get the element for the current list item.
 String getKey()
          Get the key that uniquely identifies the current list item.
 boolean next()
          Move to the next list item.
 

Field Detail

versionId

public static final String versionId
See Also:
Constant Field Values
Method Detail

next

public boolean next()
Move to the next list item. If there is no next list item, return false. The item's key and element can be accessed with calls to getKey() and getElement(). Initially, the list model is positioned before the first item, so that next() has to be called once before it is possible to access the item.

Returns:
true if the model is positioned on a valid item after the call returns.

getElement

public Object getElement()
Get the element for the current list item. The concrete type of the object returned is specific to each implementation of ListModel and should be documented there.

This method can only be called successfully if the previous cal to next() returned true.

Returns:
the element for the current list item
See Also:
next()

getKey

public String getKey()
Get the key that uniquely identifies the current list item. The key should be a string that uniquely identifies the list item, at least amongst all items in the list model. If the key needs to be communicated to other components, for example to display details about the list item, all components need to agree how the key identifies the underlying object. For objects stored in a database, this will usually be a suitable string representation for the primary key of the object.

This method can only be called successfully if the previous cal to next() returned true.

Returns:
identifies the object underlying the list item uniquely
See Also:
next()


Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 20 2004:2337 UTC