Return-Path: Delivered-To: apmail-jakarta-commons-dev-archive@www.apache.org Received: (qmail 699 invoked from network); 20 Jan 2007 18:55:40 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 20 Jan 2007 18:55:40 -0000 Received: (qmail 16690 invoked by uid 500); 20 Jan 2007 18:55:44 -0000 Delivered-To: apmail-jakarta-commons-dev-archive@jakarta.apache.org Received: (qmail 16624 invoked by uid 500); 20 Jan 2007 18:55:44 -0000 Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Help: List-Post: List-Id: "Jakarta Commons Developers List" Reply-To: "Jakarta Commons Developers List" Delivered-To: mailing list commons-dev@jakarta.apache.org Received: (qmail 16613 invoked by uid 500); 20 Jan 2007 18:55:44 -0000 Received: (qmail 16610 invoked by uid 99); 20 Jan 2007 18:55:44 -0000 Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 20 Jan 2007 10:55:44 -0800 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 20 Jan 2007 10:55:37 -0800 Received: by eris.apache.org (Postfix, from userid 65534) id 0D3CD1A981A; Sat, 20 Jan 2007 10:54:32 -0800 (PST) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r498153 - in /jakarta/commons/proper/configuration/trunk/xdocs: changes.xml howto_events.xml user_guide.xml Date: Sat, 20 Jan 2007 18:54:31 -0000 To: commons-cvs@jakarta.apache.org From: oheger@apache.org X-Mailer: svnmailer-1.1.0 Message-Id: <20070120185432.0D3CD1A981A@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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 @@ + + 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. + 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 ]]> + +

+ Some implementations of the Configuration interface operate + on underlying storages that can throw exceptions on each property access. + As an example consider + + DatabaseConfiguration: this configuration class issues an SQL + statement for each accessed property, which can potentially cause a + SQLException. +

+ In earlier versions of Commons Configuration 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 error + listeners. +

+ A configuration error listener is very similar to a regular configuration + event listener. Instead of the ConfigurationListener + interface it has to implement the + + ConfigurationErrorListener interface, which defines a single method + configurationError(). In case of an internal error this + method is invoked, and a + + ConfigurationErrorEvent with information about that error is + passed. By inheriting from ConfigurationEvent + ConfigurationErrorEvent 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 + isBefore() method does not really make sense for error + events because an error can only occur after something was done, so it + returns always false is this context). This data can + be used to find out when and where the error happened. In addition there + is the getCause() method that returns the Throwable + object, which generated this event (i.e. the causing exception). +

+ 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 ConfigurationLogListener class also + implement the ConfigurationErrorListener interface: +

+ +import org.apache.commons.configuration.event.ConfigurationEvent; +import org.apache.commons.configuration.event.ConfigurationListener; +import org.apache.commons.configuration.event.ConfigurationListener; + +public class ConfigurationLogListener + implements ConfigurationListener, ConfigurationErrorListener +{ + public void configurationChanged(ConfigurationEvent event) + { + // remains unchanged, see above + ... + } + + 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(); + } +} + +

+ Now the listener object has to be registered as an error listener, too. + For this purpose AbstractConfiguration provides the + addErrorListener() method. The following example fragment + shows the registration of the log listener object: +

+ +AbstractConfiguration config = ... // somehow create the configuration +ConfigurationListener listener = new ConfigurationLogListener(); +config.addConfigurationListener(listener); +config.addErrorListener((ConfigurationErrorListener) listener); +... +config.addProperty("newProperty", "newValue"); // will fire an event + +

+ Note: AbstractConfiguration already implements a mechanism + for writing internal errors to a logger object: It has the protected + addErrorLogListener() 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 + DatabaseConfiguration that are affected by potential internal + errors call this method during their initialization. So the default + behavior of Commons Configuration 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. +

+ 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 @@

--------------------------------------------------------------------- To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org For additional commands, e-mail: commons-dev-help@jakarta.apache.org