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

java.lang.Object
  |
  +--net.rim.device.api.collection.util.UnsortedReadableList
All Implemented Interfaces:
ChainableCollection, Collection, CollectionEventSource, CollectionListener, LoadableCollection, ReadableList
Direct Known Subclasses:
SortedReadableList

public class UnsortedReadableList
extends Object
implements ChainableCollection, LoadableCollection, ReadableList

Maintains a collection of elements in an unsorted order.


Constructor Summary
UnsortedReadableList()
          Constructs a new UnsortedReadableList instance.
UnsortedReadableList(CollectionEventSource sourceCollection)
          Constructs a new UnsortedReadableList using another collection as a source of initial elements.
 
Method Summary
 void addCollectionListener(Object listener)
          Registers a listener to receive collection events.
protected  void doAdd(Object element)
          Adds element without sending an event.
protected  boolean doRemove(Object element)
          Removes an element without sending an event.
protected  boolean doUpdate(Object oldElement, Object newElement)
          Updates an element without sending an event.
 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 index)
          Retrieves element by index.
 int getAt(int index, int count, Object[] elements, int destIndex)
          Retrieves range of elements starting at provided index.
protected  Object[] getElements()
          Retrieves all this collection's elements.
 int getIndex(Object element)
          Retrieves index by element.
protected  CollectionListenerManager getListenerManager()
          Retrieves this collection's listener manager.
protected  void insertAt(int index, Object element)
          Inserts an element by location.
 void loadFrom(Object collection)
          Reload this list using specified collection as source.
protected  void reload(Object collection)
          Reloads from the given collection.
 void removeCollectionListener(Object listener)
          Removes a listener object from the list of those receiving events.
 void reset(Collection collection)
          Monitored collection has changed drastically; reload from this source.
protected  void setElements(Object[] elements, int count)
          Set the elements in the collection.
 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

UnsortedReadableList

public UnsortedReadableList()
Constructs a new UnsortedReadableList instance.

UnsortedReadableList

public UnsortedReadableList(CollectionEventSource sourceCollection)
Constructs a new UnsortedReadableList using another collection as a source of initial elements.

This builds a collection using the provided Collection as an initial source of data (but only if the passed object is a Collection). In any case, this constructor registers the passed object as a listener for this collection's events.

Parameters:
sourceCollection - Collection to use as source of initial contents.
Method Detail

addCollectionListener

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

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

doAdd

protected void doAdd(Object element)
Adds element without sending an event.

Parameters:
element - Element to add.

doRemove

protected boolean doRemove(Object element)
Removes an element without sending an event.

Parameters:
element - Element to remove; if this element doesn't exist within this collection, thus method does nothing.
Returns:
True if element was found and removed (and thus you should send out a remove event); otherwise, false.

doUpdate

protected boolean doUpdate(Object oldElement,
                           Object newElement)
Updates an element without sending an event.

Parameters:
oldElement - Old element to replace; if this element doesn't exist within this colleciton, this method does nothing.
newElement - New element to replace the old element.
Returns:
True if this method found the old element and replaced it with the new one (and thus you should send out an update event); otherwise, false.

elementAdded

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

Adds element to this collection, and sends an element added event to listening collections.

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.

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 also sends an update event to each listener monitoring this collection for events.

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 index)
Retrieves element by index.

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

getAt

public int getAt(int index,
                 int count,
                 Object[] elements,
                 int destIndex)
Retrieves range of elements starting at provided index.

Parameters:
index - Index of first element to retrieve.
count - Number of elements to retrieve.
Object - array to contain returned elements; this array must have enough space to hold the nubmer of elements you expect to receive.
destIndex - Index within destination array to contain the first element retrieved (the destination array must therefore be at least destIndex + count elements long).
Returns:
Number of elements actually retrieved.

getElements

protected Object[] getElements()
Retrieves all this collection's elements.

Returns:
Elements from this collection.

getIndex

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

Note: This operation is 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.

getListenerManager

protected CollectionListenerManager getListenerManager()
Retrieves this collection's listener manager.

Returns:
Listener manager for this collection.

insertAt

protected void insertAt(int index,
                        Object element)
Inserts an element by location.

Parameters:
index - Index at which to place the new element.
element - Element to insert.

loadFrom

public void loadFrom(Object collection)
Reload this list using specified collection as source.

This method also sends a reset event to all the collection's monitoring this list for events. If the collection is of the expected type, then this method sends a reset event to this collection's listeners.

Parameters:
collection - New contents for this list; must be a ReadableSet, a ReadableList, an Object array, or an Enumeration.

reload

protected void reload(Object collection)
Reloads from the given collection.

Parameters:
collection - New contents for this list; should be a ReadableSet, a ReadableList, an Object array, or an Enumeration.

removeCollectionListener

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

Parameters:
listener - Collection listener to remove.

reset

public void reset(Collection collection)
Monitored collection has changed drastically; reload from this source.

Parameters:
collection - Changed collection.

setElements

protected void setElements(Object[] elements,
                           int count)
Set the elements in the collection.

Note that the array you provide may have more slots than actual element data; for this reason, you must also provide the number of elements passed in the array.

Parameters:
elements - Array containing new elements.
count - Number of actual elements in the provided array.
Throws:
IllegalArgumentException - Thrown if the specified number of elements is greater than the length of the array, or if the specified number of elements is less than zero.

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.