com.sap.tc.cmi.util

Class CMIObservableListEvent

java.lang.Object
  java.util.EventObject
      com.sap.tc.cmi.util.CMIObservableListEvent

All Implemented Interfaces:

Serializable

public class CMIObservableListEvent
extends EventObject

Event object that describes changes in an ICMIObservableList.

It always informs about the source of the event as well as the type of the reported change. For some types of events, it contains additional information (getElement(), getFromIndex(), getToIndex()).

Revised contract for listeners In NetWeaver 04, the eventing of the ICMIObservableList was restricted to a fixed set of event types:

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

In the meantime, additional event types have been defined and the contract for listeners has been clarified with respect to new or model defined event types. See ICMIObservableListChangeListener02 for details about this revised contract.

This type can be called by applications or frameworks using CMI and implementations of CMI can (but usually don't have to) subclass it.

See Also:

Serialized Form

Type Classification:

This class is part of the Common Model Interface and is intended to be subclassed by applications.

Field Summary

static int	CONTIGUOUS_ELEMENTS_ADDED Event type used when multiple elements have been added en block to an ICMIObservableList.
static int	CONTIGUOUS_ELEMENTS_REMOVED Event type used when multiple elements have been removed en block from an ICMIObservableList.
static int	ELEMENT_ADDED Event type when a single element has been added to an ICMIObservableList.
static int	ELEMENT_CHANGED Event type when a single element has been replaced in an ICMIObservableList.
static int	ELEMENT_REMOVED Event type used when a single element has been removed from an ICMIObservableList.
static int	ELEMENTS_REORDERED Event type used when the elements in the list have been reordered, but not manipulated (no adds, removes, replacements).
static int	FIRST_MODEL_DEFINED_EVENT_TYPE Smallest integer that model implementations may use to define their own event types.
static int	LIST_CLEARED Event type used when an ICMIObservableList has been cleared.
static int	MULTIPLE_ELEMENTS_REMOVED Event type used when multiple elements have been removed from an ICMIObservableList at not necessarily contiguous positions.

Fields inherited from class java.util.EventObject

source

Constructor Summary

CMIObservableListEvent(ICMIObservableList source)
Constructor for CMIObservableListEvent.

CMIObservableListEvent(ICMIObservableList source, int type, Object element, int fromIndex, int toIndex)
Creates an event object with the given type and parameters for the given source list.

Method Summary

int	getChangeType() Returns the type of this event.
Object	getElement() Returns the element that is directly affected by the reported change.
int	getFromIndex() Returns the first index in the source list that is directly affected by the reported change.
ICMIObservableList	getObservableList() Returns the observable list that is the source of this event.
int	getToIndex() Returns the last index in the source list that is directly affected by the reported change.

Methods inherited from class java.util.EventObject

getSource, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

LIST_CLEARED

public static final int LIST_CLEARED

Event type used when an ICMIObservableList has been cleared. The event object doesn't contain additional information.

This event must always be delivered through the ICMIObservableListChangeListener.complexChange(CMIObservableListEvent) method.

See Also:

Constant Field Values

ELEMENT_ADDED

public static final int ELEMENT_ADDED

Event type when a single element has been added to an ICMIObservableList. As additional information the event object contains the added element and the index where the element has been added. This event implies an index increment by 1 for any existing element after the insert position.

For convenience, getFromIndex() must be equal to getToIndex().

This is the only event that can be delivered through the ICMIObservableListChangeListener.elementAdded(CMIObservableListEvent) method.

See Also:

Constant Field Values

ELEMENT_CHANGED

public static final int ELEMENT_CHANGED

Event type when a single element has been replaced in an ICMIObservableList. As additional information the event object contains the replaced element (old) and the previous index of the replaced element. The new element can be retrieved from the list using the given index.

For convenience, getFromIndex() must be equal to getToIndex().

Note: The name of this event type is misleading. The element did not necessarily change itself (ICMIObservableList does not inform about such changes), but a single entry in the list has been replaced by a new entry. So the size of the list did not change and only a single entry was affected. To stay consistent with the method names in ICMIObservableListChangeListener, the name of this event type has not been changed.

This is the only event that can be delivered through the ICMIObservableListChangeListener.elementChanged(CMIObservableListEvent) method.

See Also:

Constant Field Values

ELEMENT_REMOVED

public static final int ELEMENT_REMOVED

Event type used when a single element has been removed from an ICMIObservableList. As additional information the event object contains the removed element and the index where the element has been removed. This event implies an index decrement by 1 for any existing element after the remove position.

For convenience, getFromIndex() must be equal to getToIndex().

This is the only event that can be delivered through the ICMIObservableListChangeListener.elementRemoved(CMIObservableListEvent) method.

See Also:

Constant Field Values

CONTIGUOUS_ELEMENTS_ADDED

public static final int CONTIGUOUS_ELEMENTS_ADDED

Event type used when multiple elements have been added en block to an ICMIObservableList. As additional information the event object contains the index of the first and the last inserted element. This event implies an index increment by getToIndex()-getFromIndex()+1 for any existing element after the first insert position.

This event must always be delivered through the ICMIObservableListChangeListener.complexChange(CMIObservableListEvent) method.

See Also:

Constant Field Values

CONTIGUOUS_ELEMENTS_REMOVED

public static final int CONTIGUOUS_ELEMENTS_REMOVED

Event type used when multiple elements have been removed en block from an ICMIObservableList. As additional information the event object contains the index of the first and the last removed element. Implies an index decrement by getToIndex()-getFromIndex()+1 for any existing element after the insert position. Note: There is currently no way to determine the set of removed objects from the event object.

This event must always be delivered through the ICMIObservableListChangeListener.complexChange(CMIObservableListEvent) method.

See Also:

Constant Field Values

MULTIPLE_ELEMENTS_REMOVED

public static final int MULTIPLE_ELEMENTS_REMOVED

Event type used when multiple elements have been removed from an ICMIObservableList at not necessarily contiguous positions. The event object does not contain any additional information. So the only added value of this event is the information that elements only have been removed (no replacements, no adds). Implies index changes for any existing element after the first remove position.

Note: There is currently no way to determine the set of removed/repositioned objects from the event object.

This event must always be delivered through the ICMIObservableListChangeListener.complexChange(CMIObservableListEvent) method.

See Also:

Constant Field Values

ELEMENTS_REORDERED

public static final int ELEMENTS_REORDERED

Event type used when the elements in the list have been reordered, but not manipulated (no adds, removes, replacements). The event object does not contain any additional information. Allows listeners to retain their associated data and to only reorder it.

Note: This event must only be delivered to listeners of type ICMIObservableListChangeListener02 and only through the ICMIObservableListChangeListener02.complexChange(CMIObservableListEvent) method. Listenes of type ICMIObservableListChangeListener should receive a LIST_CLEARED event followed by a CONTIGUOUS_ELEMENTS_ADDED event instead.

See Also:

Constant Field Values

FIRST_MODEL_DEFINED_EVENT_TYPE

public static final int FIRST_MODEL_DEFINED_EVENT_TYPE

Smallest integer that model implementations may use to define their own event types. If the event object contains any additional information depends on the model implementation and must be documented there.

Note: Events with a type >= FIRST_MODEL_DEFINED_EVENT_TYPE must only be send to listeners of type ICMIObservableListChangeListener02 and only through their ICMIObservableListChangeListener02.complexChange(CMIObservableListEvent) method. Listeners of type ICMIObservableListChangeListener should receive a LIST_CLEARED event followed by a CONTIGUOUS_ELEMENTS_ADDED event instead.

See Also:

Constant Field Values

Constructor Detail

CMIObservableListEvent

public CMIObservableListEvent(ICMIObservableList source)

Constructor for CMIObservableListEvent.

Parameters:

source -

CMIObservableListEvent

public CMIObservableListEvent(ICMIObservableList source,
                              int type,
                              Object element,
                              int fromIndex,
                              int toIndex)

Creates an event object with the given type and parameters for the given source list.

The source must not be null and the type must either be one of the event types defined in this class or it must be a model defined event type with type >= FIRST_MODEL_DEFINED_EVENT_TYPE. Whether or how the other parameters have to be set, depends on the event type and is documented with these types or, in the case of a model specific event type, in the documentation of the model type.

This constructor can be called by implementations that use CMIObservableListEvent as it is as well as by implementations that have to subclass it.

Method Detail

getObservableList

public final ICMIObservableList getObservableList()

Returns the observable list that is the source of this event.

Returns:

ICMIObservableList that is the source of this event.

getChangeType

public final int getChangeType()

Returns the type of this event. Will either be one of the event types defined in this class or it must be a model defined event type with type >= FIRST_MODEL_DEFINED_EVENT_TYPE.

Returns:

type of this event

getFromIndex

public final int getFromIndex()

Returns the first index in the source list that is directly affected by the reported change. For some event types, the returned value is undefined. See documentation of event types for details.

Returns:

index of first element affected by this event

getToIndex

public final int getToIndex()

Returns the last index in the source list that is directly affected by the reported change. For some event types, the returned value is undefined. See documentation of event types for details.

Returns:

index of last element affected by this event

getElement

public final Object getElement()

Returns the element that is directly affected by the reported change. For some event types, the returned value can be null. See documentation of event types for details.

Returns:

element affected by this event

Access Rights

This class can be accessed from:

SC	DC	Public Part	ACH
[sap.com] FRAMEWORK	[sap.com] tc/cm/ejb/api	api	BC-JAS-EJB
[sap.com] FRAMEWORK	[sap.com] tc/cmi	default	BC-WD-JAV-RUN