com.samskivert.util
Class ObserverList<T>

java.lang.Object
  java.util.AbstractCollection<E>
      java.util.AbstractList<E>
          java.util.ArrayList<T>
              com.samskivert.util.ObserverList<T>

All Implemented Interfaces:

Serializable, Cloneable, Iterable<T>, Collection<T>, List<T>, RandomAccess

Direct Known Subclasses:

ResultListenerList

public class ObserverList<T>
extends ArrayList<T>

Provides a simplified mechanism for maintaining a list of observers (or listeners or whatever you like to call them) and notifying those observers when desired. Notification takes place through a ObserverList.ObserverOp which allows the list maintainer to call an arbitrary method on its observers.

A couple of different usage patterns will help to illuminate. The first, where a new notify operation is created every time the observers are notified. This wins on brevity but loses on performance.

 ...
     // notify our observers
     final int foo = 19;
     final String bar = "yay!";
     _observers.apply(new ObserverList.ObserverOp() {
         public boolean apply (Object observer) {
             ((MyHappyObserver)observer).foozle(foo, bar);
             return true;
         }
     });
 ...
 

The second where a singleton instance of the operation class is maintained and is configured each time notification is desired.

 ...
     protected static class FoozleOp implements ObserverOp
     {
         public void init (int foo, String bar)
         {
             _foo = foo;
             _bar = bar;
         }

         public boolean apply (Object observer)
         {
             ((MyHappyObserver)observer).foozle(_foo, _bar);
             return true;
         }

         protected int _foo;
         protected String _bar;
     }
 ...
     // notify our observers
     _foozleOp.init(19, "yay!");
     _observers.apply(_foozleOp);
 ...
     protected static FoozleOp _foozleOp = new FoozleOp();
 ...
 

Bear in mind that this latter case is not thread safe.

Other usage patterns are most certainly conceivable, and hopefully these two will give you a useful starting point for determining what is the most appropriate usage for your needs.

See Also:

Serialized Form

Nested Class Summary

static interface

ObserverList.ObserverOp<T> Instances of this interface are used to apply methods to all observers in a list.

Field Summary

protected boolean	_allowDups Whether to allow observers to observe more than once simultaneously.
protected int	_policy The notification policy.
protected T[]	_snap Used to avoid creating a new snapshot array every time we notify our observers if the size has not changed.
static int	FAST_UNSAFE_NOTIFY A notification ordering policy wherein the observers are notified last to first so that they can be removed during the notification process and new observers added will not inadvertently be notified as well, but no copy of the observer list need be made.
static int	SAFE_IN_ORDER_NOTIFY A notification ordering policy indicating that the observers should be notified in the order they were added and that the notification should be done on a snapshot of the array.
protected static String	UNSUPPORTED_ADD_MESSAGE Message reported for unsupported add() variants.

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

ObserverList(int notifyPolicy)
Creates an empty observer list with the supplied notification policy and that only allows observers to observe the list once.

ObserverList(int notifyPolicy, boolean allowDups)
Creates an empty observer list with the supplied notification and duplicate observer policy.

Method Summary

void	add(int index, T element)
boolean	add(T element)
boolean	addAll(Collection<? extends T> c)
boolean	addAll(int index, Collection<? extends T> c)
void	apply(ObserverList.ObserverOp<T> obop) Applies the supplied observer operation to all observers in the list in a manner conforming to the notification ordering policy specified at construct time.
protected static <T> boolean	checkedApply(ObserverList.ObserverOp<T> obop, T obs) Applies the operation to the observer, catching and logging any exceptions thrown in the process.
int	indexOf(Object element)
protected boolean	isDuplicate(T obs) Returns true and issues a warning if this list does not allow duplicates and the supplied observer is already in the list.
int	lastIndexOf(Object element)
static <T> ObserverList<T>	newFastUnsafe() A convenience method for creating an observer list that avoids duplicating the type parameter on the right hand side.
static <T> ObserverList<T>	newList(int notifyPolicy, boolean allowDups) A convenience method for creating an observer list that avoids duplicating the type parameter on the right hand side.
static <T> ObserverList<T>	newSafeInOrder() A convenience method for creating an observer list that avoids duplicating the type parameter on the right hand side.
boolean	remove(Object element)

Methods inherited from class java.util.ArrayList

