package org.apache.commons.events.observable ; import java.util.Collection; import java.util.Map ; /** *
* This interface defines a factory for the production of * CollectionChangeEvents. The purpose of this factory is to provide a means * of instantiating custom, user-defined CollectionChangeEvents without * modification to the BoundCollection or ConstrainedCollection classes. * Should users decide to write their own CollectionChangeEvents which * provide more information than the supplied classes, they would need to * implement this interface and supply an instance to the appropriate * ObservedCollection class. *
* * @see CollectionChangeEvent * @see CollectionChangeType * @see BoundCollection * @see ConstrainedCollection * @author Bryce Nordgren / USDA Forest Service * @since 0.1 */ public interface CollectionChangeEventFactory extends Cloneable { /** * Returns the collection responsible for events constructed by this * factory. This must be one of the decorator classes defined in * this package. * @return source of CollectionChangeEvents. */ public Object getCollection() ; /** * Sets the collection responsible for events constructed by this * factory. This must be one of the decorator classes defined in * this package. The type of this property isObject
* because java.util.Map
, while part of the Collections
* framework, does not share a common parentage with
* java.util.Collection
. Legal values are instances or
* subclasses of:
* source
is not
* a BoundCollection or a ConstrainedCollection.
* @throws UnsupportedOperationException if the source has already
* been set.
*/
public void setCollection(Object source) ;
/**
*
* Clones a CollectionChangeEventFactory
by
* constructing a copy of the existing factory, without copying the
* event source. The user must call setCollection()
* on the returned factory prior to use. In effect, this event factory
* suffers from inadequate separation of concerns because it is required to
* know the details of event construction as well as the specific object
* which caused the event. This clone method causes duplication of the
* event construction logic while permitting the caller to specify a
* different event source. As such, implementors should ensure that all
* configuration and setup from the original object is duplicated in the
* returned object except for the event source.
*
* This method exists so that sub lists (and other derivative collections) * can use the same event factory as the original list. *
* @return A duplicate of this factory, except the event source is not set. */ public Object clone() ; /** * Instantiates and returns aCollectionChangeEvent
* of type ADD
.
*
* @param element The element added to the collection.
* @param changed True
if the element was added to the
* collecton, false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createAdd(Object element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type ADD_INDEXED
. The "parameter"
* property is initialized to contain the index.
*
* @param element The element added to the collection.
* @param index The index at which the item is added.
* @param changed True
if the element was added to the
* collecton, false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createAddIndexed(
int index, Object element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type ADD_NCOPIES
. The "parameter"
* property is initialized to contain the specified number of copies.
*
* @param element The element added to the collection.
* @param copies How many copies to add.
* @param changed True
if the element was added to the
* collecton, false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createAddNCopies(
int copies, Object element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type ADD_ITERATED
. The "parameter"
* property is initialized to contain the index.
*
* @param element The element added to the collection.
* @param index The index at which the item is added.
* @param changed True
if the element was added to the
* collecton, false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createAddIterated(
int index, Object element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type ADD_ALL
.
*
* @param element The collection containing all the elements to be added.
* @param changed True
if the element was added to the
* collecton, false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createAddAll(
Collection element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type ADD_ALL_INDEXED
. The "parameter"
* property is initialized to contain the index.
*
* @param element The collection containing all the elements to be added.
* @param index The index at which the collection is added.
* @param changed True
if the element was added to the
* collecton, false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createAddAllIndexed(
int index, Collection element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type CLEAR
.
*
* @param changed True
if the collection was nonempty
* before it was cleared, false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createClear(boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type REMOVE
.
*
* @param element The element removed from the collection.
* @param changed True
if the element was removed from the
* collecton, false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createRemove(Object element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type REMOVE_INDEXED
. The "parameter"
* property is initialized to contain the index.
*
* @param element The element removed from the collection.
* @param index The index of the removed item.
* @param changed True
if the element was removed from the
* collecton, false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createRemoveIndexed(
int index, Object element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type REMOVE_NCOPIES
. The "parameter"
* property is initialized to contain the index.
*
* @param element The element removed from the collection.
* @param copies The number of copies to remove.
* @param changed True
if the element was removed from the
* collecton, false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createRemoveNCopies(
int copies, Object element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type REMOVE_NEXT
. The "parameter"
* property is initialized to contain the index. This event
* applies to a buffer.
*
* @param element The element removed from the buffer.
* @param changed True
if the element was removed from the
* collecton, false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createRemoveNext(
Object element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type REMOVE_ITERATED
. The "parameter"
* property is initialized to contain the index.
*
* @param element The element removed from the collection.
* @param index The index of the iterator when remove was called.
* @param changed True
if the element was removed from the
* collecton, false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createRemoveIterated(
int index, Object element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type REMOVE_ALL
.
*
* @param element The collection containing all items to remove from
* this collection.
* @param changed True
if the element was removed from the
* collecton, false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createRemoveAll(
Collection element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type RETAIN_ALL
.
*
* @param element The Collection containing all elements to be retained.
* @param changed True
if the observed collection was
* changed.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createRetainAll(
Collection element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type SET_INDEXED
. The "parameter"
* property is initialized to contain the index. Additionally, the
* oldValue
and newValue
properties are
* set to the former and current values of the element at the index,
* respectively.
*
* @param element The new value of the element at index
.
* This is stored in the element
and newValue
* properties.
* @param oldValue The former value of the element at index
.
* This is stored in the oldValue
property.
* @param index The index of the changed item.
* @param changed True
if the element was changed,
* false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createSetIndexed(
int index, Object oldValue, Object element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type SET_ITERATED
. The "parameter"
* property is initialized to contain the index. Additionally, the
* oldValue
and newValue
properties are
* set to the former and current values of the element at the index,
* respectively.
*
* @param element The new value of the element at index
.
* This is stored in the element
and newValue
* properties.
* @param oldValue The former value of the element at index
.
* This is stored in the oldValue
property.
* @param index The index of the changed item.
* @param changed True
if the element was changed,
* false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createSetIterated(
int index, Object oldValue, Object element, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type PUT
. This is unique among the
* CollectionChangeEvents
in that a single addition
* involves two objects, namely a key-value pair. Additionally,
* the if the key was already present in the map, the former
* value is returned. The former and present "values" are
* stored in oldValue
and newValue
properties,
* respectively. The element
property is set to the key.
*
* @param key The key provided to the put()
method.
* @param value The value provided to the put()
method.
* @param oldValue The value returned by the call to put()
.
* @param changed True
if the element was changed,
* false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createPut(
Object key, Object value, Object oldValue, boolean changed) ;
/**
* Instantiates and returns a CollectionChangeEvent
* of type PUT_ALL
. The element
property
* is set to the Map containing all the entries to be added.
*
* @param newElements The map containing the entries to add.
* @param changed True
if the element was changed,
* false
otherwise.
* @return A new event, properly initialized and ready to fire.
*/
public CollectionChangeEvent createPutAll(
Map newElements, boolean changed) ;
}