org.apache.commons.events.observable
Class ModificationHandler

java.lang.Object
  extended by org.apache.commons.events.observable.ModificationHandler
Direct Known Subclasses:
ModificationHandler.SetViewHandler, ModificationHandler.SubListHandler, StandardModificationHandler

public class ModificationHandler
extends Object

Defines a handler for collection modification events.

This class defines the event handling methods, following the preXxx and postXxx naming convention. It also provides a default implementation that forwards to single methods.

To write your own handler, you will normally subclass and override the preEvent and postEvent methods. However, you could choose to override any individual event method.

This class could have been implemented as an interface, however to do so would prevent the addition of extra events in the future. It does mean that if you subclass this class, you must check it when you upgrade to a later release.

Since:
Commons Events 1.0
Version:
$Revision: 155443 $ $Date: 2005-02-26 13:19:51 +0000 (Sat, 26 Feb 2005) $
Author:
Stephen Colebourne

Nested Class Summary
protected static class ModificationHandler.SetViewHandler
          Inner class for views.
protected static class ModificationHandler.SubListHandler
          Inner class for subLists.
 
Constructor Summary
protected ModificationHandler()
          Constructor.
protected ModificationHandler(ModificationHandler rootHandler, int viewOffset)
          Constructor.
 
Method Summary
 void addPostModificationListener(Object listener)
          Adds a post listener to the list held in the handler.
 void addPreModificationListener(Object listener)
          Adds a pre listener to the list held in the handler.
protected  ModificationHandler createHeadSetHandler(Object toElement)
          Creates a new handler for SortedSet headSet.
protected  ModificationHandler createSubListHandler(int fromIndex, int toIndex)
          Creates a new handler for subLists that is aware of the offset.
protected  ModificationHandler createSubSetHandler(Object fromElement, Object toElement)
          Creates a new handler for SortedSet subSet.
protected  ModificationHandler createTailSetHandler(Object fromElement)
          Creates a new handler for SortedSet tailSet.
protected  Collection getBaseCollection()
          Gets the base collection.
 ObservableCollection getObservedCollection()
          Gets the observed collection.
 Object[] getPostModificationListeners()
          Gets an array of all the post listeners active in the handler.
 Object[] getPreModificationListeners()
          Gets an array of all the pre listeners active in the handler.
protected  ModificationHandler getRootHandler()
          Gets the root handler.
protected  int getViewOffset()
          Gets the view offset.
protected  void postAdd(Object object, boolean result)
          Send an event after add(obj) is called.
protected  void postAddAll(Collection coll, boolean collChanged)
          Send an event after addAll(coll) is called.
protected  void postAddAllIndexed(int index, Collection coll, boolean collChanged)
          Send an event after addAll(int,coll) is called on a List.
protected  void postAddIndexed(int index, Object object)
          Send an event after add(int,obj) is called on a List.
protected  void postAddIterated(int index, Object object)
          Send an event after add(obj) is called on a ListIterator.
protected  void postAddNCopies(Object object, int nCopies, boolean result)
          Send an event after add(obj,int) is called on a Bag.
protected  void postClear()
          Send an event after clear() is called.
protected  void postEvent(boolean modified, int type, int index, Object object, int repeat, Object previous, ObservableCollection view, int viewOffset)
          Handles the post event.
protected  void postRemove(Object object, boolean collChanged)
          Send an event after remove(obj) is called.
protected  void postRemoveAll(Collection coll, boolean collChanged)
          Send an event after removeAll(coll) is called.
protected  void postRemoveIndexed(int index, Object previousValue)
          Send an event after remove(int) is called on a List.
protected  void postRemoveIterated(int index, Object removedValue)
          Send an event after remove(obj) is called on an Iterator.
protected  void postRemoveNCopies(Object object, int nCopies, boolean collChanged)
          Send an event after remove(obj,int) is called on a Bag.
protected  void postRemoveNext(Object removedValue)
          Send an event after remove() is called on a Buffer.
protected  void postRetainAll(Collection coll, boolean collChanged)
          Send an event after retainAll(coll) is called.
protected  void postSetIndexed(int index, Object object, Object previousValue)
          Send an event after set(int,obj) is called on a List.
protected  void postSetIterated(int index, Object object, Object previousValue)
          Send an event after set(obj) is called on a ListIterator.
protected  boolean preAdd(Object object)
          Store data and send event before add(obj) is called.
protected  boolean preAddAll(Collection coll)
          Store data and send event before addAll(coll) is called.
