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

java.lang.Object
  extended by net.rim.device.api.collection.util.UnsortedReadableList
      extended by 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 instance, and initialize its contents 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; may 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 instance, and initialize its contents from another list.

This constructor also automatically registers this collection as a listener with the source collection you specify.

Parameters:
sourceCollection - Collection use as source of elements for this list.
comparator - Comparator this list will use to sort its elements; may not be 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.





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.