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

public 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

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



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.