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:02:26 UTC
svn commit: r1612671 - in
/commons/proper/configuration/trunk/src/site/xdoc/userguide:
howto_events.xml user_guide.xml
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<Event></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>