com.virtuosotechnologies.lib.util
Class EventBroadcaster

java.lang.Object
  com.virtuosotechnologies.lib.util.EventBroadcaster

public final class EventBroadcaster

extends Object

A helper class for broadcasting events.

This class is meant to be used internally by any class that needs to broadcast events. It provides the following facilities:

• It manages a set of listeners, providing helper methods for adding and removing listeners.
• It optionally references listeners via weak references, so they can be garbage collected and do not need to be removed explicitly. Actually, it is recommended that all listeners should be weak.
• It provides methods for broadcasting an event to all listeners.

Typical usage will involve keeping a data member of type EventBroadcaster in your client class. Your add*Listener() and remove*Listener() methods can delegate to this helper, and you may use the helper's fireEvent() method to fire events.

This class is fully synchronized and thread-safe.

Constructor Summary

EventBroadcaster(Class listenerClass)
Constructor.

Method Summary

void	addListenerStrong(EventListener listener) Add a listener to the set of listeners.
void	addListenerWeak(EventListener listener) Add a listener to the set of listeners.
void	fireAbortableEvent(Method method, EventObject event) Fires an event.
void	fireAbortableEvent(String methodName, EventObject event) Fires an event.
void	fireEvent(Method method, EventObject event) Fires an event.
void	fireEvent(String methodName, EventObject event) Fires an event.
Class	getListenerClass() Returns the listener class associated with this broadcaster.
static Method	getListenerMethod(Class listenerClass, String name, Class eventClass) A helper for listener interfaces that want to provide static Method members for fast access to their methods.
List	getListenersAsList() Returns a copy of the set of listeners as a list.
Set	getListenersAsSet() Returns a copy of the set of listeners as a set.
static Method	getUniqueListenerMethod(Class listenerClass) A helper for listener interfaces that want to provide static Method members for fast access to their methods.
boolean	isVerbose() Get verbose mode (for debugging)
void	removeAllListeners() Removes all listeners from the set of listeners.
void	removeListener(EventListener listener) Removes a listener from the set of listeners.
void	setName(String name) Set identifying name that will be returned from toString (for debugging)
void	setVerbose(boolean verbose) Set verbose mode (for debugging)
String	toString() toString override.

Methods inherited from class java.lang.Object

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

Constructor Detail

EventBroadcaster

public EventBroadcaster(Class listenerClass)

Constructor.

Parameters:

listenerClass - the type of listener that will listen to this broadcaster. Normally, you should pass the class of the listener interface.

Method Detail

getListenerMethod

public static Method getListenerMethod(Class listenerClass,
                                       String name,
                                       Class eventClass)

A helper for listener interfaces that want to provide static Method members for fast access to their methods. This allows a listener interface to initialize a static member in a single line so a static initializer inner class is not needed.

Parameters:

listenerClass - class object for the listener

name - name of the method

eventClass - class of the event parameter.

Returns:

a Method object for the method

Throws:

ClassCastException - the listener wasn't an EventListener, or the event wasn't an EventObject.

IllegalArgumentException - no such method.

getUniqueListenerMethod

public static Method getUniqueListenerMethod(Class listenerClass)

A helper for listener interfaces that want to provide static Method members for fast access to their methods. This version assumes that the listener class declares exactly one method, and it returns that method.

Parameters:

listenerClass - class object for the listener

Returns:

a Method object for the method

Throws:

ClassCastException - the listener wasn't an EventListener, or the parameter taken by its unique method wasn't an EventObject.

IllegalArgumentException - no methods, or multiple methods, or the unique method took no parameters of multiple parameters.

isVerbose

public boolean isVerbose()

Get verbose mode (for debugging)

Returns:

true if the broadcaster is in verbose mode

setVerbose

public void setVerbose(boolean verbose)

Set verbose mode (for debugging)

Parameters:

verbose - verbose mode

setName

public void setName(String name)

Set identifying name that will be returned from toString (for debugging)

