org.apache.commons.events.observable
Class ObservableList

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

All Implemented Interfaces:

Iterable, Collection, List

public class ObservableList
extends ObservableCollection
implements List

Decorates a List implementation to observe modifications.

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

All indices on events returned by subList are relative to the base List.

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

ObservableList.ObservableListIterator Inner class ListIterator for the ObservableList.

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	ObservableList(List list, Object listener) Constructor that wraps (not copies) and takes a handler.
protected	ObservableList(ModificationHandler handler, List list) Constructor used by subclass views, such as subList.

Method Summary

void	add(int index, Object object)
boolean	addAll(int index, Collection coll)
static ObservableList	decorate(List list) Factory method to create an observable list.
static ObservableList	decorate(List list, Object listener) Factory method to create an observable list using a listener or a handler.
Object	get(int index)
int	indexOf(Object object)
int	lastIndexOf(Object object)
ListIterator	listIterator()
ListIterator	listIterator(int index)
Object	remove(int index)
Object	set(int index, Object object)
List	subList(int fromIndex, int toIndex) Returns a subList view on the original base List.

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

add, 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 java.util.List

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

Constructor Detail

ObservableList

protected ObservableList(List list,
                         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:

list - the list to decorate, must not be null

listener - the listener, may be null

Throws:

IllegalArgumentException - if the list is null

ObservableList

protected ObservableList(ModificationHandler handler,
                         List list)

Constructor used by subclass views, such as subList.

Parameters:

handler - the handler to use, must not be null

list - the subList to decorate, must not be null

Throws:

IllegalArgumentException - if the list is null

Method Detail

decorate

public static ObservableList decorate(List list)

Factory method to create an observable list.

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

Parameters:

list - the list to decorate, must not be null

Returns:

the observed List

Throws:

IllegalArgumentException - if the list is null

decorate

public static ObservableList decorate(List list,
                                      Object listener)

Factory method to create an observable list 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 ObservableList 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:

list - the list to decorate, must not be null

listener - list listener, may be null

Returns:

the observed list

Throws:

IllegalArgumentException - if the list is null

IllegalArgumentException - if there is no valid handler for the listener

get

public Object get(int index)

Specified by:

get in interface List

indexOf

public int indexOf(Object object)

Specified by:

indexOf in interface List

lastIndexOf

public int lastIndexOf(Object object)

Specified by:

lastIndexOf in interface List

add

public void add(int index,
                Object object)

Specified by:

add in interface List

addAll

public boolean addAll(int index,
                      Collection coll)

Specified by:

addAll in interface List

remove

public Object remove(int index)

Specified by:

remove in interface List

set

public Object set(int index,
                  Object object)

Specified by:

set in interface List

listIterator

public ListIterator listIterator()

Specified by:

listIterator in interface List

listIterator

public ListIterator listIterator(int index)

Specified by:

listIterator in interface List

subList

public List subList(int fromIndex,
                    int toIndex)

Returns a subList view on the original base List.

Changes to the subList affect the underlying List. Change events will return change indices relative to the underlying List, not the subList.

Specified by:

subList in interface List

Parameters:

fromIndex - inclusive start index of the range

toIndex - exclusive end index of the range

Returns:

the subList view