com.jthreadkit
Class ListenerTool

java.lang.Object
  |
  +--com.jthreadkit.ListenerTool

All Implemented Interfaces:

AccessibleLock

public final class ListenerTool

extends Object

implements AccessibleLock

Used to manage listeners (or observers). A class that needs to have listeners added and removed can use a private instance of of ListenerTool to help manage the task.

The following example shows how an instance of ListenerTool can be used to manage listeners of the hypothetical type SomeListener:

public interface SomeListener { void messageReceived(String msg); }

This example also shows how to specify the object to lock on for synchronization--in this case: lockObject:

private ListenerTool listenerTool; // private member private Object lockObject; public //... // ... in some constructor ... // ... ListenerTool.Callback cb = new ListenerTool.Callback() { // When the notifyListeners method on ListenerTool // gets called, this method gets called once for // each registered listener. Note that the passed // parameters are explicitly cast into their known // types for this context, and then the private method // notifyOneListener on the enclosing class // is called with the appropriate types: public void notifyListener(Object lst, Object data) { notifyOneListener((SomeListener) lst, (String) data); } }; // Specify the lock to use so that the addListener, // removeListener, and notifyListeners methods on ListenerTool // synchronize on it before doing their work: listenerTool = new ListenerTool(cb, lockObject); // ... // ... the rest of some constructor ... } // During notification, this private method gets automatically // called once for each registered listener while the // object-level exclusive lock is held on lockObject. private void notifyOneListener(SomeListener listener, String msg) { listener.messageReceived(msg); } // Call this method with the message that you want to pass to each // of the registered listeners. During the entire notification process, // a lock is held on lockObject (specified during construction). private void notifyAllListeners(String msg) { listenerTool.notifyListeners(msg); } public void addSomeListener(SomeListener listener) { listenerTool.addListener(listener); } public void removeSomeListener(SomeListener listener) { listenerTool.removeListener(listener); }

This class is marked as final to prohibit subclasses. Instead of extending this class, an instance of it should be referred to by a member variable.

NOTE: This class is multithread-safe. All of the methods synchronize on the lock object returned by getLockObject() to control concurrency.

Inner Class Summary

static interface

ListenerTool.Callback Used to allow callbacks during notification.

Constructor Summary

ListenerTool(ListenerTool.Callback callback)
Creates a listener manager with the specified callback.

ListenerTool(ListenerTool.Callback callback, Object lock)
Creates a listener manager with the specified callback, lock object, no recursive notifications.

ListenerTool(ListenerTool.Callback callback, Object lock, boolean allowRecursiveNotification)
Creates a listener manager with the specified callback, lock object, and recursive notification option.

Method Summary

boolean	addListener(Object listener) Adds the specified listener to the list.
int	addListeners(Object[] listenerList) Adds all of the listeners to the current list.
int	getListenerCount() Returns the number of listeners currently registered.
Object	getLockObject() Returns the reference to the object that is synchronized on by other methods in the implementing class.
void	notifyListeners(Object data) Notifies each of the registered listeners passing the specified data to each one.
int	removeAllListeners() Removes all of the listeners in the list.
boolean	removeListener(Object listener) Removes the specified listener from the list.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

ListenerTool

public ListenerTool(ListenerTool.Callback callback,
                    Object lock,
                    boolean allowRecursiveNotification)

Creates a listener manager with the specified callback, lock object, and recursive notification option.

Parameters:

callback - the object to notify with each listener

lock - the alternative object to lock on during adding, removing, and notifications. If null is passed in, locking will occur on this instance.

allowRecursiveNotification - if false (most common case), recursive notifications will be squelched. If true, then notifyListeners can be called recursively.

ListenerTool

public ListenerTool(ListenerTool.Callback callback,
                    Object lock)

Creates a listener manager with the specified callback, lock object, no recursive notifications. Effectively does:

this(callback, lock, false);

See Also:

ListenerTool(ListenerTool.Callback, Object, boolean)

ListenerTool

public ListenerTool(ListenerTool.Callback callback)

Creates a listener manager with the specified callback. Effectively does:

this(callback, null, false);

See Also:

ListenerTool(ListenerTool.Callback, Object, boolean)

Method Detail

getLockObject

public Object getLockObject()

Description copied from interface: AccessibleLock

Returns the reference to the object that is synchronized on by other methods in the implementing class. This reference is not permitted to change after construction, so this method can be called once and the reference saved.

This reference can be used in synchronized blocks to keep other threads from sneaking in between methods calls like this:

obj = //... synchronized ( obj.getLockObject() ) { obj.methodA(); obj.methodB(); }

Specified by:

getLockObject in interface AccessibleLock

Following copied from interface: com.jthreadkit.AccessibleLock

Returns:

the object used to lock on to control concurrent access.

getListenerCount

public int getListenerCount()

Returns the number of listeners currently registered.

addListener

public boolean addListener(Object listener)

Adds the specified listener to the list. Duplicate listeners are ignored (determined by using == on the two object references).

Parameters:

listener - the listener to add to the current list.

Returns:

true if the listener was added, false if not added (this was a duplicate listener).

addListeners

public int addListeners(Object[] listenerList)

Adds all of the listeners to the current list. Duplicate listeners are silently ignore and not added.

Parameters:

listenerList - the listeners to add.

Returns:

the number of listeners actually added. This may be less than listenerList.length if there were any duplicates.

removeListener

public boolean removeListener(Object listener)

Removes the specified listener from the list. Requests to remove non-existent listeners are silently ignored.

Parameters:

listener - the listener to remove (using == comparisions to locate it).

Returns:

true if the listener was found and removed, false if the listener was not found in this list.

removeAllListeners

public int removeAllListeners()

Removes all of the listeners in the list.

Returns:

the number of listeners removed.

notifyListeners

public void notifyListeners(Object data)

Notifies each of the registered listeners passing the specified data to each one. During the entire notification duration, the lock is held (see getLockObject(). If you don't want to send any specific information to each listener you can pass in null for data.

The notifyListener(Object, Object) method on ListenerTool.Callback is invoked once for each listener.

If recursive notifications are not allowed (this is specified during construction), recursive calls are silently ignored. Although it is most common to prohibit the resursion, it can be enabled during construction (see this constructor). Note that only the thread already inside this method could re-enter it since it is holding the lock--other threads are blocked waiting to get exclusive access to the lock.

Parameters:

data - the message to pass to each listener. Can be null.

toString

public String toString()

Overrides:

toString in class Object