Class EventSource
- Direct Known Subclasses:
AbstractConfiguration
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.
HierarchicalConfiguration
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.
For them a special listener interface exists:
ConfigurationErrorListener
. There is another set of
methods dealing with event listeners of this type. The
fireError()
method can be used by derived classes to send
notifications about errors to registered observers.
- Since:
- 1.3
- Version:
- $Id: EventSource.java 1234617 2012-01-22 21:31:01Z oheger $
- Author:
- Commons Configuration team
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
Adds a configuration listener to this object.void
Adds a new configuration error listener to this object.void
Removes all registered configuration listeners.void
Removes all registered error listeners.protected Object
clone()
Overrides theclone()
method to correctly handle so far registered event listeners.protected ConfigurationErrorEvent
createErrorEvent
(int type, String propName, Object propValue, Throwable ex) Creates aConfigurationErrorEvent
object based on the passed in parameters.protected ConfigurationEvent
createEvent
(int type, String propName, Object propValue, boolean before) Creates aConfigurationEvent
object based on the passed in parameters.protected void
Creates an error event object and delivers it to all registered error listeners.protected void
Creates an event object and delivers it to all registered event listeners.Returns a collection with all configuration event listeners that are currently registered at this object.Returns a collection with all configuration error listeners that are currently registered at this object.boolean
Returns a flag whether detail events are enabled.boolean
Removes the specified event listener so that it does not receive any further events caused by this object.boolean
Removes the specified error listener so that it does not receive any further events caused by this object.void
setDetailEvents
(boolean enable) Determines whether detail events should be generated.
-
Constructor Details
-
EventSource
public EventSource()Creates a new instance ofEventSource
.
-
-
Method Details
-
addConfigurationListener
Adds a configuration listener to this object.- Parameters:
l
- the listener to add
-
removeConfigurationListener
Removes the specified event listener so that it does not receive any further events caused by this object.- Parameters:
l
- the listener to be removed- Returns:
- a flag whether the event listener was found
-
getConfigurationListeners
Returns a collection with all configuration event listeners that are currently registered at this object.- Returns:
- a collection with the registered
ConfigurationListener
s (this collection is a snapshot of the currently registered listeners; manipulating it has no effect on this event source object)
-
clearConfigurationListeners
Removes all registered configuration listeners. -
isDetailEvents
Returns a flag whether detail events are enabled.- Returns:
- a flag if detail events are generated
-
setDetailEvents
Determines whether detail events should be generated. If enabled, some methods can generate multiple update events. Note that this method records the number of calls, i.e. if for instancesetDetailEvents(false)
was called three times, you will have to invoke the method as often to enable the details.- Parameters:
enable
- a flag if detail events should be enabled or disabled
-
addErrorListener
Adds a new configuration error listener to this object. This listener will then be notified about internal problems.- Parameters:
l
- the listener to register (must not be null)- Since:
- 1.4
-
removeErrorListener
Removes the specified error listener so that it does not receive any further events caused by this object.- Parameters:
l
- the listener to remove- Returns:
- a flag whether the listener could be found and removed
- Since:
- 1.4
-
clearErrorListeners
Removes all registered error listeners.- Since:
- 1.4
-
getErrorListeners
Returns a collection with all configuration error listeners that are currently registered at this object.- Returns:
- a collection with the registered
ConfigurationErrorListener
s (this collection is a snapshot of the currently registered listeners; it cannot be manipulated) - Since:
- 1.4
-
fireEvent
Creates an event object and delivers it to all registered event listeners. The method will check first if sending an event is allowed (making use of thedetailEvents
property), and if listeners are registered.- Parameters:
type
- 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 flag
-
createEvent
protected ConfigurationEvent createEvent(int type, String propName, Object propValue, boolean before) Creates aConfigurationEvent
object based on the passed in parameters. This is called byfireEvent()
if it decides that an event needs to be generated.- Parameters:
type
- 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 flag- Returns:
- the newly created event object
-
fireError
Creates an error event object and delivers it to all registered error listeners.- Parameters:
type
- the event's typepropName
- the name of the affected property (can be null)propValue
- the value of the affected property (can be null)ex
- theThrowable
object that caused this error event- Since:
- 1.4
-
createErrorEvent
protected ConfigurationErrorEvent createErrorEvent(int type, String propName, Object propValue, Throwable ex) Creates aConfigurationErrorEvent
object based on the passed in parameters. This is called byfireError()
if it decides that an event needs to be generated.- Parameters:
type
- the event's typepropName
- the name of the affected property (can be null)propValue
- the value of the affected property (can be null)ex
- theThrowable
object that caused this error event- Returns:
- the event object
- Since:
- 1.4
-
clone
Overrides theclone()
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 anEventSource
object will not be copied.- Overrides:
clone
in classObject
- Returns:
- the cloned object
- Throws:
CloneNotSupportedException
- if cloning is not allowed- Since:
- 1.4
-