com.cburch.editor.util
Class WeakEventSupport<L>

java.lang.Object
  com.cburch.editor.util.WeakEventSupport<L>

Type Parameters:

L - the type of listener we want to remember.

All Implemented Interfaces:

java.lang.Iterable<L>

public class WeakEventSupport<L>
extends java.lang.Object
implements java.lang.Iterable<L>

This class provides methods to support objects that may have listeners that do not persist for the lifetime of the object. It uses WeakReferences to remember the listeners; this way, the object's existence listening to the object does not count against the object's garbage collection.

You can read more about the WeakReference class in the documentation for Java's java.lang.ref package.

NOTE: Care must be taken with any listeners that references are maintained to the listener as long as it is needed. For example, the following popular idiom for creating listeners is invalid.

      // This is INVALID!!
      object.addListener(new Listener() {
           // ... required method definitions ...
      });
 

There will be no references to the anonymous object anywhere except within object. If object uses WeakEventSupport, then this reference will not count toward garbage collection. As a result, the anonymous listener object is immediately eligible for garbage collection, and it may well never hear of any of the events that it is intended to be listening for.

In general, if you want an object to listen for events initiated by an object using WeakEventSupport, then you will want to make sure that your object maintains an instance variable referring to the listener.

Version:

0.1 2005-05-31

Author:

Carl Burch

Constructor Summary

WeakEventSupport()
Constructs an empty list of listeners.

Method Summary

void	add(L listener) Adds a weak reference to the given listener into our list.
boolean	isEmpty() Says whether the list currently contains any elements that have not been collected out.
java.util.Iterator<L>	iterator() Returns an iterator for stepping through the active listeners of the list.
void	remove(L listener) Removes the given listener from our list.
int	size() Returns the number of active listeners in the list.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WeakEventSupport

public WeakEventSupport()

Constructs an empty list of listeners.

Method Detail

add

public void add(L listener)

Adds a weak reference to the given listener into our list.

Parameters:

listener - the listener to be added.

remove

public void remove(L listener)

Removes the given listener from our list.

Parameters:

listener - the listener to be removed.

isEmpty

public boolean isEmpty()

Says whether the list currently contains any elements that have not been collected out. It is possible that that isEmpty will return false at one time and true later on, even if no listeners have been explicitly added, because some listeners may have been stale and thus collected out.

Returns:

true if there are currently no active listeners in the list; false otherwise.

size

public int size()

Returns the number of active listeners in the list. This number may decrease, even when there are no deletions, because some listeners may become stale and be collected out.

Returns:

the number of listeners in the list.

iterator

public java.util.Iterator<L> iterator()

Returns an iterator for stepping through the active listeners of the list.

Specified by:

iterator in interface java.lang.Iterable<L>

Returns:

the iterator over active listeners.