org.apache.commons.events.observable
Class ObservableCollection

java.lang.Object
  org.apache.commons.collections.collection.AbstractCollectionDecorator
      org.apache.commons.events.observable.ObservableCollection

All Implemented Interfaces:

Iterable, Collection

Direct Known Subclasses:

ObservableBag, ObservableBuffer, ObservableList, ObservableSet

public class ObservableCollection
extends org.apache.commons.collections.collection.AbstractCollectionDecorator

Decorates a Collection implementation to observe modifications.

Each modifying method call made on this Collection is forwarded to a ModificationHandler. The handler manages the event, notifying listeners and optionally vetoing changes. The default handler is StandardModificationHandler. See this class for details of configuration available.

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 class

ObservableCollection.ObservableIterator Inner class Iterator for the ObservableCollection.

Field Summary

protected ModificationHandler

handler The handler to delegate event handling to

Fields inherited from class org.apache.commons.collections.collection.AbstractCollectionDecorator

collection

Constructor Summary

protected	ObservableCollection(Collection coll, Object listener) Constructor that wraps (not copies) and takes a handler.
protected	ObservableCollection(ModificationHandler handler, Collection coll) Constructor used by subclass views, such as subList.

Method Summary

boolean	add(Object object)
boolean	addAll(Collection coll)
void	clear()
protected ModificationHandler	createHandler(Collection coll, Object listener) Creates a handler subclass based on the specified listener.
static ObservableCollection	decorate(Collection coll) Factory method to create an observable collection.
static ObservableCollection	decorate(Collection coll, Object listener) Factory method to create an observable collection using a listener or a handler.
ModificationHandler	getHandler() Gets the handler that is observing this collection.
Iterator	iterator()
static void	registerFactory(ModificationHandlerFactory factory) Registers a handler factory to be used for looking up a listener to a handler.
boolean	remove(Object object)
boolean	removeAll(Collection coll)
boolean	retainAll(Collection coll)

Methods inherited from class org.apache.commons.collections.collection.AbstractCollectionDecorator

contains, containsAll, equals, getCollection, hashCode, isEmpty, size, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

handler

protected final ModificationHandler handler

The handler to delegate event handling to

Constructor Detail

ObservableCollection

protected ObservableCollection(Collection coll,
                               Object listener)

Constructor that wraps (not copies) and takes a handler.

The handler implementation is determined by the listener parameter via the registered factories. The listener may be a manually configured ModificationHandler instance.

Parameters:

coll - the collection to decorate, must not be null

listener - the observing handler, may be null

Throws:

IllegalArgumentException - if the collection is null

ObservableCollection

protected ObservableCollection(ModificationHandler handler,
                               Collection coll)

Constructor used by subclass views, such as subList.

Parameters:

handler - the observing handler, may be null

coll - the collection to decorate, must not be null

Throws:

IllegalArgumentException - if the collection is null

Method Detail

decorate

public static ObservableCollection decorate(Collection coll)

Factory method to create an observable collection.

A StandardModificationHandler will be created. This can be accessed by getHandler() to add listeners.

Parameters:

coll - the collection to decorate, must not be null

Returns:

the observed collection

Throws:

IllegalArgumentException - if the collection is null

decorate

public static ObservableCollection decorate(Collection coll,
                                            Object listener)

Factory method to create an observable collection using a listener or a handler.

A lot of functionality is available through this method. If you don't need the extra functionality, simply implement the StandardModificationListener interface and pass it in as the second parameter.

Internally, an ObservableCollection relies on a ModificationHandler. The handler receives all the events and processes them, typically by calling listeners. Different handler implementations can be plugged in to provide a flexible event system.

The handler implementation is determined by the listener parameter via the registered factories. The listener may be a manually configured ModificationHandler instance.

The listener is defined as an Object for maximum flexibility. It does not have to be a listener in the classic JavaBean sense. It is entirely up to the factory and handler as to how the parameter is interpretted. An IllegalArgumentException is thrown if no suitable handler can be found for this listener.

A null listener will create a StandardModificationHandler.

Parameters:

coll - the collection to decorate, must not be null

listener - collection listener, may be null

Returns:

the observed collection

Throws:

IllegalArgumentException - if the collection is null

IllegalArgumentException - if there is no valid handler for the listener

registerFactory

public static void registerFactory(ModificationHandlerFactory factory)

Registers a handler factory to be used for looking up a listener to a handler.

This method is used to add your own event handler to the supplied ones. Registering the factory will enable the decorate(Collection, Object) method to create your handler.

Each handler added becomes the first in the lookup chain. Thus it is possible to override the default setup. Obviously this should be done with care in a shared web environment!

This method is not guaranteed to be threadsafe. It should only be called during initialization. Problems will occur if two threads call this method at the same time.

Parameters:

factory - the factory to add, may be null

createHandler

protected ModificationHandler createHandler(Collection coll,
                                            Object listener)

Creates a handler subclass based on the specified listener.

The method is defined in terms of an Object to allow for unusual listeners, such as a Swing model object.

Parameters:

listener - a listener object to create a handler for

Returns:

an instantiated handler with the listener attached

Throws:

IllegalArgumentException - if no suitable handler

getHandler

public ModificationHandler getHandler()

Gets the handler that is observing this collection.

Returns:

the observing handler, never null

add

public boolean add(Object object)

Specified by:

add in interface Collection

Overrides:

add in class org.apache.commons.collections.collection.AbstractCollectionDecorator

addAll

public boolean addAll(Collection coll)

Specified by:

addAll in interface Collection

Overrides:

addAll in class org.apache.commons.collections.collection.AbstractCollectionDecorator

clear

public void clear()

Specified by:

clear in interface Collection

Overrides:

clear in class org.apache.commons.collections.collection.AbstractCollectionDecorator

iterator

public Iterator iterator()

Specified by:

iterator in interface Iterable

Specified by:

iterator in interface Collection

Overrides:

iterator in class org.apache.commons.collections.collection.AbstractCollectionDecorator

remove

public boolean remove(Object object)

Specified by:

remove in interface Collection

Overrides:

remove in class org.apache.commons.collections.collection.AbstractCollectionDecorator

removeAll

public boolean removeAll(Collection coll)

Specified by:

removeAll in interface Collection

Overrides:

removeAll in class org.apache.commons.collections.collection.AbstractCollectionDecorator

retainAll

public boolean retainAll(Collection coll)

Specified by:

retainAll in interface Collection

Overrides:

retainAll in class org.apache.commons.collections.collection.AbstractCollectionDecorator