package org.apache.commons.events.observable ; import java.beans.PropertyChangeEvent ; import java.util.Collection; /** *
* This event is fired to all registered listeners whenever an observed
* collection is altered. The inherited oldValue
and
* newValue
properties are almost always null, as populating
* them normally requires that two nearly identical copies of the collection
* be maintained. The sole exception to this rule are events which
* replace a value in the collection with a different value (e.g., setting
* a particular element of a List
.)
*
Instead, this event maintains * information about how the collection was changed. This information * includes: *
* ** This event is always fired after the proposed action has taken place. * As such, it serves as a notification of an action, not * pre-notification of the action. This same event is fired to * subscribers of bound propertes and constrained * properties. Those who wish to affect whether or not the change * actually occurs should use a ConstrainedCollection. Those who merely wish * to be notified of changes should use an BoundCollection. *
* *
* The parent of this event is designed to monitor arbitrary properties of
* java beans. This class is designed to monitor only changes to
* collections. Therefore, the "property" field of this
* event is always set to "collection". Likewise, the
* "source" property must always be a BoundCollection
* or a ConstrainedCollection
.
*
PROPERTY
field of this class.
* @param source The collection which was modified.
* @param type The type of modification.
* @param changed Was the collection actually changed?
* @param element The element participating in the modification.
* @param parameter Used to indicate number of copies or index.
*/
public CollectionChangeEvent(Object source,
final CollectionChangeType type, final boolean changed,
final Object element, final int parameter) {
super(source, PROPERTY, null, null) ;
this.type = type ;
this.changed = changed ;
this.element = element ;
this.parameter = parameter ;
}
public CollectionChangeEvent(Object source,
final CollectionChangeType type, final boolean changed,
final Object element) {
this(source, type, changed, element, NOT_SET) ;
}
public CollectionChangeEvent(Object source,
final CollectionChangeType type, final boolean changed) {
this(source, type, changed, null, NOT_SET) ;
}
/**
* * Public constructor which sets the oldValue and newValue properties * of the parent object. This should be used only when an individual * element of a collection is changed from one value to another. This * is applicable, for instance, when a map entry is changed or a list * entry is set. The constructed object will have identical values for * the "element" property and the "newValue" * property. *
* @param source The collection which was modified. * @param type The type of modification. * @param changed Was the collection actually changed? * @param element The new value of the element. * @param oldElement the old value of the element. * @param parameter The index of the changed element. */ public CollectionChangeEvent(Object source, final CollectionChangeType type, final boolean changed, final Object element, final Object oldElement, final int parameter) { super(source, PROPERTY, oldElement, element) ; this.type = type ; this.changed = changed ; this.element = element ; this.parameter = parameter ; } /** *
* Public constructor which initializes the event appropriately for
* reporting a put()
event on a Map. The oldValue and
* newValue properties are set to the former and current values mapped
* to the key. The element property is set to the key.
*
null
if the change was an operation like
* clear()
.
* @return the element added or removed from the collection.
*/
public Object getElement() {
return element ;
}
/** Indicates whether the collection was changed as a result of the
* action.
* @return true
if the collection was changed,
* false
otherwise.
*/
public boolean isChanged() {
return changed ;
}
/**
* The "parameter" is an indication of the index into the
* collection or the number of copies added or removed by the operation.
* In many cases, the "parameter" will not be set, in which
* case it takes on the value NOT_SET
.
* @return the index, number of copies, or NOT_SET
*/
public int getParameter() {
return parameter ;
}
}