com.sap.tc.cmi.util

Interface ICMIPageableList

All Superinterfaces:

Collection, Iterable, List

public interface ICMIPageableList
extends List

Contract for a list implementation that not necessarily keeps all its elements in memory. Whenever data is accessed via the normal element accessor methods (iterator(), get(int), etc.), then a pageable list has to automatically retrieve the necessary data from its data source. This side effect always has to be transparent to clients that know and use the java.util.List interface only.

To optimize the behavior described above, clients of the ICMIPageableList can inform it about a range of data that they will access in the near future. This is for example helpful for a paged display of mass data (like in a table view) or for a batch process that wants to process mass data in small chunks of only a few records at a time.

Clients that want to synchronize with the set of currently prepared elements, can use the preparedElements() method for that purpose.

There is currently no contract on how to release elements. Implementations are free to release any elements on their own purpose, as long as this is transparent for users of the java.util.List interface. If this turns out to be a hard constraint for ICMIPageableList implementations (as it - for example - might require the usage of WeakReferences), then the contract must be redefined in a new interface (ICMIPageableList02).

Implementation hints:
Implementors of this interface often might subclass from one of the common collection implementations (e.g. java.util.AbstractList as well as CMIAbstractObservableList). If so, they should keep in mind that these base implementations don't know about prepared or unprepared elements and therefore simply iterate over all or at least many elements in their method implementations. As a side effect, all elements will be prepared.

While, in many cases, this is necessary to fulfill the contract of the java.util.List interface (e.g. iterator()), there are cases, where implementors of ICMIPageableList should consider to provide better implementations:

• contains(Object)
• indexOf(Object)
• lastIndexOf(Object)
• remove(Object) if a list implementation fully controls its elements, it might know, that an object can only be contained in the list, if it is a prepared element. So instead of checking all elements, it might only check the prepared ones.
• toString() instead of concatenating the string representations of all contained elements, implementations might use the string rep. of the prepared elements only and somehow indicate that there are other, not yet prepared elements (e.g. by using elipses: "[a,b,...,j,k,...x,y,...]").

Since:

NW Paris, MS2

Type Classification:

This interface is part of the Common Model Interface and is intended to be implemented by applications.

Method Summary

ICMIListIterator	preparedElements() Returns an iterator over all currently prepared elements.
void	prepareElements(int index, int count) Notifies the pageable list about a range of elements that will be accessed in the (near) future.

Methods inherited from interface java.util.List

add, add, addAll, addAll, clear, contains, containsAll, equals, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, retainAll, set, size, subList, toArray, toArray

Method Detail

prepareElements

void prepareElements(int index,
                     int count)

Notifies the pageable list about a range of elements that will be accessed in the (near) future.

A call to this method only serves as a hint for the list. Implementations are not forced to process the provided information exactly. They can cumulate several calls, extend the specified range in any suitable way (e.g. align it with some internal block size) or even ignore it. Especially, it is not guaranteed, that at any time after a call to this method, every element in the specified index range is contained in the set of prepared elements as returned by preparedElements().

The specified index range must match the range of the list and the count must not be negative:

   0 <= count
   0 <= index < size()
   0 <= index + count -1 < size() for count > 0
 

Parameters:

index - index of the first element that will be accessed

count - number of elements that will be accessed

Throws:

IndexOutOfBoundsException, - if the specfied range doesn't fit into the range of this list.

IllegalArgumentException - if count is < 0

preparedElements

ICMIListIterator preparedElements()

Returns an iterator over all currently prepared elements. Usually, the returned iterator will be immutable.

Returns:

ICMIListIterator of prepared elements.

Since:

NW Paris, MS3

Access Rights

This class can be accessed from:

SC	DC	Public Part	ACH
[sap.com] FRAMEWORK	[sap.com] tc/cm/ejb/api	api	BC-JAS-EJB
[sap.com] FRAMEWORK	[sap.com] tc/cmi	default	BC-WD-JAV-RUN