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
 

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.

Parameters:
listener - Listener to register.

doAdd

protected void doAdd(Object element)
Adds an element to this collection without sending an add event.

Parameters:
element - Element to add.

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.

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.

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.

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.

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.

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.

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.

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.

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.

getAt

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

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.

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.

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.

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

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.

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.

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.

removeCollectionListener

public void removeCollectionListener(Object listener)
Removes a listener from this collections list.

Parameters:
listener - Collection listener to remove.

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:
JDE 4.0.0

reset

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

This collection should rebuild itself accordingly.

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.