svn commit: r1620044 - /commons/proper/configuration/trunk/src/site/xdoc/userguide/upgradeto2_0.xml

[oh...@apache.org]

Author: oheger
Date: Sat Aug 23 16:15:34 2014
New Revision: 1620044

URL: http://svn.apache.org/r1620044
Log:
Added a section about the new event mechanism.

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

Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/upgradeto2_0.xml
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/upgradeto2_0.xml?rev=1620044&r1=1620043&r2=1620044&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/site/xdoc/userguide/upgradeto2_0.xml (original)
+++ commons/proper/configuration/trunk/src/site/xdoc/userguide/upgradeto2_0.xml Sat Aug 23 16:15:34 2014
@@ -54,6 +54,7 @@
         <li><a href="#Reloading">Reloading</a></li>
         <li><a href="#Combining_Configuration_Sources">Combining Configuration Sources</a></li>
         <li><a href="#Concurrency_Issues">Concurrency Issues</a></li>
+        <li><a href="#Events">Events</a></li>
       </ul>
     </p>
 
@@ -440,6 +441,64 @@ PropertiesConfiguration config = builder
       Concurrent Access</a> for a full description of this complex topic.
     </p>
     </subsection>
+
+    <subsection name="Events">
+    <p>
+      Another area in which major changes took place is the support for
+      <a href="howto_events.html">event notifications</a>. <em>Commons
+      Configuration</em> 1.x had two types of event listeners for configuration
+      update events and error events. Version 2.0 adds some more event sources -
+      events generated by configuration builders and reloading events. Despite
+      this increased number of event sources, there is now only a single event
+      listener interface
+      (<code><a href="../apidocs/org/apache/commons/configuration/event/EventListener.html">
+      EventListener</a></code>), and the mechanisms for adding and removing event
+      listeners are the same everywhere; the basic protocol is defined by the
+      <code><a href="../apidocs/org/apache/commons/configuration/event/EventSource.html">
+      EventSource</a></code> interface. (Note that <code>EventSource</code> used
+      to be a class in version 1.x; it actually was the base class of
+      <code>AbstractConfiguration</code> and therefore inherited by all concrete
+      configuration implementations. In version 2.0 this role has been taken
+      over by the <code><a href="../apidocs/org/apache/commons/configuration/event/BaseEventSource.html">
+      BaseEventSource</a></code> class.)
+    </p>
+    <p>
+      While the old version used numeric constants to define specific event types,
+      the new events are classified by instances of the
+      <code><a href="../apidocs/org/apache/commons/configuration/event/EventType.html">
+      EventType</a></code> class. Event types can be used to determine the
+      semantic meaning of an event, but also for filtering for specific events.
+      They stand in a logic hierarchical relation with each other; an event
+      listener that is registered for a base event type also receives notifications
+      for derived types. This makes a flexible and fine-grained event processing
+      possible. The whole event mechanism is very similar to the one implemented
+      in JavaFX.
+    </p>
+    <p>
+      The most basic use case for event listeners in version 1.x was probably
+      the registration of a change listener on a single configuration instance.
+      To achieve an equivalent effect with the new API, one would implement an
+      event listener and register it for the event type
+      <code><a href="../apidocs/org/apache/commons/configuration/event/ConfigurationEvent.html#ANY">
+      ConfigurationEvent.ANY</a></code>. This listener will then receive
+      notifications for all kinds of updates performed on the monitored
+      configuration. Structure and content of these events is nearly
+      identical to the counterparts in version 1.x.
+    </p>
+    <p>
+      There is, however, an important difference with the event listener
+      registration: The recommended way is to add the listener to the
+      <a href="#Creating_Configurations">configuration builder</a> which
+      creates the configuration rather than to the configuration itself. This
+      ensures that registration is done at the correct moment in time and also
+      updated when the builder decides to replace its managed configuration
+      instance.
+    </p>
+    <p>
+      All in all the new event mechanism should be much more flexible and
+      powerful than the old one.
+    </p>
+    </subsection>
   </section>
 </body>