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

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

All Implemented Interfaces:

ChainableCollection, Collection, CollectionCombiner, CollectionEventSource, CollectionListener, IntRangedActionTarget, LongRangedActionTarget, NotificationSuspension, ReadableList

public class ReadableListCombiner
extends Object
implements ChainableCollection, CollectionCombiner, ReadableList, LongRangedActionTarget, IntRangedActionTarget, NotificationSuspension

Combines any number of ReadableList implementations and present them as a single ReadableList.

Field Summary

Fields inherited from interface net.rim.device.api.collection.LongRangedActionTarget

FROM_THE_START, TO_THE_END

Fields inherited from interface net.rim.device.api.collection.IntRangedActionTarget

FROM_THE_START, TO_THE_END

Constructor Summary

ReadableListCombiner()
Constructs new ReadableListCombiner instance.

Method Summary
void	addCollectionListener(Object listener) Registers a listener to receive collection events.
void	addSource(Object source) Adds a new collection as a source of elements for this collection.
void	apply(int lowValue, int highValue, long action, Object context) Applies an action to a range of elements in each one of this collection's sources, using integer keys.
void	apply(long lowValue, long highValue, long action, Object context) Applies an action to a range of elements in each one of this collection's sources, using long integer keys.
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 elements 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 CollectionListenerManager	getListeners() Retrieves the listeners for this collection.
protected Vector	getSources() Retrieves the current list of collections being combined.
void	removeCollectionListener(Object listener) Removes a listener object from the list of those receiving events.
void	removeSource(Object source) Removes a collection source from this collection.
void	reset(Collection collection) Monitored collection has changed drastically.
void	resumeNotification(Object context) Resumes sending of collection events to this collection's listeners.
int	size() Retrieves the number of elements in this collection.
void	suspendNotification(Object context) Suspends sending of collection events to this collection's listeners.

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

ReadableListCombiner

public ReadableListCombiner()

Constructs new ReadableListCombiner instance.

Method Detail

getSources

protected Vector getSources()

Retrieves the current list of collections being combined.

Returns:

Current list of collections being combined.

getListeners

protected CollectionListenerManager getListeners()

Retrieves the listeners for this collection.

Returns:

The listener manager.

Since:

BlackBerry API 6.0.0

addCollectionListener

public void addCollectionListener(Object listener)

Registers a listener to receive collection events.

Specified by:

addCollectionListener in interface CollectionEventSource

Parameters:

Object - to register as a listener for this collection's events (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 - Listener to remove.

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

elementAdded

public void elementAdded(Collection collection,
                         Object element)

Monitored collection has added an element.

Parameters:

collection - Changed collection.

element - Element added to the monitored collection.

Since:

BlackBerry API 4.0.2

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

elementRemoved

public void elementRemoved(Collection collection,
                           Object element)

Monitored collection has removed an element.

Parameters:

colleciton - Changed collection.

element - Element removed from the monitored collection.

Since:

BlackBerry API 4.0.2

addSource

public void addSource(Object source)

Adds a new collection as a source of elements for this collection.

Invoke this method to retrieve all the elements from a specified, readable source, adding them to this collection.

Note: You should synchronize with the source collection when you add elements using this method, to prevent the loss of other object's changes to the source.

Specified by:

addSource in interface CollectionCombiner

Parameters:

source - Readable source collection from which to add elements. If this source implements CollectionEventSource, then this method registers this collection as a listener to collection events from the source.

removeSource

public void removeSource(Object source)

Removes a collection source from this collection.

Invoke this metohd to remove a colleciton as a source; this operation removes every element from this collection that also exists in the source collection.

Note: You should synchronize with the source collection when you add elements using this method, to prevent the loss of other object's changes to the source.

Specified by:

removeSource in interface CollectionCombiner

Parameters:

source - Source collection to remove; must be one of the readable types, because this method must be able to read the source's elements to know which to remove from this collection. If this source implements CollectionEventSource, then this method unregisters this collection as a listener to its collection events.l

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

elements - Object array to contain returned elements; this array must have enough space to hold the number 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.

apply

public void apply(long lowValue,
                  long highValue,
                  long action,
                  Object context)

Applies an action to a range of elements in each one of this collection's sources, using long integer keys.

This method sends each source collection an action, by invoking LongRangedActionTarget.apply(long, long, long, java.lang.Object) on each source. If a source collection does not implement LongRangedActionTarget, then this method does nothing to that source and moves on to the next.

Specified by:

apply in interface LongRangedActionTarget

Parameters:

lowValue - Key for the first element to affect.

highValue - Key for the last element to affect.

action - Action to perform.

context - Contextual data for use during the action.

apply

public void apply(int lowValue,
                  int highValue,
                  long action,
                  Object context)

Applies an action to a range of elements in each one of this collection's sources, using integer keys.

This method sends each source collection an action, by invoking IntRangedActionTarget.apply(int, int, long, java.lang.Object) on each source. If a source collection does not implement IntRangedActionTarget, then this method does nothing to that source and moves on to the next.

Specified by:

apply in interface IntRangedActionTarget

Parameters:

lowValue - Key for the first element to affect.

highValue - Key for the last element to affect.

action - Action to perform.

context - Contextual data for use during the action.

suspendNotification

public void suspendNotification(Object context)

Suspends sending of collection events to this collection's listeners.

On each of this collection's sources in turn, this method attempts to invoke NotificationSuspension.suspendNotification(java.lang.Object), passing in the context object passed to this method. If a source does not implement NotificationSuspension, then this method does nothing to that source and moves on to the next.

Specified by:

suspendNotification in interface NotificationSuspension

Parameters:

context - Context object to associate with this request.

resumeNotification

public void resumeNotification(Object context)

Resumes sending of collection events to this collection's listeners.

On each of this collection's sources in turn, this method attempts to invoke NotificationSuspension.resumeNotification(java.lang.Object), passing in the context object passed to this method. If a source does not implement NotificationSuspension, then this method does nothing to that source and moves on to the next.

Specified by:

resumeNotification in interface NotificationSuspension

Parameters:

context - Context object to associate with this request.