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

Constructor Detail

ReadableListCombiner

public ReadableListCombiner()
Constructs new ReadableListCombiner instance.

Method Detail

addCollectionListener

public void addCollectionListener(Object listener)
Registers a listener to receive collection events.

Parameters:
Object - to register as a listener for this collection's events (must implement CollectionListener or one of its derived interfaces.

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.

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.

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.

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

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.

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.

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.

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.

getAt

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

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

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

getSources

protected Vector getSources()
Retrieves the current list of collections being combined.

Returns:
Current list of collections being combined.

removeCollectionListener

public void removeCollectionListener(Object listener)
Removes a listener object from the list of those receiving events.

Parameters:
listener - Listener to remove.

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.

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

reset

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

This collection should rebuild itself accordingly.

Parameters:
collection - Changed collection.

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.

Parameters:
context - Context object to associate with this request.

size

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

Returns:
Number of elements in this collection.

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.

Parameters:
context - Context object to associate with this request.



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.