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

java.lang.Object
  extended by 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
 
Methods inherited from interface net.rim.device.api.collection.CollectionListener
elementAdded, elementRemoved, elementUpdated, reset
 



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

getElements

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

Returns:
Elements from this 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.

getListenerManager

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

Returns:
Listener manager for this collection.

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 which 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 - Collection listener to remove.

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.

Specified by:
loadFrom in interface LoadableCollection
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.

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.

size

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

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

getAt

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

Specified by:
getAt in interface ReadableList
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.

Specified by:
getAt in interface ReadableList
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.

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.

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.

reset

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

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

doAdd

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

Parameters:
element - Element to add.

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.
Since:
BlackBerry API 4.0.2

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.

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.
Since:
BlackBerry API 4.0.2

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.

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.
Since:
BlackBerry API 4.0.2





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.