| java.lang.Object
 org.apache.commons.configuration.event.EventSource
All known Subclasses: org.apache.commons.configuration.AbstractConfiguration,
| EventSource | | public class EventSource (Code) | |
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 machanism. 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.
org.apache.commons.configuration.HierarchicalConfiguration 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.
author:
author:
href="http://jakarta.apache.org/commons/configuration/team-list.html">Commons
author:
Configuration team
version:
$Id: EventSource.java 495918 2007-01-13 16:33:02Z oheger $
since:
1.3 |
| Constructor Summary | |
| public | EventSource()
Creates a new instance of EventSource. |
| Method Summary | |
| public void | addConfigurationListener(ConfigurationListener l)
Adds a configuration listener to this object. | | public void | addErrorListener(ConfigurationErrorListener l)
Adds a new configuration error listener to this object. | | public void | clearConfigurationListeners()
Removes all registered configuration listeners. | | public void | clearErrorListeners()
Removes all registered error listeners. | | protected Object | clone()
Overrides the clone() method to correctly handle so far
registered event listeners. | | protected ConfigurationErrorEvent | createErrorEvent(int type, String propName, Object propValue, Throwable ex)
Creates a ConfigurationErrorEvent object based on the
passed in parameters. | | protected ConfigurationEvent | createEvent(int type, String propName, Object propValue, boolean before)
Creates a ConfigurationEvent object based on the passed in
parameters. | | protected void | fireError(int type, String propName, Object propValue, Throwable ex)
Creates an error event object and delivers it to all registered error
listeners. | | protected void | fireEvent(int type, String propName, Object propValue, boolean before)
Creates an event object and delivers it to all registered event
listeners. | | public Collection | getConfigurationListeners()
Returns a collection with all configuration event listeners that are
currently registered at this object. | | public Collection | getErrorListeners()
Returns a collection with all configuration error listeners that are
currently registered at this object. | | public boolean | isDetailEvents()
Returns a flag whether detail events are enabled. | | public boolean | removeConfigurationListener(ConfigurationListener l)
Removes the specified event listener so that it does not receive any
further events caused by this object. | | public boolean | removeErrorListener(ConfigurationErrorListener l)
Removes the specified error listener so that it does not receive any
further events caused by this object. | | public void | setDetailEvents(boolean enable)
Determines whether detail events should be generated. |
| EventSource | | public EventSource()(Code) | | Creates a new instance of EventSource.
|
| addConfigurationListener | | public void addConfigurationListener(ConfigurationListener l)(Code) | | Adds a configuration listener to this object.
Parameters:
l - the listener to add |
| addErrorListener | | public void addErrorListener(ConfigurationErrorListener l)(Code) | | 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 |
| clearConfigurationListeners | | public void clearConfigurationListeners()(Code) | | Removes all registered configuration listeners.
|
| clearErrorListeners | | public void clearErrorListeners()(Code) | | Removes all registered error listeners.
since:
1.4 |
| clone | | protected Object clone() throws CloneNotSupportedException(Code) | | Overrides the 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
EventSource object will not be copied.
the cloned object
throws:
CloneNotSupportedException - if cloning is not allowed
since:
1.4 |
| createErrorEvent | | protected ConfigurationErrorEvent createErrorEvent(int type, String propName, Object propValue, Throwable ex)(Code) | | Creates a ConfigurationErrorEvent object based on the
passed in parameters. This is called by fireError() if it
decides that an event needs to be generated.
Parameters:
type - the event's type
Parameters:
propName - the name of the affected property (can be null)
Parameters:
propValue - the value of the affected property (can be null)
Parameters:
ex - the Throwable object that caused this errorevent the event object
since:
1.4 |
| createEvent | | protected ConfigurationEvent createEvent(int type, String propName, Object propValue, boolean before)(Code) | | Creates a ConfigurationEvent object based on the passed in
parameters. This is called by fireEvent() if it decides
that an event needs to be generated.
Parameters:
type - the event's type
Parameters:
propName - the name of the affected property (can be null)
Parameters:
propValue - the value of the affected property (can be null)
Parameters:
before - the before update flag the newly created event object |
| fireError | | protected void fireError(int type, String propName, Object propValue, Throwable ex)(Code) | | Creates an error event object and delivers it to all registered error
listeners.
Parameters:
type - the event's type
Parameters:
propName - the name of the affected property (can be null)
Parameters:
propValue - the value of the affected property (can be null)
Parameters:
ex - the Throwable object that caused this errorevent
since:
1.4 |
| fireEvent | | protected void fireEvent(int type, String propName, Object propValue, boolean before)(Code) | | 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 the detailEvents property), and if
listeners are registered.
Parameters:
type - the event's type
Parameters:
propName - the name of the affected property (can be null)
Parameters:
propValue - the value of the affected property (can be null)
Parameters:
before - the before update flag |
| getConfigurationListeners | | public Collection getConfigurationListeners()(Code) | | Returns a collection with all configuration event listeners that are
currently registered at this object.
a collection with the registeredConfigurationListeners (this collection is a snapshotof the currently registered listeners; manipulating it has no effecton this event source object) |
| getErrorListeners | | public Collection getErrorListeners()(Code) | | Returns a collection with all configuration error listeners that are
currently registered at this object.
a collection with the registeredConfigurationErrorListeners (this collection is asnapshot of the currently registered listeners; it cannot be manipulated)
since:
1.4 |
| isDetailEvents | | public boolean isDetailEvents()(Code) | | Returns a flag whether detail events are enabled.
a flag if detail events are generated |
| removeConfigurationListener | | public boolean removeConfigurationListener(ConfigurationListener l)(Code) | | 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 a flag whether the event listener was found |
| removeErrorListener | | public boolean removeErrorListener(ConfigurationErrorListener l)(Code) | | Removes the specified error listener so that it does not receive any
further events caused by this object.
Parameters:
l - the listener to remove a flag whether the listener could be found and removed
since:
1.4 |
| setDetailEvents | | public void setDetailEvents(boolean enable)(Code) | | 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 instance
setDetailEvents(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 |
|
|