cz.cuni.amis.utils.listener
Class Listeners<Listener extends java.util.EventListener>

java.lang.Object
  cz.cuni.amis.utils.listener.Listeners<Listener>

public class Listeners<Listener extends java.util.EventListener>
extends java.lang.Object

This object is implementing listeners list, where you may store both type of references to the listeners (strong reference / weak reference).

It takes quite of effort to maintain the list with both strong / weak references, therefore the class was created.

Because we don't know what method we will be calling on the listeners the public interface ListenerNotifier exists. If you want to fire all the listeners, just implement this interface and stuff it to the notify() method of the "Listeners". (This somehow resembles the Stored Procedure pattern...)

Another interface is used for removing listeners. You may want to go through the listeners list and mark some of them to be removed (according to some rule like 'instanceof'). See static interface ListenerRemover.

The class is thread-safe.

Nested Class Summary

static class	Listeners.AdaptableListenerNotifier<LISTENER extends IListener>
static interface	Listeners.ListenerNotifier<Listener extends java.util.EventListener> Used to raise the event in the listeners.
static interface	Listeners.ListenerRemover Used as a visitor to the listeners that should tell which listeners to remove...

Constructor Summary

Listeners()

Method Summary

void	addStrongListener(Listener listener) Adds listener with strong reference to it.
void	addWeakListener(Listener listener) Adds listener with weak reference to it.
void	clearListeners()
int	count() Returns count of listners in the list, note that this may not be exact as we store also listeners with weak listeners, but the list will be purged in next opportunity (like raising event, removing listener).
boolean	isEqualListening(java.util.EventListener listener) Returns true if at least one equals listener to the param 'listener' is found.
boolean	isListening(java.util.EventListener listener) Returns true if at least one == listener to the param 'listener' is found.
void	notify(Listeners.ListenerNotifier<Listener> notifier) Calls notifier.notify() on each of the stored listeners, allowing you to execute stored command.
boolean	notifySafe(Listeners.ListenerNotifier<Listener> notifier, java.util.logging.Logger exceptionLog) Calls notifier.notify() on each of the stored listeners, allowing you to execute stored command.
void	remove(Listeners.ListenerRemover remover) This will iterate over all of the listeners and do the query "whether the listner should be removed from the Listeners object".
int	removeEqualListener(java.util.EventListener listener) Removes all listeners that are equal() to this one.
int	removeListener(java.util.EventListener listener) Removes all listeners that are == to this one (not equal()! must be the same object).

Methods inherited from class java.lang.Object

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

Constructor Detail

Listeners

public Listeners()

Method Detail

addStrongListener

public void addStrongListener(Listener listener)

Adds listener with strong reference to it.

Parameters:

listener -

addWeakListener

public void addWeakListener(Listener listener)

Adds listener with weak reference to it.

Parameters:

listener -

removeEqualListener

public int removeEqualListener(java.util.EventListener listener)

Removes all listeners that are equal() to this one.

Parameters:

listener -

Returns:

how many listeners were removed

removeListener

public int removeListener(java.util.EventListener listener)

Removes all listeners that are == to this one (not equal()! must be the same object).

Parameters:

listener -

Returns:

how many listeners were removed

notify

public void notify(Listeners.ListenerNotifier<Listener> notifier)

Calls notifier.notify() on each of the stored listeners, allowing you to execute stored command.

Parameters:

notifier -

notifySafe

public boolean notifySafe(Listeners.ListenerNotifier<Listener> notifier,
                          java.util.logging.Logger exceptionLog)

Calls notifier.notify() on each of the stored listeners, allowing you to execute stored command.

Every notification is run inside try/catch block, exceptions are reported into the log (if not null) and method returns false if some exception is thrown.

Parameters:

notifier -

exceptionLog - where to log exceptions, may be null

Returns:

true, if no exception happened

isEqualListening

public boolean isEqualListening(java.util.EventListener listener)

Returns true if at least one equals listener to the param 'listener' is found.

Parameters:

listener -

Returns:

isListening

public boolean isListening(java.util.EventListener listener)

Returns true if at least one == listener to the param 'listener' is found.

Not using equal() but pointer ==.

Parameters:

listener -

Returns:

clearListeners

public void clearListeners()

count

public int count()

Returns count of listners in the list, note that this may not be exact as we store also listeners with weak listeners, but the list will be purged in next opportunity (like raising event, removing listener).

NOT a constant-time operation. Because of the asynchronous nature of used queue, determining the current number of elements requires an O(n) traversal.

Returns:

remove

public void remove(Listeners.ListenerRemover remover)

This will iterate over all of the listeners and do the query "whether the listner should be removed from the Listeners object".

If 'remover' returns true to the listener, the listener is removed.

Parameters:

remover -