commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r398392 - in /jakarta/commons/proper/configuration/trunk/xdocs: changes.xml howto_events.xml user_guide.xml
Date Sun, 30 Apr 2006 17:46:23 GMT
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="oheger@apache.org">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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message