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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]