protected  boolean preAddAllIndexed(int index, Collection coll)
          Store data and send event before addAll(int,coll) is called on a List.
protected  boolean preAddIndexed(int index, Object object)
          Store data and send event before add(int,obj) is called on a List.
protected  boolean preAddIterated(int index, Object object)
          Store data and send event before add(obj) is called on a ListIterator.
protected  boolean preAddNCopies(Object object, int nCopies)
          Store data and send event before add(obj,int) is called on a Bag.
protected  boolean preClear()
          Store data and send event before clear() is called.
protected  boolean preEvent(int type, int index, Object object, int repeat, Object previous, ObservableCollection view, int viewOffset)
          Handles the pre event.
protected  boolean preRemove(Object object)
          Store data and send event before remove(obj) is called.
protected  boolean preRemoveAll(Collection coll)
          Store data and send event before removeAll(coll) is called.
protected  boolean preRemoveIndexed(int index)
          Store data and send event before remove(int) is called on a List.
protected  boolean preRemoveIterated(int index, Object removedValue)
          Store data and send event before remove(obj) is called on an Iterator.
protected  boolean preRemoveNCopies(Object object, int nCopies)
          Store data and send event before remove(obj,int) is called on a Bag.
protected  boolean preRemoveNext()
          Store data and send event before remove() is called on a Buffer.
protected  boolean preRetainAll(Collection coll)
          Store data and send event before retainAll(coll) is called.
protected  boolean preSetIndexed(int index, Object object)
          Store data and send event before set(int,obj) is called on a List.
protected  boolean preSetIterated(int index, Object object, Object previousValue)
          Store data and send event before set(obj) is called on a ListIterator.
 void removePostModificationListener(Object listener)
          Removes a post listener to the list held in the handler.
 void removePreModificationListener(Object listener)
          Removes a pre listener to the list held in the handler.
 String toString()
          Gets a debugging string version of this object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ModificationHandler

protected ModificationHandler()
Constructor.


ModificationHandler

protected ModificationHandler(ModificationHandler rootHandler,
                              int viewOffset)
Constructor.

Parameters:
rootHandler - the base underlying handler
viewOffset - the offset on the base collection
Method Detail

getObservedCollection

public ObservableCollection getObservedCollection()
Gets the observed collection.

Returns:
the observed collection

getBaseCollection

protected Collection getBaseCollection()
Gets the base collection.

Returns:
the base collection

getRootHandler

protected ModificationHandler getRootHandler()
Gets the root handler.

Returns:
the root handler

getViewOffset

protected int getViewOffset()
Gets the view offset.

Returns:
the view offset

getPreModificationListeners

public Object[] getPreModificationListeners()
Gets an array of all the pre listeners active in the handler.

This implementation throws UnsupportedOperationException.

Returns:
the listeners
Throws:
UnsupportedOperationException - if the handler does not support listeners

addPreModificationListener

public void addPreModificationListener(Object listener)
Adds a pre listener to the list held in the handler.

No error occurs if the listener is null.

The listener does not necessarily have to be a listener in the classic JavaBean sense. It is entirely up to the handler as to how it interprets the listener parameter. A ClassCastException is thrown if the handler cannot interpret the parameter.

This implementation throws UnsupportedOperationException.

Parameters:
listener - the listener to add, may be null (ignored)
Throws:
ClassCastException - if the listener is not of the correct type
UnsupportedOperationException - if the handler does not support listeners

removePreModificationListener

public void removePreModificationListener(Object listener)
Removes a pre listener to the list held in the handler.

No error occurs if the listener is not in the list or the type of the listener is incorrect.

This implementation throws UnsupportedOperationException.

Parameters:
listener - the listener to remove, may be null (ignored)
Throws:
UnsupportedOperationException - if the handler does not support listeners

getPostModificationListeners

public Object[] getPostModificationListeners()
Gets an array of all the post listeners active in the handler.

This implementation throws UnsupportedOperationException.

Returns:
the listeners
Throws:
UnsupportedOperationException - if the handler does not support listeners

addPostModificationListener

public void addPostModificationListener(Object listener)
Adds a post listener to the list held in the handler.

No error occurs if the listener is null.

The listener does not necessarily have to be a listener in the classic JavaBean sense. It is entirely up to the handler as to how it interprets the listener parameter. A ClassCastException is thrown if the handler cannot interpret the parameter.

This implementation throws UnsupportedOperationException.

Parameters:
listener - the listener to add, may be null (ignored)
Throws:
ClassCastException - if the listener is not of the correct type
UnsupportedOperationException - if the handler does not support listeners