Parameters:

name - identifying name

toString

public String toString()

toString override. Returns the identifying name, if available.

getListenerClass

public Class getListenerClass()

Returns the listener class associated with this broadcaster.

Returns:

the listener class

addListenerWeak

public void addListenerWeak(EventListener listener)

Add a listener to the set of listeners. Has no effect if the listener is already in the set. References the new listener through a weak reference, which means the reference will go away when the listener gets collected. This has two implications:

• If the listener is going to get collected otherwise, you don't need to explicitly remove it from the listener list.
• You shouldn't add a listener weakly without storing a reference to it, or it might get collected prematurely. For example, the following is a no-no:

  addListenerWeak(new MyListener());

Parameters:

listener - a reference to the listener to add. It must be castable to the listener class associated with this broadcaster.

Throws:

ClassCastException - the listener isn't castable to the associated listener class

addListenerStrong

public void addListenerStrong(EventListener listener)

Add a listener to the set of listeners. Has no effect if the listener is already in the set. References the new listener through a strong reference, which means the reference will not be collected until the listener is explicitly removed.

Parameters:

listener - a reference to the listener to add. It must be castable to the listener class associated with this broadcaster.

Throws:

ClassCastException - the listener isn't castable to the associated listener class

removeListener

public void removeListener(EventListener listener)

Removes a listener from the set of listeners. Has no effect if the listener is not in the list.

Parameters:

listener - a reference to the listener to remove.

removeAllListeners

public void removeAllListeners()

Removes all listeners from the set of listeners.

getListenersAsSet

public Set getListenersAsSet()

Returns a copy of the set of listeners as a set. The copy is not backed by the original, so modifications made to the returned set do not affect the actual set of listeners.

Returns:

set of listeners.

getListenersAsList

public List getListenersAsList()

Returns a copy of the set of listeners as a list. The copy is not backed by the original, so modifications made to the returned list do not affect the actual set of listeners.

Returns:

list of listeners.

fireEvent

public void fireEvent(String methodName,
                      EventObject event)

Fires an event. This version takes the name of the method to invoke and an event object to send.

This version of fireEvent may be a little slow because it looks up the method object from the name and parameters via reflection. If an event is to be fired rapidly, you may want to create and cache the method object yourself, and call the other version of fireEvent() that takes a method object.

Parameters:

methodName - name of method to invoke

event - event object to send

Throws:

IllegalArgumentException - the given method was not found in the listener class, or it is not accessible because it is private or protected.

IllegalStateException - the method threw a checked exception.

fireEvent

public void fireEvent(Method method,
                      EventObject event)

Fires an event. This version takes a method object to invoke and an event object to send.

Parameters:

method - method to invoke

event - event object to send

Throws:

IllegalArgumentException - the given method is not accessible because it is private or protected.

IllegalStateException - the method threw a checked exception.

fireAbortableEvent

public void fireAbortableEvent(String methodName,
                               EventObject event)
                        throws EventAbortedException

Fires an event. This version takes the name of the method to invoke and an event object to send.

This version of fireEvent may be a little slow because it looks up the method object from the name and parameters via reflection. If an event is to be fired rapidly, you may want to create and cache the method object yourself, and call the other version of fireEvent() that takes a method object.

Parameters:

methodName - name of method to invoke

event - event object to send

Throws:

EventAbortedException - event aborted by a listener

IllegalArgumentException - the given method was not found in the listener class, or it is not accessible because it is private or protected.

IllegalStateException - the method threw a checked exception.

fireAbortableEvent

public void fireAbortableEvent(Method method,
                               EventObject event)
                        throws EventAbortedException

Fires an event. This version takes a method object to invoke and an event object to send.

Parameters:

method - method to invoke

event - event object to send

Throws:

EventAbortedException - event aborted by a listener

IllegalArgumentException - the given method is not accessible because it is private or protected.

IllegalStateException - the method threw a checked exception.