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

java.lang.Object
  extended by 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  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.

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.





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.