removePostModificationListener

public void removePostModificationListener(Object listener)
Removes a post listener to the list held in the handler.

No error occurs if the listener is not in the list or the type of the listener is incorrect.

This implementation throws UnsupportedOperationException.

Parameters:
listener - the listener to remove, may be null (ignored)
Throws:
UnsupportedOperationException - if the handler does not support listeners

preEvent

protected boolean preEvent(int type,
                           int index,
                           Object object,
                           int repeat,
                           Object previous,
                           ObservableCollection view,
                           int viewOffset)
Handles the pre event.

This implementation does nothing.

Parameters:
type - the event type to send
index - the index where the change starts, the method param or derived
object - the object that will be added/removed/set, the method param or derived
repeat - the number of repeats of the add/remove, the method param or derived
previous - the previous value that will be removed/replaced, must exist in coll
view - the view collection that the change was actioned on, null if no view
viewOffset - the offset of the subList view, -1 if unknown

postEvent

protected void postEvent(boolean modified,
                         int type,
                         int index,
                         Object object,
                         int repeat,
                         Object previous,
                         ObservableCollection view,
                         int viewOffset)
Handles the post event.

This implementation does nothing.

Parameters:
modified - true if the method succeeded in changing the collection
type - the event type to send
index - the index where the change starts, the method param or derived
object - the object that was added/removed/set, the method param or derived
repeat - the number of repeats of the add/remove, the method param or derived
previous - the previous value that was removed/replace, must have existed in coll
view - the view collection that the change was actioned on, null if no view
viewOffset - the offset of the subList view, -1 if unknown

preAdd

protected boolean preAdd(Object object)
Store data and send event before add(obj) is called.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int). It does not set the index for List implementations.

Parameters:
object - the object being added
Returns:
true to process modification

postAdd

protected void postAdd(Object object,
                       boolean result)
Send an event after add(obj) is called.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int). It does not set the index for List implementations.

Parameters:
object - the object being added
result - the result from the add method

preAddIndexed

protected boolean preAddIndexed(int index,
                                Object object)
Store data and send event before add(int,obj) is called on a List.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index to add at
object - the object being added
Returns:
true to process modification

postAddIndexed

protected void postAddIndexed(int index,
                              Object object)
Send an event after add(int,obj) is called on a List.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index to add at
object - the object being added

preAddNCopies

protected boolean preAddNCopies(Object object,
                                int nCopies)
Store data and send event before add(obj,int) is called on a Bag.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
object - the object being added
nCopies - the number of copies being added
Returns:
true to process modification

postAddNCopies

protected void postAddNCopies(Object object,
                              int nCopies,
                              boolean result)
Send an event after add(obj,int) is called on a Bag.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int). The method result is not used by this implementation (Bag violates the Collection contract)

Parameters:
object - the object being added
nCopies - the number of copies being added
result - the method result

preAddIterated

protected boolean preAddIterated(int index,
                                 Object object)
Store data and send event before add(obj) is called on a ListIterator.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index of the iterator
object - the object being added
Returns:
true to process modification

postAddIterated

protected void postAddIterated(int index,
                               Object object)
Send an event after add(obj) is called on a ListIterator.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index of the iterator
object - the object being added

preAddAll

protected boolean preAddAll(Collection coll)
Store data and send event before addAll(coll) is called.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
coll - the collection being added
Returns:
true to process modification

postAddAll

protected void postAddAll(Collection coll,
                          boolean collChanged)
Send an event after addAll(coll) is called.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
coll - the collection being added
collChanged - the result from the addAll method

preAddAllIndexed

protected boolean preAddAllIndexed(int index,
                                   Collection coll)
Store data and send event before addAll(int,coll) is called on a List.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index to addAll at
coll - the collection being added
Returns:
true to process modification

postAddAllIndexed

protected void postAddAllIndexed(int index,
                                 Collection coll,
                                 boolean collChanged)
Send an event after addAll(int,coll) is called on a List.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index to addAll at
coll - the collection being added
collChanged - the result from the addAll method

preClear

protected boolean preClear()
Store data and send event before clear() is called.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Returns:
true to process modification

postClear

protected void postClear()
Send an event after clear() is called.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).


preRemove

protected boolean preRemove(Object object)
Store data and send event before remove(obj) is called.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
object - the object being removed
Returns:
true to process modification

postRemove

protected void postRemove(Object object,
                          boolean collChanged)
