svn commit: r1612670 - in /commons/proper/configuration/trunk/src/site/xdoc/userguide: howto_events.xml user_guide.xml

[oh...@apache.org]

Author: oheger
Date: Tue Jul 22 20:01:59 2014
New Revision: 1612670

URL: http://svn.apache.org/r1612670
Log:
Reworked the example aboout a logging event listener.

Modified:
    commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_events.xml
    commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml

Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_events.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_events.xml?rev=1612670&r1=1612669&r2=1612670&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_events.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_events.xml Tue Jul 22 20:01:59 2014
@@ -175,7 +175,7 @@ config.addEventListener(ConfigurationEve
     </p>
     </subsection>
 
-    <subsection name="Configuration Events">
+    <subsection name="Configuration Update Events">
     <p>
       All configuration implementations derived from
       <code><a href="../apidocs/org/apache/commons/configuration/AbstractConfiguration.html">
@@ -247,27 +247,26 @@ config.addEventListener(ConfigurationEve
         </ul>
       </ul>
     </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:
+      After all the theory about the different event types, let's come to a
+      concrete example. Implementing an event listener for configuration
+      events is quite easy. To prove this and as a kind of "Hello world" use
+      case, 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;
+import org.apache.commons.configuration.event.EventListener;
 
-public class ConfigurationLogListener implements ConfigurationListener
+public class ConfigurationLogListener implements EventListener<ConfigurationEvent>
 {
-    public void configurationChanged(ConfigurationEvent event)
+    public void onEvent(ConfigurationEvent event)
     {
         if (!event.isBeforeUpdate())
         {
             // only display events after the modification was done
             System.out.println("Received event!");
-            System.out.println("Type = " + event.getType());
+            System.out.println("Type = " + event.getEventType());
             if (event.getPropertyName() != null)
             {
                 System.out.println("Property name = " + event.getPropertyName());
@@ -282,16 +281,33 @@ public class ConfigurationLogListener im
 ]]></source>
     <p>
       Now an instance of this event listener class has to be registered at a
-      configuration object:
+      configuration object (Note: in a later section we will learn how event
+      listeners can be added to configurations via their associated builders;
+      this is the preferred way):
     </p>
     <source><![CDATA[
 AbstractConfiguration config = ... // somehow create the configuration
-ConfigurationListener listener = new ConfigurationLogListener();
-config.addConfigurationListener(listener);
+EventListener<ConfigurationEvent> listener = new ConfigurationLogListener();
+config.addEventListener(ConfigurationEvent.ANY, listener);
 ...
 config.addProperty("newProperty", "newValue"); // will fire an event
 ]]></source>
+    <p>
+      Because our implementation is a very generic event listener it has been
+      registered for all kinds of configuration update events - the event type
+      <code>ConfigurationEvent.ANY</code> was used. Now consider the case that
+      we only want to log events about cleared properties. This can be easily
+      achieved - without having to modify the event listener implementation -
+      by just changing the registration code in the following way:
+    </p>
+    <source><![CDATA[
+config.addEventListener(ConfigurationEvent.CLEAR_PROPERTY, listener);
+...
+config.addProperty("newProperty", "newValue"); // will NOT fire an event
+config.clearProperty("removedProperty"); // but this one will
+]]></source>
     </subsection>
+
     <subsection name="Error listeners">
     <p>
       Some implementations of the <code>Configuration</code> interface operate

Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml?rev=1612670&r1=1612669&r2=1612670&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml Tue Jul 22 20:01:59 2014
@@ -158,7 +158,8 @@
       <li><a href="howto_events.html#Events">Events</a></li>
       <ul>
         <li><a href="howto_events.html#Event_Sources_and_Listeners">Event Sources and Listeners</a></li>
-        <li><a href="howto_events.html#An_example">An example</a></li>
+        <li><a href="howto_events.html#The_Hierarchy_of_Events">The Hierarchy of Events</a></li>
+        <li><a href="howto_events.html#Configuration_Update_Events">Configuration Update Events</a></li>
         <li><a href="howto_events.html#Error_listeners">Error listeners</a></li>
       </ul>
       <li><a href="howto_utilities.html#Utility_classes_and_Tips_and_Tricks">Utility classes and Tips and Tricks</a></li>