Author: oheger Date: Sun Apr 30 10:46:22 2006 New Revision: 398392 URL: http://svn.apache.org/viewcvs?rev=398392&view=rev Log: Added documentation about configuration events to the user guide
Added: jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml (with props) Modified: jakarta/commons/proper/configuration/trunk/xdocs/changes.xml jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml Modified: jakarta/commons/proper/configuration/trunk/xdocs/changes.xml URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/changes.xml?rev=398392&r1=398391&r2=398392&view=diff ============================================================================== --- jakarta/commons/proper/configuration/trunk/xdocs/changes.xml (original) +++ jakarta/commons/proper/configuration/trunk/xdocs/changes.xml Sun Apr 30 10:46:22 2006 @@ -32,6 +32,11 @@ The new class CombinedConfiguration was added as a hierarchical alternative to CompositeConfiguration. </action> + <action dev="oheger" type="add" issue="38929"> + Support for low-level configuration events was added to all classes + derived from AbstractConfiguration. The major part of this is handled + by the new super class EventSource of AbstractConfiguration. + </action> <action dev="oheger" type="add"> A new method convertToHierarchical() was added to ConfigurationUtils, which is able to convert an arbitrary configuration object into a Added: jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml?rev=398392&view=auto ============================================================================== --- jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml (added) +++ jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml Sun Apr 30 10:46:22 2006 @@ -0,0 +1,131 @@ +<?xml version="1.0"?> +<!-- + Copyright 2006 The Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> + +<document> + + <properties> + <title>Configuration Events Howto</title> + <author email="[EMAIL PROTECTED]">Oliver Heger</author> + </properties> + +<body> + <section name="Configuration Events"> + <p> + All configuration classes derived from + <code><a href="apidocs/org/apache/commons/configuration/AbstractConfiguration.html"> + AbstractConfiguration</a></code> allow to register event listeners, which + are notified whenever the configuration's data is changed. This provides + an easy means for tracking updates on a configuration. + </p> + + <subsection name="Configuration listeners"> + <p> + Objects that are interested in update events triggered by configurations + must implement the + <code><a href="apidocs/org/apache/commons/configuration/event/ConfigurationListener.html"> + ConfigurationListener</a></code> interface. This interface defines a + single method <code>configurationChanged()</code>, which is passed a + <code><a href="apidocs/org/apache/commons/configuration/event/ConfigurationEvent.html"> + ConfigurationEvent</a></code> object. The event object contains all + information available about the modification, including: + <ul> + <li>A source object, which is usually the configuration object that was + modified.</li> + <li>The event's type. This is a numeric value that corresponds to + constant declarations in concrete configuration classes. It describes + what exactly has happended.</li> + <li>If available, the name of the property whose modification caused the + event.</li> + <li>If available, the value of the property that caused this event.</li> + <li>A flag whether this event was generated before or after the update + of the source configuration. A modification of a configuration typically + causes two events: one event before and one event after the modification + is performed. This allows event listeners to react at the correct point + of time.</li> + </ul> + Depending on the event type not all of this data may be available. + </p> + <p> + For resolving the numeric event type use constants defined in + <code>AbstractConfiguration</code> or derived classes. These constants + start with the prefix <code>EVENT_</code> and have a speaking name. Here + is an incomplete list of available event types with the configuration + classes, in which they are defined: + </p> + <p> + <dl> + <dt>AbstractConfiguration</dt> + <dd>EVENT_ADD_PROPERTY (a property was added), EVENT_SET_PROPERTY + (a property's value was changed), EVENT_CLEAR_PROPERTY (a property was + removed from the configuration), EVENT_CLEAR (the configuration was + cleared)</dd> + <dt>AbstractFileConfiguration</dt> + <dd>EVENT_RELOAD (the configuration was reloaded)</dd> + <dt>HierarchicalConfiguration</dt> + <dd>EVENT_ADD_NODES (the <code>addNodes()</code> method was called), + EVENT_CLEAR_TREE (the <code>clearTree()</code> method was called)</dd> + </dl> + </p> + </subsection> + + <subsection name="An example"> + <p> + Implementing an event listener is quite easy. As an example we are going + to define an event listener, which logs all received configuration events + to the console. The class could look as follows: + </p> + <source><![CDATA[ +import org.apache.commons.configuration.event.ConfigurationEvent; +import org.apache.commons.configuration.event.ConfigurationListener; + +public class ConfigurationLogListener implements ConfigurationListener +{ + public void configurationChanged(ConfigurationEvent event) + { + if (!event.isBeforeUpdate()) + { + // only display events after the modification was done + System.out.println("Received event!"); + System.out.println("Type = " + event.getType()); + if (event.getPropertyName() != null) + { + System.out.println("Property name = " + event.getPropertyName()); + } + if (event.getPropertyValue() != null) + { + System.out.println("Property value = " + event.getPropertyValue()); + } + } + } +} +]]></source> + <p> + Now an instance of this event listener class has to be registered at a + configuration object: + </p> + <source><![CDATA[ +AbstractConfiguration config = ... // somehow create the configuration +ConfigurationListener listener = new ConfigurationLogListener(); +config.addConfigurationListener(listener); +... +config.addProperty("newProperty", "newValue"); // will fire an event +]]></source> + </subsection> + </section> +</body> + +</document> \ No newline at end of file Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml ------------------------------------------------------------------------------ svn:eol-style = native Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml ------------------------------------------------------------------------------ svn:keywords = Date Author Id Revision HeadURL Propchange: jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml ------------------------------------------------------------------------------ svn:mime-type = text/xml Modified: jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml?rev=398392&r1=398391&r2=398392&view=diff ============================================================================== --- jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml (original) +++ jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml Sun Apr 30 10:46:22 2006 @@ -114,6 +114,11 @@ <li><a href="howto_configurationbuilder.html#An example">An example</a></li> <li><a href="howto_configurationbuilder.html#Extending the configuration definition file format">Extending the configuration definition file format</a></li> </ul> + <li><a href="howto_events.html#Configuration Events">Configuration Events</a></li> + <ul> + <li><a href="howto_events.html#Configuration listeners">Configuration listeners</a></li> + <li><a href="howto_events.html#An example">An example</a></li> + </ul> </ul> </section> </body> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]