public class BaseEventSource extends Object implements EventSource
A base class for objects that can generate configuration events.
This class implements functionality for managing a set of event listeners that can be notified when an event occurs.
It can be extended by configuration classes that support the event mechanism. In this case these classes only need to
call the fireEvent()
method when an event is to be delivered to the registered listeners.
Adding and removing event listeners can happen concurrently to manipulations on a configuration that cause events. The operations are synchronized.
With the detailEvents
property the number of detail events can be controlled. Some methods in configuration
classes are implemented in a way that they call other methods that can generate their own events. One example is the
setProperty()
method that can be implemented as a combination of clearProperty()
and
addProperty()
. With detailEvents
set to true, all involved methods will generate events (i.e.
listeners will receive property set events, property clear events, and property add events). If this mode is turned
off (which is the default), detail events are suppressed, so only property set events will be received. Note that the
number of received detail events may differ for different configuration implementations.
BaseHierarchicalConfiguration
for instance
has a custom implementation of setProperty()
, which does not generate any detail events.
In addition to "normal" events, error events are supported. Such events signal an internal problem that
occurred during access of properties. They are handled via the regular EventListener
interface, but there are
special event types defined by ConfigurationErrorEvent
. The fireError()
method can be used by derived
classes to send notifications about errors to registered observers.
Constructor and Description |
---|
BaseEventSource()
Creates a new instance of
BaseEventSource . |
Modifier and Type | Method and Description |
---|---|
<T extends Event> |
addEventListener(EventType<T> eventType,
EventListener<? super T> listener)
Adds an event listener for the specified event type.
|
void |
clearErrorListeners()
Removes all registered error listeners.
|
void |
clearEventListeners()
Removes all registered event listeners.
|
protected Object |
clone()
Overrides the
clone() method to correctly handle so far registered event listeners. |
void |
copyEventListeners(BaseEventSource source)
Copies all event listener registrations maintained by this object to the specified
BaseEventSource object. |
protected ConfigurationErrorEvent |
createErrorEvent(EventType<? extends ConfigurationErrorEvent> type,
EventType<?> opType,
String propName,
Object propValue,
Throwable ex)
Creates a
ConfigurationErrorEvent object based on the passed in parameters. |
protected <T extends ConfigurationEvent> |
createEvent(EventType<T> type,
String propName,
Object propValue,
boolean before)
Creates a
ConfigurationEvent object based on the passed in parameters. |
<T extends ConfigurationErrorEvent> |
fireError(EventType<T> eventType,
EventType<?> operationType,
String propertyName,
Object propertyValue,
Throwable cause)
Creates an error event object and delivers it to all registered error listeners of a matching type.
|
protected <T extends ConfigurationEvent> |
fireEvent(EventType<T> type,
String propName,
Object propValue,
boolean before)
Creates an event object and delivers it to all registered event listeners.
|
List<EventListenerRegistrationData<?>> |
getEventListenerRegistrations()
Returns a list with all
EventListenerRegistrationData objects currently contained for this event source. |
<T extends Event> |
getEventListeners(EventType<T> eventType)
Returns a collection with all event listeners of the specified event type that are currently registered at this
object.
|
boolean |
isDetailEvents()
Returns a flag whether detail events are enabled.
|
<T extends Event> |
removeEventListener(EventType<T> eventType,
EventListener<? super T> listener)
Removes the event listener registration for the given event type and listener.
|
void |
setDetailEvents(boolean enable)
Determines whether detail events should be generated.
|
public BaseEventSource()
BaseEventSource
.public <T extends Event> Collection<EventListener<? super T>> getEventListeners(EventType<T> eventType)
T
- the event typeeventType
- the event type objectpublic List<EventListenerRegistrationData<?>> getEventListenerRegistrations()
EventListenerRegistrationData
objects currently contained for this event source. This
method allows access to all registered event listeners, independent on their type.public boolean isDetailEvents()
public void setDetailEvents(boolean enable)
setDetailEvents(false)
was called
three times, you will have to invoke the method as often to enable the details.enable
- a flag if detail events should be enabled or disabledpublic <T extends Event> void addEventListener(EventType<T> eventType, EventListener<? super T> listener)
EventSource
addEventListener
in interface EventSource
T
- the type of events processed by this listenereventType
- the event type (must not be null)listener
- the listener to be registered (must not be null)public <T extends Event> boolean removeEventListener(EventType<T> eventType, EventListener<? super T> listener)
EventSource
removeEventListener
in interface EventSource
T
- the type of events processed by this listenereventType
- the event typelistener
- the event listener to be removedpublic void clearEventListeners()
public void clearErrorListeners()
public void copyEventListeners(BaseEventSource source)
BaseEventSource
object.source
- the target source for the copy operation (must not be null)IllegalArgumentException
- if the target source is nullprotected <T extends ConfigurationEvent> void fireEvent(EventType<T> type, String propName, Object propValue, boolean before)
detailEvents
property), and if listeners are registered.T
- the type of the event to be firedtype
- the event's typepropName
- the name of the affected property (can be null)propValue
- the value of the affected property (can be null)before
- the before update flagprotected <T extends ConfigurationEvent> ConfigurationEvent createEvent(EventType<T> type, String propName, Object propValue, boolean before)
ConfigurationEvent
object based on the passed in parameters. This method is called by
fireEvent()
if it decides that an event needs to be generated.T
- the type of the event to be createdtype
- the event's typepropName
- the name of the affected property (can be null)propValue
- the value of the affected property (can be null)before
- the before update flagpublic <T extends ConfigurationErrorEvent> void fireError(EventType<T> eventType, EventType<?> operationType, String propertyName, Object propertyValue, Throwable cause)
T
- the event typeeventType
- the event's typeoperationType
- the type of the failed operationpropertyName
- the name of the affected property (can be null)propertyValue
- the value of the affected property (can be null)cause
- the Throwable
object that caused this error eventprotected ConfigurationErrorEvent createErrorEvent(EventType<? extends ConfigurationErrorEvent> type, EventType<?> opType, String propName, Object propValue, Throwable ex)
ConfigurationErrorEvent
object based on the passed in parameters. This is called by
fireError()
if it decides that an event needs to be generated.type
- the event's typeopType
- the operation type related to this errorpropName
- the name of the affected property (can be null)propValue
- the value of the affected property (can be null)ex
- the Throwable
object that caused this error eventprotected Object clone() throws CloneNotSupportedException
clone()
method to correctly handle so far registered event listeners. This implementation
ensures that the clone will have empty event listener lists, i.e. the listeners registered at an
BaseEventSource
object will not be copied.clone
in class Object
CloneNotSupportedException
- if cloning is not allowedCopyright © 2001–2022 The Apache Software Foundation. All rights reserved.