Send an event after remove(obj) is called.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
object - the object being removed
collChanged - the result from the remove method

preRemoveIndexed

protected boolean preRemoveIndexed(int index)
Store data and send event before remove(int) is called on a List.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index to remove at
Returns:
true to process modification

postRemoveIndexed

protected void postRemoveIndexed(int index,
                                 Object previousValue)
Send an event after remove(int) is called on a List.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index to remove at
previousValue - the result from the remove method

preRemoveNCopies

protected boolean preRemoveNCopies(Object object,
                                   int nCopies)
Store data and send event before remove(obj,int) is called on a Bag.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
object - the object being removed
nCopies - the number of copies being removed
Returns:
true to process modification

postRemoveNCopies

protected void postRemoveNCopies(Object object,
                                 int nCopies,
                                 boolean collChanged)
Send an event after remove(obj,int) is called on a Bag.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
object - the object being removed
nCopies - the number of copies being removed
collChanged - the result from the remove method

preRemoveNext

protected boolean preRemoveNext()
Store data and send event before remove() is called on a Buffer.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Returns:
true to process modification

postRemoveNext

protected void postRemoveNext(Object removedValue)
Send an event after remove() is called on a Buffer.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
removedValue - the previous value at this index

preRemoveIterated

protected boolean preRemoveIterated(int index,
                                    Object removedValue)
Store data and send event before remove(obj) is called on an Iterator.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index of the iterator
removedValue - the object being removed
Returns:
true to process modification

postRemoveIterated

protected void postRemoveIterated(int index,
                                  Object removedValue)
Send an event after remove(obj) is called on an Iterator.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index of the iterator
removedValue - the previous value at this index

preRemoveAll

protected boolean preRemoveAll(Collection coll)
Store data and send event before removeAll(coll) is called.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
coll - the collection being removed
Returns:
true to process modification

postRemoveAll

protected void postRemoveAll(Collection coll,
                             boolean collChanged)
Send an event after removeAll(coll) is called.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
coll - the collection being removed
collChanged - the result from the removeAll method

preRetainAll

protected boolean preRetainAll(Collection coll)
Store data and send event before retainAll(coll) is called.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
coll - the collection being retained
Returns:
true to process modification

postRetainAll

protected void postRetainAll(Collection coll,
                             boolean collChanged)
Send an event after retainAll(coll) is called.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
coll - the collection being retained
collChanged - the result from the retainAll method

preSetIndexed

protected boolean preSetIndexed(int index,
                                Object object)
Store data and send event before set(int,obj) is called on a List.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index to add at
object - the object being added
Returns:
true to process modification

postSetIndexed

protected void postSetIndexed(int index,
                              Object object,
                              Object previousValue)
Send an event after set(int,obj) is called on a List.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index to add at
object - the object being added
previousValue - the result from the set method

preSetIterated

protected boolean preSetIterated(int index,
                                 Object object,
                                 Object previousValue)
Store data and send event before set(obj) is called on a ListIterator.

This implementation forwards to preEvent(int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index to set at
object - the object being added
previousValue - the previous value at this index
Returns:
true to process modification

postSetIterated

protected void postSetIterated(int index,
                               Object object,
                               Object previousValue)
Send an event after set(obj) is called on a ListIterator.

This implementation forwards to postEvent(boolean, int, int, java.lang.Object, int, java.lang.Object, org.apache.commons.events.observable.ObservableCollection, int).

Parameters:
index - the index to set at
object - the object being added
previousValue - the previous value at this index

createSubSetHandler

protected ModificationHandler createSubSetHandler(Object fromElement,
                                                  Object toElement)
Creates a new handler for SortedSet subSet.

Parameters:
fromElement - the from element
toElement - the to element

createHeadSetHandler

protected ModificationHandler createHeadSetHandler(Object toElement)
Creates a new handler for SortedSet headSet.

Parameters:
toElement - the to element

createTailSetHandler

protected ModificationHandler createTailSetHandler(Object fromElement)
Creates a new handler for SortedSet tailSet.

Parameters:
fromElement - the from element

createSubListHandler

protected ModificationHandler createSubListHandler(int fromIndex,
                                                   int toIndex)
Creates a new handler for subLists that is aware of the offset.

Parameters:
fromIndex - the sublist fromIndex (inclusive)
toIndex - the sublist toIndex (exclusive)

toString

public String toString()
Gets a debugging string version of this object.

Overrides:
toString in class Object
Returns:
a debugging string


Copyright © 2001-2010 The Apache Software Foundation. All Rights Reserved.