com.sap.tc.cmi.util

Interface ICMIObservableListChangeListener02

All Superinterfaces:

ICMIObservableListChangeListener

public interface ICMIObservableListChangeListener02
extends ICMIObservableListChangeListener

Duplicate of ICMIObservableListChangeListener with a revised contract.

Modified Contract
Listeners of type ICMIObservableListChangeListener are designed to receive events of one of the following types:

• LIST_CLEARED
• ELEMENT_ADDED
• ELEMENT_CHANGED
• ELEMENT_REMOVED
• CONTIGUOUS_ELEMENTS_ADDED
• CONTIGUOUS_ELEMENTS_REMOVED
• MULTIPLE_ELEMENTS_REMOVED

Unfortunately, this design leaves no room for enhancements. Under the new contract represented by this interface, listeners must be prepared to receive events with any of the types defined in CMIObservableListEvent (including but not restricted to the types listed above), but they must also be prepared to receive events of previously unknown types. These either might be extensions of CMIObservableListEvent or they might be model specific events.

The recommended reaction on previously unknown event types is to handle them the same way as a LIST_CLEARED event (remove old content) followed by a CONTIGUOUS_ELEMENTS_ADDED event (add new content). Typically, listeners might simply 'forget' their old knowledge about the observed list and take a new, fresh look at its current content.

The recommended implementation is to implement the described behavior in the default branch of a switch statement and to handle only those event types differently for which the listener can optimize its behavior.

To illustrate the idea, the following code sample shows a listener that keeps a copy of the list in sync with the observed list:

 // this represents the knowledge about the observed list:
 private List myCopyOfList;
 
 public void complexChange(CMIObservableListEvent event) {
   switch(event.getType()) {
     // handle specific event types with a dedicated branch
     case CMIObservableListEvent.LIST_CLEARED:
       // implement some optimized reaction
       myCopyOfList.clear();
       break;
       ...
     // and implement the default reaction in the 'default' branch
     default:
       // forget previous knowledge about list
       myCopyOfList.clear(); 
       // take a look at the current content of the list
       for(Iterator it=event.getObservableList().iterator(); it.hasNext(); ) {
         Object newElement = it.next();
         // do whatever is necessary for an observed element in the list
         myCopyOfList.add(newElement);
       }
       break;
     }
   }
 }
 

Compatibility with old ICMIObservableList implementations:
Implementations of ICMIObservableList that are not aware of the new contract will send out only events of the old types. As new listeners must be able to deal with these old types, they are fully compatible with such old list implementations.

Compatibility with old listener implementations:
New implementations of ICMIObservableList must deliver any of the new event types only to listeners of type ICMIObservableListChangeListener02. Listeners of type ICMIObservableListChangeListener should receive a LIST_CLEARED event followed by a CONTIGUOUS_ELEMENTS_ADDED event instead. This might lead to problems for old listeners, that don't ignore the existing list content when receiving a LIST_CLEARED event. But for most listeners, this is an acceptable event scheme.

Since:

NW Paris, MS3

Type Classification:

This interface is part of the Common Model Interface and is intended to be implemented by applications.

Method Summary

void	complexChange(CMIObservableListEvent event) General callback when an observed list has changed and if none of the more specific callbacks elementAdded, elementReplaced or elementRemoved matches.

Methods inherited from interface com.sap.tc.cmi.util.ICMIObservableListChangeListener

elementAdded, elementChanged, elementRemoved

Method Detail

complexChange

void complexChange(CMIObservableListEvent event)

General callback when an observed list has changed and if none of the more specific callbacks elementAdded, elementReplaced or elementRemoved matches.

The event object must at least contain the event type. The type must either be one of the event types defined by CMIObservableListEvent or it must be a model defined event type. Depending on the type, further data might be provided by the event object. See the documentation of CMIObservableListEvent and its event types for details.

Specified by:

complexChange in interface ICMIObservableListChangeListener

Parameters:

event - an event object that describes the added element

Access Rights

This class can be accessed from:

SC	DC
[sap.com] FRAMEWORK	[sap.com] tc/cmi
[sap.com] FRAMEWORK	[sap.com] tc/cm/ejb/api