net.rim.device.api.collection
Interface CollectionCombiner

All Superinterfaces:

Collection

All Known Implementing Classes:

ReadableListCombiner

public interface CollectionCombiner
extends Collection

Allows a collection to collect and combine elements from a number of source collections.

Usage notes
To receive events from a source collection, this collection must also register as a listener for events with the source using CollectionEventSource.addCollectionListener(java.lang.Object) (presuming that the source collection implements the event source interface). You should synchronize with the source collection when you register as a listener, to prevent the loss of any events it might have posted while registering you.

Note that, if this collection does not register itself as a listener with its sources, it will have no way of tracking the changes that happen to its sources after the invocation of CollectionCombiner.addSource(java.lang.Object).

Method Summary
void	addSource(Object source) Adds a new collection as a source of elements for this colleciton.
void	removeSource(Object source) Removes a collection source from this collection.

Method Detail

addSource

void addSource(Object source)

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

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 - Source collection from which to add elements; must be one of the readable-type collections so that this method can retrieve its elements.

removeSource

void removeSource(Object source)

Removes a collection source from this collection.

Invoke this method to remove a collection as a source: this operation removes every element from this collection that also exists in the source collection.

Note: If this collection registered itself as a listener for the source's collection events, then you should also unregister this collection as a listener. You should synchronize that action with the invocation of this method to ensure that you don't lose any changes made 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.