You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by oh...@apache.org on 2014/07/22 22:12:10 UTC
svn commit: r1612690 - in
/commons/proper/configuration/trunk/src/site/xdoc/userguide:
howto_events.xml user_guide.xml
Author: oheger
Date: Tue Jul 22 20:12:09 2014
New Revision: 1612690
URL: http://svn.apache.org/r1612690
Log:
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/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=1612690&r1=1612689&r2=1612690&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:12:09 2014
@@ -389,7 +389,169 @@ config.clearProperty("removedProperty");
implement their own handling of such errors.
</p>
</subsection>
- </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 type
+ 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());
+ }
+}
+]]></source>
+ <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 = ...;
+builder.addEventListener(ConfigurationBuilderResultCreatedEvent.RESULT_CREATED,
+ new NewConfigurationInitListener());
+]]></source>
+ <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 = ...;
+builder.addEventListener(ConfigurationEvent.ANY,
+ new ConfigurationLogListener());
+]]></source>
+ <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 an
+ 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();
+]]></source>
+ <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>
</body>
</document>
\ No newline at end of file
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=1612690&r1=1612689&r2=1612690&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:12:09 2014
@@ -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>
</ul>
<li><a href="howto_utilities.html#Utility_classes_and_Tips_and_Tricks">Utility classes and Tips and Tricks</a></li>
<ul>