org.apache.commons.events.observable
Class ObservableBag

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

All Implemented Interfaces:

Iterable, Collection, org.apache.commons.collections.Bag

Direct Known Subclasses:

ObservableSortedBag

public class ObservableBag
extends ObservableCollection
implements org.apache.commons.collections.Bag

Decorates a Bag implementation to observe modifications.

Each modifying method call made on this Bag 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.

NOTE: The uniqueSet() method returns a Set that is NOT observed. This is because the set should be unmodifiable.

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

Nested classes/interfaces inherited from class org.apache.commons.events.observable.ObservableCollection

ObservableCollection.ObservableIterator

Field Summary

Fields inherited from class org.apache.commons.events.observable.ObservableCollection

handler

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

collection

Constructor Summary

protected

ObservableBag(org.apache.commons.collections.Bag bag, Object listener) Constructor that wraps (not copies).

Method Summary

boolean	add(Object object)
boolean	add(Object object, int nCopies)
static ObservableBag	decorate(org.apache.commons.collections.Bag bag) Factory method to create an observable bag.
static ObservableBag	decorate(org.apache.commons.collections.Bag bag, Object listener) Factory method to create an observable bag using a listener or a handler.
int	getCount(Object object)
boolean	remove(Object object, int nCopies)
Set	uniqueSet()

Methods inherited from class org.apache.commons.events.observable.ObservableCollection

addAll, clear, createHandler, decorate, decorate, getHandler, iterator, registerFactory, remove, removeAll, retainAll

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

Methods inherited from interface org.apache.commons.collections.Bag

containsAll, iterator, remove, removeAll, retainAll, size

Methods inherited from interface java.util.Collection

addAll, clear, contains, equals, hashCode, isEmpty, toArray, toArray

Constructor Detail

ObservableBag

protected ObservableBag(org.apache.commons.collections.Bag bag,
                        Object listener)

Constructor that wraps (not copies).

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

Parameters:

bag - the bag to decorate, must not be null

listener - the listener, may be null

Throws:

IllegalArgumentException - if the bag is null

Method Detail

decorate

public static ObservableBag decorate(org.apache.commons.collections.Bag bag)

Factory method to create an observable bag.

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

Parameters:

bag - the bag to decorate, must not be null

Returns:

the observed Bag

Throws:

IllegalArgumentException - if the bag is null

decorate

public static ObservableBag decorate(org.apache.commons.collections.Bag bag,
                                     Object listener)

Factory method to create an observable bag 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 ObservableBag 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:

bag - the bag to decorate, must not be null

listener - bag listener, may be null

Returns:

the observed bag

Throws:

IllegalArgumentException - if the bag is null

IllegalArgumentException - if there is no valid handler for the listener

getCount

public int getCount(Object object)

Specified by:

getCount in interface org.apache.commons.collections.Bag

uniqueSet

public Set uniqueSet()

Specified by:

uniqueSet in interface org.apache.commons.collections.Bag

add

public boolean add(Object object)

Specified by:

add in interface Collection

Specified by:

add in interface org.apache.commons.collections.Bag

Overrides:

add in class ObservableCollection

add

public boolean add(Object object,
                   int nCopies)

Specified by:

add in interface org.apache.commons.collections.Bag

remove

public boolean remove(Object object,
                      int nCopies)

Specified by:

remove in interface org.apache.commons.collections.Bag