commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1612690 - in /commons/proper/configuration/trunk/src/site/xdoc/userguide: howto_events.xml user_guide.xml
Date Tue, 22 Jul 2014 20:12:10 GMT
Author: oheger
Date: Tue Jul 22 20:12:09 2014
New Revision: 1612690

Added a section about configuration builders and events.


Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_events.xml
--- 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:12:09 2014
@@ -389,7 +389,169 @@ config.clearProperty("removedProperty");
       implement their own handling of such errors.
-    </section>
+    <subsection name="Configuration Builders and Events">
+    <p>
+      <a href="howto_builders.html">Configuration builders</a> also offer
+      support for the event mechanism in <em>Commons Configuration</em>. There
+      are the following aspects:
+      <ul>
+        <li>Configuration builders can generate events themselves; for instance,
+        events are fired when a managed configuration is created or reset.</li>
+        <li>Configuration builders can be used to register event listeners at
+        managed configurations. Although it is possible to register event
+        listeners directly at a configuration object obtained from a builder,
+        this is not necessarily the best option. Consider for instance the case
+        that a <a href="howto_reloading.html">reloading configuration builder</a>
+        is used. When a need for a reload is detected the managed configuration
+        is replaced by a new instance. Event listener registrations directly
+        done at the old instance are no longer active. In contranst, for event
+        listener registrations done via the configuration builder, the builder
+        ensures that all listeners are automatically added to a newly created
+        configuration instance and removed from an obsolete instance.</li>
+      </ul>
+    </p>
+    <p>
+      For the events generated by a configuration builder a new event class is
+      introduced: <code><a href="../apidocs/org/apache/commons/configuration/builder/ConfigurationBuilderEvent.html">
+      ConfigurationBuilderEvent</a></code>. This class extends the base
+      <code><a href="../apidocs/org/apache/commons/configuration/event/Event.html">
+      Event</a></code> class, but does not define any new properties. However,
+      it overrides the <code>getSource()</code> method to return an instance
+      of <code><a href="../apidocs/org/apache/commons/configuration/builder/ConfigurationBuilder.html">
+      ConfigurationBuilder</a></code>. This event class is used to send
+      notifications which do not require additional information; the event itself
+      is sufficient to find out what has happened. Derived from
+      <code>ConfigurationBuilderEvent</code> is the
+      <code><a href="../apidocs/org/apache/commons/configuration/builder/ConfigurationBuilderResultCreatedEvent.html">
+      ConfigurationBuilderResultCreatedEvent</a></code> event class. It is used
+      to indicate that a new managed configuration object was created. A
+      reference to this object can be queried using the
+      <code>getConfiguration()</code> method.
+    </p>
+    <p>
+      The full hierarchy of event types related to configuration builders is
+      shown below. As usual, <code>EventType</code> constants are defined in
+      the event classes:
+      <ul>
+        <li>Event.ANY</li>
+        <ul>
+          <li><strong>ConfigurationBuilderEvent.ANY</strong> A common super
+          for all events produced by a configuration builder. An event listener
+          registered for this event type receives all notifications about a
+          configuration builder.</li>
+          <li><strong>ConfigurationBuilderEvent.RESET</strong> The managed
+          configuration of a builder has been reset. This means that the
+          configuration is now obsolete. A new object is created the next time
+          the builder's <code>getConfiguration()</code> method is called.</li>
+          <li><strong>ConfigurationBuilderEvent.CONFIGURATION_REQUEST</strong>
+          This event is generated when the builder's <code>getConfiguration()</code>
+          method is entered, but before the managed configuration is actually
+          accessed. This is an opportunity to perform some manipulations which
+          might also affect the managed configuration. One use case is to
+          trigger a reloading check at this point of time. If it turns out that
+          a reload is required, the managed configuration gets invalidated and
+          is replaced by a new object - which is then directly returned by
+          the current method call.</li>
+          <li><strong>ConfigurationBuilderResultCreatedEvent.RESULT_CREATED</strong>
+          A new managed configuration object has been created. This event is
+          fired initially on first invocation of the <code>getConfiguration()</code>
+          method, and then again after the managed configuration has been reset
+          and created anew. A reference to the new configuration object can be
+          obtained from the event so that specific initializations can be
+          performed.</li>
+        </ul>
+      </ul>
+    </p>
+    <p>
+      As an example of how to use event listeners for builders we are going to
+      make use of the <em>RESULT_CREATED</em> event time: every time a managed
+      configuration is created, a special property is set with the creation
+      date. This information can then be evaluated by client code. To achieve
+      this, a special event listener class is created:
+    </p>
+    <source><![CDATA[
+public class NewConfigurationInitListener
+    implements EventListener<ConfigurationBuilderResultCreatedEvent>
+    public void onEvent(ConfigurationBuilderResultCreatedEvent event)
+    {
+        event.getConfiguration().addProperty("creationDate", new Date());
+    }
+    <p>
+      This is pretty straight-forward. Now an instance of this listener class
+      has to be registered at the configuration builder in question. We can
+      directly use the method from the <code>EventSource</code> interface:
+    </p>
+    <source><![CDATA[
+ConfigurationBuilder<Configuration> builder = ...;
+    new NewConfigurationInitListener());
+    <p>
+      Now every time the builder creates a new managed configuration object,
+      the creation date is automatically stored in a property. This may be
+      indeed useful, for instance in a scenario supporting automatic reloads.
+      Here the application can determine when the configuration was updated
+      the last time.
+    </p>
+    <p>
+      All event listeners passed to a configuration builder's
+      <code>addEventListener()</code> method are not only registered at the
+      builder itself but are also propagated to the managed configuration
+      object. This is the recommended way of adding listeners for events
+      generated by the builder's managed configuration. The builder ensures that
+      - even if the configuration instance is replaced by another one - all
+      listeners are correctly registered and unregistered. In section
+      <a href="#Configuration_Update_Events">Configuration Update Events</a>
+      we created a simple configuration event listener which just logged
+      occuring update events. We can now show how this listener is
+      registered via the configuration builder:
+    </p>
+    <source><![CDATA[
+ConfigurationBuilder<Configuration> builder = ...;
+    new ConfigurationLogListener());
+    <p>
+      As can be seen, the same pattern is always used for all kind of event
+      listeners. Configuration builders offer a fluent API for setting up
+      builder objects and setting required initialization parameters. This
+      also includes the registration of event listeners. For this purpose the
+      <code><a href="../apidocs/org/apache/commons/configuration/builder/EventListenerParameters.html">
+      EventListenerParameters</a></code> has been created. It allows setting
+      arbitrary number of event listeners using method chaining. An instance
+      configured with the event listeners to be registered can then be passed
+      to the configuration builder's <code>configure()</code> method like
+      normal builder parameters objects. Here is an example how a configuration
+      builder for an XML configuration source can be constructed and initialized
+      - including an event listener - in a single expression:
+    </p>
+    <source><![CDATA[
+Parameters params = new Parameters();
+FileBasedConfigurationBuilder<Configuration> builder =
+    new FileBasedConfigurationBuilder<Configuration>(XMLConfiguration.class)
+    .configure(
+        // Regular builder initialization parameters
+        params.fileBased()
+            .setFile(new File("config.xml")),
+        // Event listener registration
+        new EventListenerParameters()
+            .addEventListener(ConfigurationEvent.ANY, new ConfigurationLogListener())
+     );
+Configuration config = builder.getConfiguration();
+    <p>
+      Here the feature is used that the <code>configure()</code> takes an
+      arbitrary number of initialization parameter objects.
+      <code>EventListenerParameters()</code> is a special parameters
+      implementation which takes care of event listener registrations, but does
+      not set any other initialization properties.
+    </p>
+    </subsection>
+  </section>
\ No newline at end of file

Modified: commons/proper/configuration/trunk/src/site/xdoc/userguide/user_guide.xml
--- 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:12:09
@@ -161,6 +161,7 @@
         <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#Configuration_Error_Events">Configuration
Error Events</a></li>
+        <li><a href="howto_events.html#Configuration_Builders_and_Events">Configuration
Builders and Events</a></li>
       <li><a href="howto_utilities.html#Utility_classes_and_Tips_and_Tricks">Utility
classes and Tips and Tricks</a></li>

View raw message