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

java.lang.Object
  extended by net.rim.device.api.collection.util.LongSortedReadableList
All Implemented Interfaces:
ChainableCollection, Collection, CollectionEventSource, CollectionListener, LoadableCollection, ReadableList, ReadableLongList

public class LongSortedReadableList
extends Object
implements ChainableCollection, LoadableCollection, ReadableList, ReadableLongList

Maintains a collection of elements with associated keys.

This class makes use of a KeyProviderAdaptor to extract the keys directly from the elements in the list.


Constructor Summary
LongSortedReadableList(CollectionEventSource sourceCollection, LongKeyProviderAdaptor adaptor)
          Constructs a new instance using another collection as a source for initial contents.
LongSortedReadableList(LongKeyProviderAdaptor adaptor)
          Constructs a new instance.
 
Method Summary
 void addCollectionListener(Object listener)
          Registers a listener to receive collection events.
 void elementAdded(Collection collection, Object element)
          Monitored collection has added an element.
 void elementRemoved(Collection collection, Object element)
          Monitored collection has removed an element.
 void elementUpdated(Collection collection, Object oldElement, Object newElement)
          Monitored collection has replaced an existing element with a new one.
 Object getAt(int offset)
          Retrieve element by index.
 int getAt(int offset, int length, Object[] data, int destIndex)
          Retrieves a range of elements starting at provided index.
 int getAt(int offset, int length, long[] keys, int destIndex)
          Retrieves range of element keys starting at provided index.
 int getIndex(Object element)
          Retrieve index by element.
 int getIndex(long key)
          Retrieve index by element key.
 long getKey(int offset)
          Retrieve element key by offset from the key cache.
 long getLongAt(int index)
          Retrieves element key by index.
 void loadFrom(Object collection)
          Flush this collection and re-initialize from specified collection.
protected  void mergeCollection(Object collection)
          Merges this collection's contents with another collection.
 void removeCollectionListener(Object listener)
          Removes a listener object from the list of those receiving events.
protected  void reset()
          Flushes this collection's contents.
 void reset(Collection collection)
          Monitored collection has changed drastically.
 int size()
          Retrieves the number of elements in this collection.
 
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.CollectionListener
elementAdded, elementRemoved, elementUpdated, reset
 



Constructor Detail

LongSortedReadableList

public LongSortedReadableList(LongKeyProviderAdaptor adaptor)
Constructs a new instance.

Parameters:
adaptor - The KeyProviderApaptor this collection will use to extract the keys from the contained elements; cannot be null.

LongSortedReadableList

public LongSortedReadableList(CollectionEventSource sourceCollection,
                              LongKeyProviderAdaptor adaptor)
Constructs a new instance using another collection as a source for initial contents.

This constructor loads the new instance with elements from the provided source collection, and then processes the elements to initialize the cache of keys using the provided adaptor.

Parameters:
sourceCollection - Source of this collection's initial elements. The source must implement either ReadableList or ReadableSet. This constructor automatically registers this collection as a listener on the source collection.
adaptor - Key provider adaptor this collection will use to extract the long integer keys from the contained elements; cannot be null.


Method Detail

mergeCollection

protected void mergeCollection(Object collection)
Merges this collection's contents with another collection.

This method gathers elements from the specified source, and merges them with this collection's current contents (that is, it joins the two collections together so that the result is sorted).

Parameters:
collection - Collection to merge with this one. The collection to merge must implement either ReadableList or ReadableSet.

reset

protected void reset()
Flushes this collection's contents.


loadFrom

public void loadFrom(Object collection)
Flush this collection and re-initialize from specified collection.

This method erases this collection's current contents, replacing them by copying the contents of another. Any collections monitoring this collection will get notified that this collection has reset its contents.

Specified by:
loadFrom in interface LoadableCollection
Parameters:
collection - Collection whose elements to use as new contents of this collection.

getLongAt

public long getLongAt(int index)
Retrieves element key by index.

Specified by:
getLongAt in interface ReadableLongList
Parameters:
index - Index of element key to retrieve.
Returns:
key for element at provided index.

getAt

public int getAt(int offset,
                 int length,
                 long[] keys,
                 int destIndex)
Retrieves range of element keys starting at provided index.

