net.rim.device.api.collection.util
Class SortedReadableList

java.lang.Object
  net.rim.device.api.collection.util.UnsortedReadableList
      net.rim.device.api.collection.util.SortedReadableList

All Implemented Interfaces:

ChainableCollection, Collection, CollectionEventSource, CollectionListener, LoadableCollection, ReadableList, SortableCollection

public class SortedReadableList
extends UnsortedReadableList
implements SortableCollection

Maintains a collection of elements in a sorted order.

This collection uses a comparator object (specified at creation time) to sort the items in the list. Every item you add to the list must be recognized as valid by this comparator.

Constructor Summary

SortedReadableList(Comparator comparator)
Constructs a new SortedReadableList instance.

SortedReadableList(CollectionEventSource sourceCollection, Comparator comparator)
Constructs a new SortedReadableList from another list.

Method Summary
protected void	doAdd(Object element) Adds an element to this list without firing an event.
protected boolean	doUpdate(Object oldElement, Object newElement) Update an element in this list without firing an event.
Comparator	getComparator() Retreives this collection's comparator.
protected void	reload(Object collection) Reload from the given collection and resort.
void	setComparator(Comparator comparator) Sets this collection's comparator, and resorts this collection.
void	sort() The list is about to be sorted.

Methods inherited from class net.rim.device.api.collection.util.UnsortedReadableList

addCollectionListener, doRemove, elementAdded, elementRemoved, elementUpdated, getAt, getAt, getElements, getIndex, getListenerManager, insertAt, loadFrom, removeCollectionListener, reset, setElements, size

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.rim.device.api.collection.SortableCollection

setComparator

Methods inherited from interface net.rim.device.api.collection.CollectionListener

elementAdded, elementRemoved, elementUpdated, reset

Constructor Detail

SortedReadableList

public SortedReadableList(Comparator comparator)

Constructs a new SortedReadableList instance.

Parameters:

comparator - Comparator this list will use to sort its elements; must not be null. Any item added to this list must be recognized as valid by this comaprator.

Since:

BlackBerry API 4.0.2

SortedReadableList

public SortedReadableList(CollectionEventSource sourceCollection,
                          Comparator comparator)

Constructs a new SortedReadableList from another list. Also registers this collection as a listener with the source collection you specify.

Parameters:

sourceCollection - The CollectionEventSource used to populate this list.

comparator - Comparator that this list will use to sort its elements; must be non-null. Any item added to this list must be recognized as valid by this comparator.

Since:

BlackBerry API 4.0.2

Method Detail

getComparator

public Comparator getComparator()

Retreives this collection's comparator.

Specified by:

getComparator in interface SortableCollection

Returns:

Comparator this collection uses to sort its elements.

setComparator

public void setComparator(Comparator comparator)

Sets this collection's comparator, and resorts this collection.

This method also sends a reset event to any collection monitoring this collection's events.

Parameters:

comparator - New comparator to use for sorting this collection.

Since:

BlackBerry API 4.0.2

sort

public void sort()

The list is about to be sorted.

Subclasses can override this method to know when the complete list is getting sorted.

reload

protected void reload(Object collection)

Reload from the given collection and resort.

Overrides:

reload in class UnsortedReadableList

Parameters:

collection - The source collection from which to reload.

doAdd

protected void doAdd(Object element)

Adds an element to this list without firing an event.

This method adds the new element in the appropriate (sorted) place in the list.

Overrides:

doAdd in class UnsortedReadableList

Parameters:

element - Element to add: the list's comparator must recognize the new element as valid.

doUpdate

protected boolean doUpdate(Object oldElement,
                           Object newElement)

Update an element in this list without firing an event.

This method replaces an existing element with a new element. If the old element does not exist in this collection, this method does nothing.

If the old element does exist, this method replaces it with the new element, and manages the list so that it's sorted after the replacement.

Overrides:

doUpdate in class UnsortedReadableList

Parameters:

oldElement - Element to replace.

newElement - New element to replace the old one: the list's comaprator must recognize the new element as valid.

Returns:

True if the old element was found and replaced (and you should send out an update event to this collection's listeners); otherwise, false.