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

java.lang.Object
  net.rim.device.api.collection.util.BigUnsortedReadableList

All Implemented Interfaces:

ChainableCollection, Collection, CollectionEventSource, CollectionListener, LoadableCollection, ReadableList

Direct Known Subclasses:

BigSortedReadableList

public class BigUnsortedReadableList
extends Object
implements ChainableCollection, LoadableCollection, ReadableList

Maintains a large collection of unsorted elements.

The collection is assumed to be large, so it is actually stored using a BigVector rather than an array. This makes insert and delete operations quicker than with an array; however, retrieving an element by index may be somewhat slower.

Field Summary
protected BigVector	_elements Elements in this collection.
protected Object	_lastInsertedUpdated Last element inserted/updated.
protected int	_lastInsertedUpdatedIndex Index of the last inserted/updated element.
protected CollectionListenerManager	_listenerManager Listener manager for this collection.

Constructor Summary

BigUnsortedReadableList()
Constructs a new, empty BigUnsortedReadableList instance.

BigUnsortedReadableList(CollectionEventSource sourceCollection)
Constructs a new BigUnsortedReadableList instance.

Method Summary
void	addCollectionListener(Object listener) Registers a listener to receive collection events from this collection.
protected void	doAdd(Object element) Adds an element to this collection without sending an add event.
protected boolean	doRemove(Object element) Removes an element from this collection without firing an event.
protected boolean	doUpdate(Object oldElement, Object newElement) Updates an element in this collection without sending an update 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.
protected void	fireElementAdded(Collection collection, Object element) Sends element add event to the listeners.
protected void	fireElementRemoved(Collection collection, Object element) Sends element remove event to the listeners.
protected void	fireElementUpdated(Collection collection, Object oldElement, Object newElement) Sends element update event to the listeners.
protected void	fireReset(Collection collection) Sends reset event to the listeners.
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.
int	getIndex(Object element) Retrieves index by element.
protected void	insertAt(int index, Object element) Inserts element by index.
void	loadFrom(Object collection) Loads elements from another collection.
protected void	reload(Object collection) Reloads elements from another collection.
void	removeCollectionListener(Object listener) Removes a listener from this collections list.
void	replaceAt(Object element, int index) Replaces an element at the given index.
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

Field Detail

_elements

protected BigVector _elements

Elements in this collection.

_lastInsertedUpdated

protected Object _lastInsertedUpdated

Last element inserted/updated.

_lastInsertedUpdatedIndex

protected int _lastInsertedUpdatedIndex

Index of the last inserted/updated element.

_listenerManager

protected CollectionListenerManager _listenerManager

Listener manager for this collection.

Constructor Detail

BigUnsortedReadableList

public BigUnsortedReadableList()

Constructs a new, empty BigUnsortedReadableList instance.

BigUnsortedReadableList

public BigUnsortedReadableList(CollectionEventSource sourceCollection)

Constructs a new BigUnsortedReadableList instance.

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 initial source of elements for this collection.

Method Detail

addCollectionListener

public void addCollectionListener(Object listener)

Registers a listener to receive collection events from this collection.

Note that the listener object must implement CollectionListener or one of its derived interfaces.

Specified by:

addCollectionListener in interface CollectionEventSource

Parameters:

listener - Listener to register.

removeCollectionListener

public void removeCollectionListener(Object listener)

Removes a listener from this collections list.

Specified by:

removeCollectionListener in interface CollectionEventSource

Parameters:

listener - Collection listener to remove.

fireReset

protected void fireReset(Collection collection)

Sends reset event to the listeners.

Parameters:

collection - Collection initiating the reset event; could be this collection, or this collection could be passing on the event from another, monitored collection.

Since:

BlackBerry API 4.0.2

fireElementAdded

protected void fireElementAdded(Collection collection,
                                Object element)

Sends element add event to the listeners.

Parameters:

collection - Collection initiating the add event; could be this collection, or this collection could be passing on the event from another, monitored collection.

element - Element added.

Since:

BlackBerry API 4.0.2

fireElementUpdated

protected void fireElementUpdated(Collection collection,
                                  Object oldElement,
                                  Object newElement)

Sends element update event to the listeners.

Parameters:

collection - Collection initiating the update event; could be this collection, or this collection could be passing on the event from another, monitored collection.

oldElement - Pre-existing element.

newElement - New element replacing the old one.

Since:

BlackBerry API 4.0.2

fireElementRemoved

protected void fireElementRemoved(Collection collection,
                                  Object element)

Sends element remove event to the listeners.

Parameters:

collection - Collection initiating the remove event; could be this collection, or this collection could be passing on the event from another, monitored collection.

element - Element removed.

Since:

BlackBerry API 4.0.2

loadFrom

public void loadFrom(Object collection)

Loads elements from another collection.

Invoke this method to replace this collection's current list of elements with elements from another collection. If the collection is of the expected type, then this method sends a reset event to this collection's listeners.

When calling this method on an empty ReadableList, an ArrayIndexOutOfBoundsException is thrown. This exception is thrown from BigVector.copyInto(), as both the offset and length have the same value, 0.

Specified by:

loadFrom in interface LoadableCollection

Parameters:

collection - Collection to use as source: must either be a ReadableSet, a ReadableList, an Object[], or a Enumeration.

Throws:

IllegalArgumentException - Thrown if the specified collection is invalid.

reload

protected void reload(Object collection)

Reloads elements from another collection.

Invoke this method to replace this collection's current list of elements with elements from another collection.

Parameters:

collection - Collection to use as source: must either be a ReadableSet, a ReadableList, an Object[], or a Enumeration.

insertAt

protected void insertAt(int index,
                        Object element)

Inserts element by index.

Parameters:

index - Position in list for new element; if greater than the size of the list, your new element gets added to the end of the list.

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 element to retrieve.

Returns:

Element at provided index.

Throws:

ArrayIndexOutOfBounds - If index parameter is not valid.

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.

elements - Object array to contain returned elements; this array must have enough space to hold the number of elements you expect to receive.

desitIndex - 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.

Throws:

ArrayIndexOutOfBounds - If index parameter is not valid.

replaceAt

public void replaceAt(Object element,
                      int index)

Replaces an element at the given index.

Parameters:

index - Index of element to replace.

element - New element to replace the old element.

Throws:

ArrayIndexOutOfBounds - If index parameter is not valid.

Since:

BlackBerry API 4.0.0

getIndex

public int getIndex(Object element)

Retrieves index by element.

Note: if the element you specify is not the last inserted or updated element, 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.

This collection should rebuild itself accordingly.

Parameters:

collection - Changed collection.

Since:

BlackBerry API 4.0.2

doAdd

protected void doAdd(Object element)

Adds an element to this collection without sending an add 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 colleciotn.

element - Element added to the monitored collection.

Since:

BlackBerry API 4.0.2

doUpdate

protected boolean doUpdate(Object oldElement,
                           Object newElement)

Updates an element in this collection without sending an update event.

Parameters:

oldElement - Old element to replace.

newElement - New element to take old element's place.

Returns:

True if an update to this collection occured; false if the old element does not exist in this collection.

elementUpdated

public void elementUpdated(Collection collection,
                           Object oldElement,
                           Object newElement)

Monitored collection has replaced an existing element with a new one.

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 from this collection without firing an event.

Parameters:

element - Element to remove.

Returns:

True if element was found and removed; false if your element does not exist in this collection.

elementRemoved

public void elementRemoved(Collection collection,
                           Object element)

Monitored collection has removed an element.

Parameters:

collection - Changed colleciton.

element - Element removed from the monitored collection.

Since:

BlackBerry API 4.0.2