clear, clone, contains, ensureCapacity, get, isEmpty, remove, removeRange, set, size, toArray, toArray, trimToSize

Methods inherited from class java.util.AbstractList

equals, hashCode, iterator, listIterator, listIterator, subList

Methods inherited from class java.util.AbstractCollection

containsAll, removeAll, retainAll, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.List

containsAll, equals, hashCode, iterator, listIterator, listIterator, removeAll, retainAll, subList

Field Detail

SAFE_IN_ORDER_NOTIFY

public static final int SAFE_IN_ORDER_NOTIFY

A notification ordering policy indicating that the observers should be notified in the order they were added and that the notification should be done on a snapshot of the array.

See Also:

Constant Field Values

FAST_UNSAFE_NOTIFY

public static final int FAST_UNSAFE_NOTIFY

A notification ordering policy wherein the observers are notified last to first so that they can be removed during the notification process and new observers added will not inadvertently be notified as well, but no copy of the observer list need be made. This will not work if observers are added or removed from arbitrary positions in the list during a notification call.

See Also:

Constant Field Values

_policy

protected int _policy

The notification policy.

_allowDups

protected boolean _allowDups

Whether to allow observers to observe more than once simultaneously.

_snap

protected T[] _snap

Used to avoid creating a new snapshot array every time we notify our observers if the size has not changed.

UNSUPPORTED_ADD_MESSAGE

protected static final String UNSUPPORTED_ADD_MESSAGE

Message reported for unsupported add() variants.

See Also:

Constant Field Values

Constructor Detail

ObserverList

public ObserverList(int notifyPolicy)

Creates an empty observer list with the supplied notification policy and that only allows observers to observe the list once.

Parameters:

notifyPolicy - Either SAFE_IN_ORDER_NOTIFY or FAST_UNSAFE_NOTIFY.

ObserverList

public ObserverList(int notifyPolicy,
                    boolean allowDups)

Creates an empty observer list with the supplied notification and duplicate observer policy.

Parameters:

notifyPolicy - Either SAFE_IN_ORDER_NOTIFY or FAST_UNSAFE_NOTIFY.

allowDups - whether to allow observers to be added to the list more than once.

Method Detail

newSafeInOrder

public static <T> ObserverList<T> newSafeInOrder()

A convenience method for creating an observer list that avoids duplicating the type parameter on the right hand side.

newFastUnsafe

public static <T> ObserverList<T> newFastUnsafe()

A convenience method for creating an observer list that avoids duplicating the type parameter on the right hand side.

newList

public static <T> ObserverList<T> newList(int notifyPolicy,
                                          boolean allowDups)

A convenience method for creating an observer list that avoids duplicating the type parameter on the right hand side.

add

public void add(int index,
                T element)

Specified by:

add in interface List<T>

Overrides:

add in class ArrayList<T>

add

public boolean add(T element)

Specified by:

add in interface Collection<T>

Specified by:

add in interface List<T>

Overrides:

add in class ArrayList<T>

addAll

public boolean addAll(Collection<? extends T> c)

Specified by:

addAll in interface Collection<T>

Specified by:

addAll in interface List<T>

Overrides:

addAll in class ArrayList<T>

addAll

public boolean addAll(int index,
                      Collection<? extends T> c)

Specified by:

addAll in interface List<T>

Overrides:

addAll in class ArrayList<T>

indexOf

public int indexOf(Object element)

Specified by:

indexOf in interface List<T>

Overrides:

indexOf in class ArrayList<T>

lastIndexOf

public int lastIndexOf(Object element)

Specified by:

lastIndexOf in interface List<T>

Overrides:

lastIndexOf in class ArrayList<T>

remove

public boolean remove(Object element)

Specified by:

remove in interface Collection<T>

Specified by:

remove in interface List<T>

Overrides:

remove in class ArrayList<T>

apply

public void apply(ObserverList.ObserverOp<T> obop)

Applies the supplied observer operation to all observers in the list in a manner conforming to the notification ordering policy specified at construct time.

isDuplicate

protected boolean isDuplicate(T obs)

Returns true and issues a warning if this list does not allow duplicates and the supplied observer is already in the list. Returns false if the supplied observer is not a duplicate.

checkedApply

protected static <T> boolean checkedApply(ObserverList.ObserverOp<T> obop,
                                          T obs)

Applies the operation to the observer, catching and logging any exceptions thrown in the process.