net.rim.device.api.collection
Interface NotificationSuspension

All Known Implementing Classes:

ReadableListCombiner

public interface NotificationSuspension

Defines the means by which a collection can suspend and resume sending of collection events sent to its listeners.

Since collections may propagate or chain events for its listeners (that is, this collection may listen for events from other collections, and forward them on to its own listeners), the typical class implementing this interface should propagate requests to suspend/resume notification on to the collections to which it listens.

Also, this interface's methods simply turn on and off the implementing object's notification state; it is not necessary to pair up suspend requests with resume requests.

Common use
If you wanted to perform many actions which would be too slow if every action were propagated up to the user inteface layer, you could suspend notification before each action, and then resume notification when these actions are finished. By the same turn, if you have an action which requires that all appropriate notifications have taken place, it's good practice to explicitly resume notification before the action (because if this collection supports suspension of notification, you can never be sure that a suspension request has taken place).

If a collection previously suspended notifications and is then asked to resume, it will most likely use CollectionListener.reset(Collection) to notify its listeners of the previously suspended changes. Code which calls NotificationSuspension.resumeNotification(java.lang.Object) should prepare for the possibility that it will subsequently receive a reset notification.

Examples
In a time consuming task such as restore:

 for( int i=0; i < someSize; ++i )
 {
     // Time consuming so we release our lock a lot.
     // (Need to allow UI to come in.)
     synchronized( FolderHierarchies.getLockObject() )
     {    
         collection.suspendNotification();
         doBitOfWorkOnCollection();
     }
 }
 synchronized( FolderHierarchies.getLockObject() )
 {
    collection.resumeNotification();
 }
 

In a UI task such as keyDown:

 synchronized( FolderHierarchies.getLockObject() )
 {
     collection.resumeNotification();
     index = getSelectionedIndex();   // This may have been altered by resumeNotification.
     doSomethingWithItem( collection.getAt(index);
 }
 

Method Summary
void	resumeNotification(Object context) Resumes sending of collection events to this collection's listeners.
void	suspendNotification(Object context) Suspends sending of collection events to this collection's listeners.

Method Detail

suspendNotification

void suspendNotification(Object context)

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

If this collection has already suspended notification, this method does nothing.

Parameters:

context - Context object to associate with this request.

resumeNotification

void resumeNotification(Object context)

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

If this collection has already suspended notification, this method does nothing.

Parameters:

context - Context object to associate with this request.