Specified by:
getAt in interface ReadableLongList
Parameters:
offset - Index of first element key to retrieve.
length - Number of element keys to retrieve.
keys - Array to contained returned element keys; this array must be large enough to hold the number of elements you expect to receive.
destIndex - Index within the destination array to contain the first element retrieved (the destination array must therefore be at least destIndex + length elements long.
Returns:
Number of element keys actually retrieved.

getIndex

public int getIndex(long key)
Retrieve index by element key.

Note: This operation is linear with respect to the number of elements in this collection.

Specified by:
getIndex in interface ReadableLongList
Parameters:
element - Element key to locate.
Returns:
Index of provided element key, or -1 if the element key isn't contained in this collection.

getKey

public long getKey(int offset)
Retrieve element key by offset from the key cache.

Parameters:
offset - Position of key to retrieve from within the key cache list.
Since:
BlackBerry API 3.6.0

reset

public void reset(Collection collection)
Monitored collection has changed drastically.

This method in turn invokes loadFrom(collection) to reload this collection's contents from the source's new contents.

Parameters:
collection - Changed collection.
Since:
BlackBerry API 4.0.2

elementAdded

public void elementAdded(Collection collection,
                         Object element)
Monitored collection has added an element.

This method extracts the key for the new element, and then uses the key to insert the element in the appropriate place in this list.

This method also notifies any listening collections of the add event.

Parameters:
collection - Changed collection.
element - Element added to the monitored collection.
Since:
BlackBerry API 4.0.2

elementUpdated

public void elementUpdated(Collection collection,
                           Object oldElement,
                           Object newElement)
Monitored collection has replaced an existing element with a new one.

This method determines if the elmeent update invalidates the sort order of this list. If it does, it updates the appropriate element in this list, and resorts this list; otherwise, it simply does an inplace update of the appropriate element.

This method also notifies any listening collections of the update event.

Parameters:
collection - Changed collection.
oldElement - Pre-existing element that was replaced.
newElement - New element that replaced the pre-existing one.
Since:
BlackBerry API 4.0.2

elementRemoved

public void elementRemoved(Collection collection,
                           Object element)
Monitored collection has removed an element.

If the element removed from the monitored collection also exists in this collection, this method removes it, and then notifies any listening collection of the remove event.

If the element doesn't exist in this collection, then this method does nothing (although before it can determine whether it needs to do nothing, it must synchronize with respect to this colleciton and invoke LongSortedReadableList.getIndex(long) which can be expensive in and of itself).

Parameters:
collection - Changed collection.
element - Element removed from the monitored collection.
Since:
BlackBerry API 4.0.2

addCollectionListener

public void addCollectionListener(Object listener)
Registers a listener to receive collection events.

Specified by:
addCollectionListener in interface CollectionEventSource
Parameters:
listener - Object to register as a listener (must implement CollectionListener or one of its derived interfaces.

removeCollectionListener

public void removeCollectionListener(Object listener)
Removes a listener object from the list of those receiving events.

Specified by:
removeCollectionListener in interface CollectionEventSource
Parameters:
listener - Listener to remove.

size

public int size()
Retrieves the number of elements in this collection.

Specified by:
size in interface ReadableList
Specified by:
size in interface ReadableLongList
Returns:
Number of elements in this collection.

getAt

public int getAt(int offset,
                 int length,
                 Object[] data,
                 int destIndex)
Retrieves a range of elements starting at provided index.

Specified by:
getAt in interface ReadableList
Parameters:
offset - Index of first element to retrieve.
length - Number of elements to retrieve.
data - Object array to contain returned element values; this array must be large enough to hold the number of elements you expect to receive.
destIndex - Index within the destination array to contain the first element retrieved (the destination array must therefore be at least destIndex + count elements long.
Returns:
Number of items actually retrieved, which may be less than the number requested.

getAt

public Object getAt(int offset)
Retrieve element by index.

Specified by:
getAt in interface ReadableList
Parameters:
offset - Index of the element to retrieve.
Returns:
Element value at provided index.

getIndex

public int getIndex(Object element)
Retrieve index by element.

Note: this operation may be linear with respect to the number of elements in the list.

Specified by:
getIndex in interface ReadableList
Parameters:
element - Element to locate.
Returns:
Index of provided element, or -1 if the element isn't contained in this collection.





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal