Module io.github.mmm.event

Package io.github.mmm.event

Interface EventSource<E,L extends EventListener<?>>

Type Parameters:

E - the type of the events to send.

L - the type of the listeners.

All Known Implementing Classes:

AbstractEventBus.EventDispatcher, AbstractEventSender, AbstractEventSource

public interface EventSource<E,L extends EventListener<?>>

Interface for a source of events that allows to add and remove EventListeners.

Since:

1.0.0

Method Summary

Modifier and Type	Method	Description
default void	addListener(L listener)	Adds an EventListener which will be notified whenever the an event occurs (something changes).
void	addListener(L listener, boolean weak)	Adds an EventListener which will be notified whenever the an event occurs (something changes).
default void	addWeakListener(L listener)	Same as addListener(EventListener, boolean) with weak-flag set to true.
boolean	removeListener(L listener)	This method removes an EventListener.

Method Details

addListener

default void addListener(L listener)

Adds an EventListener which will be notified whenever the an event occurs (something changes). If the same listener is added more than once, it will be notified more than once. The same EventListener instance may be registered for different EventSources.

By default the EventSource stores a strong reference to the EventListener which will prevent the listener from being garbage collected. You then need to remove that EventListener after use to avoid memory leaks. For convenience your may also use addWeakListener(EventListener) instead to enforce that a WeakReference is used internally.

Parameters:

listener - the EventListener to register.

See Also:

• addListener(EventListener, boolean)
• removeListener(EventListener)
• EventListener.isMatchedUsingEquals()

addWeakListener

default void addWeakListener(L listener)

Same as addListener(EventListener, boolean) with weak-flag set to true.

Parameters:

listener - the EventListener to register.

See Also:

• addListener(EventListener, boolean)

addListener

void addListener(L listener,
 boolean weak)

Adds an EventListener which will be notified whenever the an event occurs (something changes). If the same listener is added more than once, it will be notified more than once. The same EventListener instance may be registered for different EventSources.

Parameters:

listener - the EventListener to register.

weak - - true if the EventListener may be garbage collected without being removed via a WeakReference, false otherwise (if the listener will be associated using a strong reference). When providing true here (use WeakReference), you need to store a reference to your registered EventListener yourself in the owning parent object so it is not garbage-collected too early.

See Also:

• addWeakListener(EventListener)

removeListener

boolean removeListener(L listener)

This method removes an EventListener. If the EventListener was not registered before this method does not do any change. Otherwise the first matching EventListener will be removed. So if you added an EventListener multiple times, only the first occurrence will be removed.
For performance reasons EventListener.isMatchedUsingEquals() returns false by default. To force the usage of equals instead, ensure your EventListener implementation overrides Object.equals(Object) and EventListener.isMatchedUsingEquals() returning true.

Parameters:

listener - is the EventListener to unregister.

Returns:

true if the given listener has successfully been removed, false if the listener was NOT registered.