commons-commits mailing list archives

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

Reworked the subsection about error listeners.


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:02:25 2014
@@ -206,7 +206,7 @@ config.addEventListener(ConfigurationEve
-        <li><strong>Event</strong></li>
+        <li><strong>Event.ANY</strong></li>
           <li><strong>ConfigurationEvent.ANY</strong> is a placeholder
for all types
           of configuration update events. A listener registered for this
@@ -308,7 +308,7 @@ config.clearProperty("removedProperty");
-    <subsection name="Error listeners">
+    <subsection name="Configuration Error Events">
       Some implementations of the <code>Configuration</code> interface operate
       on underlying storages that can throw exceptions on each property access.
@@ -319,88 +319,73 @@ config.clearProperty("removedProperty");
-      In earlier versions of <em>Commons Configuration</em> such exceptions
-      were simply logged and then swallowed. So for clients it was impossible
-      to find out if something went wrong. From version 1.4 on there is a new
-      way of dealing with those internal errors: the concept of <em>error
-      listeners</em>.
+      Because the <code>Configuration</code> interface does not define checked
+      exceptions for the methods which access properties such exceptions
+      thrown from the underlying property store have to be handled somehow.
+      One way would be to re-throw them as runtime exceptions. This is
+      possible, a description how to enable this feature can be found in the
+      <a href="howto_utilities.html#Handling_of_runtime_exceptions">Tips and
+      Tricks</a> chapter. An alternative way of dealing with such exceptions is
+      to register an event listener for error events.
-      A configuration error listener is very similar to a regular configuration
-      event listener. Instead of the <code>ConfigurationListener</code>
-      interface it has to implement the
-      <code><a href="../apidocs/org/apache/commons/configuration/event/ConfigurationErrorListener.html">
-      ConfigurationErrorListener</a></code> interface, which defines a single
-      <code>configurationError()</code>. In case of an internal error this
-      method is invoked, and a
+      When a configuration implementation encounters an exception on accessing
+      its data it generates an event of class
       <code><a href="../apidocs/org/apache/commons/configuration/event/ConfigurationErrorEvent.html">
-      ConfigurationErrorEvent</a></code> with information about that error is
-      passed. By inheriting from <code>ConfigurationEvent</code>
-      <code>ConfigurationErrorEvent</code> supports all information that is
-      available for normal configuration listeners, too (e.g. the event type or
-      the property that was accessed when the problem occurred; note that the
-      <code>isBefore()</code> method does not really make sense for error
-      events because an error can only occur after something was done, so it
-      returns always <b>false</b> is this context). This data can
-      be used to find out when and where the error happened. In addition there
-      is the <code>getCause()</code> method that returns the <code>Throwable</code>
-      object, which generated this event (i.e. the causing exception).
-    </p>
-    <p>
-      We can now continue our example from the previous section and make our
-      example configuration listener also capable of tracing error events. To
-      achieve this we let the <code>ConfigurationLogListener</code> class also
-      implement the <code>ConfigurationErrorListener</code> interface:
+      ConfigurationErrorEvent</a></code>. This event class has similar properties
+      as <code><a href="../apidocs/org/apache/commons/configuration/event/ConfigurationEvent.html">
+      ConfigurationEvent</a></code>. Especially the name and the value of the
+      property which was accessed when the error occurred can be retrieved.
+      In addition, there is the <code>getCause()</code> method which returns
+      exception causing this event.
+    </p>
+    <p>
+      <code>ConfigurationErrorEvent</code> defines some new event type constants.
+      They build up the following hierarchy:
+      <ul>
+        <li><strong>Event.ANY</strong></li>
+        <ul>
+          <li><strong>ConfigurationErrorEvent.ANY</strong> The common super
+          of all error events. An event listener registered for this type can
+          be sure to be notified for all kind of error events.</li>
+          <li><strong>ConfigurationErrorEvent.READ</strong> A sub type
+          that the error occurred while reading a property.</li>
+          <li><strong>ConfigurationErrorEvent.WRITE</strong> A sub type
+          indicating that the error occured on an update operation. In this
+          case, an additional property of the event can be used to find out
+          which operation was performed: <code>errorOperationType</code>
+          returns an <code>EventType</code> object corresponding to the failed
+          update method (e.g. <em>ConfigurationEvent.ADD_PROPERTY</em> if a
+          property could not be added).</li>
+        </ul>
+      </ul>
-    <source>
-import org.apache.commons.configuration.event.ConfigurationEvent;
-import org.apache.commons.configuration.event.ConfigurationListener;
-<b>import org.apache.commons.configuration.event.ConfigurationListener;</b>
-public class ConfigurationLogListener
-  implements ConfigurationListener, <b>ConfigurationErrorListener</b>
-    public void configurationChanged(ConfigurationEvent event)
-    {
-      // remains unchanged, see above
-      ...
-    }
-    <b>public void configurationError(ConfigurationErrorEvent event)
-    {
-        System.out.println("An internal error occurred!");
-        // Log the standard properties of the configuration event
-        configurationChanged(event);
-        // Now log the exception
-        event.getCause().printStackTrace();
-    }</b>
-      Now the listener object has to be registered as an error listener, too.
-      For this purpose <code>AbstractConfiguration</code> provides the
-      <code>addErrorListener()</code> method. The following example fragment
-      shows the registration of the log listener object:
+      We could now continue the example from the previous section and make our
+      sample logging event listener also capable of tracing error events. 
+      However, this would not earn us that much. There is no principle difference
+      in the handling of configuration update events and error events;
+      therefore, there is nothing new to learn. If the logging functionality
+      should be implemented in a single listener class, the only tricky part is
+      that <code>ConfigurationEvent</code> and <code>ConfigurationErrorEvent</code>
+      do not stand in a super/extends relation with each other; they are both
+      derived from the type <em>Event.ANY</em>. So a generic logging listener
+      would have to be of type <code>EventListener&lt;Event&gt;</code>,
and it
+      would have to use the event's type to determine how to handle this
+      concrete event. Creating a separate event listener class for logging error
+      events is certainly easier.
-    <source>
-AbstractConfiguration config = ... // somehow create the configuration
-ConfigurationListener listener = new ConfigurationLogListener();
-<b>config.addErrorListener((ConfigurationErrorListener) listener);</b>
-config.addProperty("newProperty", "newValue"); // will fire an event
       Note: <code>AbstractConfiguration</code> already implements a mechanism
-      for writing internal errors to a logger object: It has the protected
-      <code>addErrorLogListener()</code> method that can be called by derived
+      for writing internal errors to a logger object: It has the
+      <code>addErrorLogListener()</code> method that can be called from derived
       classes to register a listener that will output all occurring internal
       errors using the default logger. Configuration implementations like
       <code>DatabaseConfiguration</code> that are affected by potential internal
       errors call this method during their initialization. So the default
-      behavior of <em>Commons Configuration</em> for these classes is not
-      changed: they still catch occurring exceptions and log them. However by
-      registering specific error listeners it is now possible for clients to
+      behavior of <em>Commons Configuration</em> for these classes is to
+      catch occurring exceptions and log them. However, by
+      registering specific error listeners it is possible for clients to
       implement their own handling of such errors.

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:02:25
@@ -160,7 +160,7 @@
         <li><a href="howto_events.html#Event_Sources_and_Listeners">Event Sources
and Listeners</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>
+        <li><a href="howto_events.html#Configuration_Error_Events">Configuration
Error 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