org.openbp.common.listener
Class ListenerSupport

java.lang.Object
  org.openbp.common.listener.ListenerSupport

Direct Known Subclasses:

AWTListenerSupport, BeanListenerSupport, SwingListenerSupport

public class ListenerSupport
extends java.lang.Object

This class holds a list of event listeners. It can be used to implement generic listener functionality. It combines listeners of various type into a single 'listener manager' class. Listeners can be added as regular 'hard' references (addListener(java.lang.Class, java.util.EventListener)) or as 'weak' references (addWeakListener(java.lang.Class, java.util.EventListener)), which may be garbage-collected if not referenced otherwise. The add-methods also ensure that the same listener will not be registered twice (comparing the listener objects using the == operation). Listeners that have not been removed from the object they have been registered with are a common cause for memory leaks. By adding them as weak listeners, you may not just add and forget them. They will be automatically garbage-collected if not referenced otherwise and automatically (i. e. after a call to the getListenerIterator(java.lang.Class) method) removed from the listener list.
ATTENTION: Never add an automatic class (i. e new FocusListener () { ... }) or an inner class that is not referenced otherwise as a weak listener to the list. These objects will be cleared by the garbage collector during the next gc run! The listeners and the corresponding listener classes will be stored in a single array list of type WeakArrayList the listener classes using hard links and the listeners as either hard or weak references. The WeakArrayList class is allocated lazily. This minimizes the footprint of the ListenerSupport class as long as no listeners have been added. For access to the listeners, you may use the getListenerIterator(java.lang.Class) method. It will return a static instance of EmptyIterator if no listeners of the desired type have been registered, minimizing allocation overhead. However, if matching listeners have been created, a small-footprint iterator class will be constructed, but this should be tolerable.

Author:

Heiko Erhardt

Nested Class Summary

class

ListenerSupport.ListenerIterator Convenience class that can serve as an empty Iterator.

Constructor Summary

ListenerSupport()
Default constructor.

Method Summary

void	addListener(java.lang.Class listenerClass, java.util.EventListener listener) Adds a listener to the list (using a regular hard reference).
void	addWeakListener(java.lang.Class listenerClass, java.util.EventListener listener) Adds a listener to the list (using a weak reference).
boolean	containsListener(java.lang.Class listenerClass, java.util.EventListener listener) Checks if the list contains a particular listener or listeners of a particular type.
boolean	containsListeners(java.lang.Class listenerClass) Checks if the list contains listeners of a particular type.
int	getListenerCount(java.lang.Class listenerClass) Gets the number of listeners of the specified type.
java.util.Iterator	getListenerIterator(java.lang.Class listenerClass) Gets an iterator over listeners of the specified type.
void	removeAllListeners(java.lang.Class listenerClass) Removes all listeners from the list.
void	removeListener(java.lang.Class listenerClass, java.util.EventListener listener) Removes a listener from the list.
void	trim() Removes 'dead' (i\.e\. garbage-collected) weak listeners from the list.

Methods inherited from class java.lang.Object

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

Constructor Detail

ListenerSupport

public ListenerSupport()

Default constructor.

Method Detail

addListener

public void addListener(java.lang.Class listenerClass,
                        java.util.EventListener listener)

Adds a listener to the list (using a regular hard reference). The method ensures that the same listener will not be added twice (comparing the listener objects using the == operation).

Parameters:

listenerClass - Listener class of the listener

listener - Listener to add

addWeakListener

public void addWeakListener(java.lang.Class listenerClass,
                            java.util.EventListener listener)

Adds a listener to the list (using a weak reference). The method ensures that the same listener will not be added twice (comparing the listener objects using the == operation).
Weak references may be garbage-collected if not referenced otherwise.
ATTENTION: Never add an automatic class (i. e new FocusListener () { ... }) or an inner class that is not referenced otherwise as a weak listener to the list. These objects will be cleared by the garbage collector during the next gc run!

Parameters:

listenerClass - Listener class of the listener

listener - Listener to add

removeListener

public void removeListener(java.lang.Class listenerClass,
                           java.util.EventListener listener)

Removes a listener from the list.

Parameters:

listenerClass - Listener class of the listener
If this parameter is null, all listener objects (regardless of the type) of the specified listener instance will be removed.

listener - Listener to remove
The listener may be either a hard or a weak listener.
If this parameter is null, all listeners of the specified class will be removed.
If both parameters are null, the method will clear the listener list.

removeAllListeners

public void removeAllListeners(java.lang.Class listenerClass)

Removes all listeners from the list.

Parameters:

listenerClass - Class of the listeners to remove.
If this parameter is null, the method will clear the listener list.

trim

public void trim()

Removes 'dead' (i\.e\. garbage-collected) weak listeners from the list.

containsListeners

public boolean containsListeners(java.lang.Class listenerClass)

Checks if the list contains listeners of a particular type. The method will consider only listeners that have not been garbage-collected.

Parameters:

listenerClass - Listener class to search for
If this parameter is null, the search will accept listeners of any class.

Returns:

true At least one matching listener has been found.
false The list contains no matching listeners or the listeners have been gc'ed.

containsListener

public boolean containsListener(java.lang.Class listenerClass,
                                java.util.EventListener listener)

Checks if the list contains a particular listener or listeners of a particular type. The method will consider only listeners that have not been garbage-collected.

Parameters:

listenerClass - Listener class to search for
If this parameter is null, the search will accept listeners of any class.

listener - Listener instance to search for
If this parameter is null, the search will consider the listener class only. If both parameters are null, the method will merely check if the list contains at least one valid listener reference.

Returns:

true At least one matching listener has been found.
false The list contains no matching listeners or the listeners have been gc'ed.

getListenerCount

public int getListenerCount(java.lang.Class listenerClass)

Gets the number of listeners of the specified type.

Parameters:

listenerClass - Listener class

Returns:

The number of registered listeners of this class

getListenerIterator

public java.util.Iterator getListenerIterator(java.lang.Class listenerClass)

Gets an iterator over listeners of the specified type.

Parameters:

listenerClass - Listener class

Returns:

An iterator of registered listeners of this class. The Iterator.next method of the returned iterator will return objects of type java.util.EventListener.
The method returns a static instance of EmptyIterator if no listeners of the desired type have been registered, minimizing allocation overhead. However, if matching listeners have been created, a small-footprint iterator class will be constructed, but this should be tolerable.
You should not call one of the methods addListener(java.lang.Class, java.util.EventListener), addWeakListener(java.lang.Class, java.util.EventListener) or trim() while iterating the listener list. The returned iterator will automatically perform a trim() operation after the Iterator.hasNext method returns false (i. e. the end of the list has been reached) and 'dead' listener references have been detected in order to keep the listener list clean.
Note that the returned iterator does not support the Iterator.remove method.