Return-Path: 
 <commits-return-42590-apmail-commons-commits-archive=commons.apache.org@commons.apache.org>
X-Original-To: apmail-commons-commits-archive@minotaur.apache.org
Delivered-To: apmail-commons-commits-archive@minotaur.apache.org
Received: from mail.apache.org (hermes.apache.org [140.211.11.3])
	by minotaur.apache.org (Postfix) with SMTP id BF43211562
	for <apmail-commons-commits-archive@minotaur.apache.org>;
 Tue, 22 Jul 2014 20:02:51 +0000 (UTC)
Received: (qmail 84672 invoked by uid 500); 22 Jul 2014 20:02:51 -0000
Delivered-To: apmail-commons-commits-archive@commons.apache.org
Received: (qmail 84599 invoked by uid 500); 22 Jul 2014 20:02:51 -0000
Mailing-List: contact commits-help@commons.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@commons.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@commons.apache.org>
List-Post: <mailto:commits@commons.apache.org>
List-Id: <commits.commons.apache.org>
Reply-To: dev@commons.apache.org
Delivered-To: mailing list commits@commons.apache.org
Received: (qmail 84587 invoked by uid 99); 22 Jul 2014 20:02:51 -0000
Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 22 Jul 2014 20:02:51 +0000
X-ASF-Spam-Status: No, hits=-2000.0 required=5.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 22 Jul 2014 20:02:51 +0000
Received: from eris.apache.org (localhost [127.0.0.1])
	by eris.apache.org (Postfix) with ESMTP id 5C9472388831;
	Tue, 22 Jul 2014 20:02:26 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
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 -0000
To: commits@commons.apache.org
From: oheger@apache.org
X-Mailer: svnmailer-1.0.9
Message-Id: <20140722200226.5C9472388831@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org

Author: oheger
Date: Tue Jul 22 20:02:25 2014
New Revision: 1612671

URL: http://svn.apache.org/r1612671
Log:
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/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=1612671&r1=1612670&r2=1612671&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:02:25 2014
@@ -206,7 +206,7 @@ config.addEventListener(ConfigurationEve
     </p>
     <p>
       <ul>
-        <li><strong>Event</strong></li>
+        <li><strong>Event.ANY</strong></li>
         <ul>
           <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");
 ]]></source>
     </subsection>
 
-    <subsection name="Error listeners">
+    <subsection name="Configuration Error Events">
     <p>
       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");
       <code>SQLException</code>.
     </p>
     <p>
-      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.
     </p>
     <p>
-      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 method
-      <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 the
+      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 type
+          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 indicating
+          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>
     </p>
-    <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>
-}
-</source>
     <p>
-      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.
     </p>
-    <source>
-AbstractConfiguration config = ... // somehow create the configuration
-ConfigurationListener listener = new ConfigurationLogListener();
-config.addConfigurationListener(listener);
-<b>config.addErrorListener((ConfigurationErrorListener) listener);</b>
-...
-config.addProperty("newProperty", "newValue"); // will fire an event
-</source>
     <p>
       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.
     </p>
     </subsection>

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=1612671&r1=1612670&r2=1612671&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:02:25 2014
@@ -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>
       </ul>
       <li><a href="howto_utilities.html#Utility_classes_and_Tips_and_Tricks">Utility classes and Tips and Tricks</a></li>
       <ul>