You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by oh...@apache.org on 2007/01/20 19:54:31 UTC
svn commit: r498153 - in /jakarta/commons/proper/configuration/trunk/xdocs:
changes.xml howto_events.xml user_guide.xml
Author: oheger
Date: Sat Jan 20 10:54:31 2007
New Revision: 498153
URL: http://svn.apache.org/viewvc?view=rev&rev=498153
Log:
CONFIGURATION-245: Updated user guide to cover the new error listener concept
Modified:
jakarta/commons/proper/configuration/trunk/xdocs/changes.xml
jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml
jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
Modified: jakarta/commons/proper/configuration/trunk/xdocs/changes.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/changes.xml?view=diff&rev=498153&r1=498152&r2=498153
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/changes.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/changes.xml Sat Jan 20 10:54:31 2007
@@ -23,6 +23,11 @@
<body>
<release version="1.4-dev" date="in SVN">
+ <action dev="oheger" type="add" issue="CONFIGURATION-245">
+ In addition to configuration event listeners now so-called configuration
+ error listeners are supported. These listeners are notified about
+ internal errors that had been logged and swallowed by privious versions.
+ </action>
<action dev="oheger" type="add">
AbstractConfiguration now allows to set an instance specific logger
using the setLogger() method. This gives clients more control over a
Modified: jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml?view=diff&rev=498153&r1=498152&r2=498153
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/howto_events.xml Sat Jan 20 10:54:31 2007
@@ -129,6 +129,102 @@
config.addProperty("newProperty", "newValue"); // will fire an event
]]></source>
</subsection>
+ <subsection name="Error listeners">
+ <p>
+ Some implementations of the <code>Configuration</code> interface operate
+ on underlying storages that can throw exceptions on each property access.
+ As an example consider <code>
+ <a href="apidocs/org/apache/commons/configuration/DatabaseConfiguration.html">
+ DatabaseConfiguration</a></code>: this configuration class issues an SQL
+ statement for each accessed property, which can potentially cause a
+ <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>.
+ </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
+ <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:
+ </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:
+ </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
+ 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
+ implement their own handling of such errors.
+ </p>
+ </subsection>
</section>
</body>
Modified: jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml?view=diff&rev=498153&r1=498152&r2=498153
==============================================================================
--- jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml (original)
+++ jakarta/commons/proper/configuration/trunk/xdocs/user_guide.xml Sat Jan 20 10:54:31 2007
@@ -134,6 +134,7 @@
<ul>
<li><a href="howto_events.html#Configuration_listeners">Configuration listeners</a></li>
<li><a href="howto_events.html#An_example">An example</a></li>
+ <li><a href="howto_events.html#Error_listeners">Error listeners</a></li>
</ul>
</ul>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org