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

java.lang.Object
  |
  +--net.rim.device.api.collection.util.IntSortedReadableList
All Implemented Interfaces:
ChainableCollection, Collection, CollectionEventSource, CollectionListener, LoadableCollection, ReadableIntList, ReadableList

public class IntSortedReadableList
extends Object
implements ChainableCollection, LoadableCollection, ReadableList, ReadableIntList

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
IntSortedReadableList(CollectionEventSource sourceCollection, IntKeyProviderAdaptor adaptor)
          Constructs a new instance using another collection as a source for initial contents.
IntSortedReadableList(IntKeyProviderAdaptor 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, int[] keys, int destIndex)
          Retrieves range of element keys starting at provided index.
 int getAt(int offset, int length, Object[] data, int destIndex)
          Retrieves a range of elements starting at provided index.
 int getIndex(int key)
          Retrieve index by element key.
 int getIndex(Object element)
          Retrieve index by element.
 int getIntAt(int index)
          Retrieves element key by index.
 int getKey(int offset)
          Retrieve element key by offset from the key cache.
 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
 

Constructor Detail

IntSortedReadableList

public IntSortedReadableList(CollectionEventSource sourceCollection,
                             IntKeyProviderAdaptor 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.

IntSortedReadableList

public IntSortedReadableList(IntKeyProviderAdaptor adaptor)
Constructs a new instance.

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

addCollectionListener

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

Parameters:
listener - Object to register as a listener (must implement CollectionListener or one of its derived interfaces.

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.

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 getIndex(int) which can be expensive in and of itself).

Parameters:
collection - Changed collection.
element - Element removed from the monitored collection.

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.

getAt

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

Parameters:
offset - Index of the element to retrieve.
Returns:
Element value at provided index.

getAt

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

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.
Since:
JDE 3.6.0

getAt

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

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.

getIndex

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

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

Parameters:
element - Element key to locate.
Returns:
Index of provided element key, or -1 if the element key isn't contained in this collection.
Since:
JDE 3.6.0

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.

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

getIntAt

public int getIntAt(int index)
Retrieves element key by index.

Parameters:
index - Index of element key to retrieve.
Returns:
key for element at provided index.
Since:
JDE 3.6.0

getKey

public int 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.

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.

Parameters:
collection - Collection whose elements to use as new contents of this collection.

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.
Since:
JDE 3.6.0

removeCollectionListener

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

Parameters:
listener - Listener to remove.

reset

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

Since:
JDE 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.

size

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

Returns:
Number of elements in this collection.



Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.