$Id$ Commons Configuration Package Version 1.5 Release Notes INTRODUCTION ============ This document contains the release notes for this version of the Commons Configuration component, and highlights changes since the previous version. Commons Configuration provides a generic configuration interface which enables an application to read configuration data from a variety of sources. The 1.5 release contains numerous bug fixes. Most of the addressed bugs are not really critical. Some of them have been living in the code base for quite a while. In some cases (e.g. handling of list properties) the behavior of the involved methods has been made more consistent. There are also a few new features, e.g. a new Configuration class for accessing environment variables or support for registering DTD files when parsing XML files. Commons Configuration 1.5 is fully binary compatible to the previous version. Apart from the bug fixes existing code should not be impacted when switching from 1.4 to 1.5. A complete list of changes can be found below. BUG FIXES IN 1.5 ================ * [CONFIGURATION-299] Resolving of variables with the prefix const (constant fields) caused a ClassCastException under certain circumstances if non-String fields were involved. This has been fixed. * [CONFIGURATION-296] A bug in XMLConfiguration caused that attributes of the root element could not be changed. This has been fixed. * [CONFIGURATION-295] The subset() method of HierarchicalConfiguration now takes the value of the subset's root node into account if it is not ambigous. * [CONFIGURATION-294] Nodes added to a XMLConfiguration using the addNodes() method could lose their value when the configuration was saved. This is now fixed. * [CONFIGURATION-291] The addNodes() method of hierarchical file-based configurations now correctly triggers an auto save. * [CONFIGURATION-287] HierarchicalConfiguration.addNodes() now resets the reference property of all nodes to be added. This fixes a problem with XMLConfiguration, which now detects the added nodes as new and treats them correctly when the configuration is saved. * [CONFIGURATION-283] ConfigurationUtils.convertToHierarchical() now correctly deals with property values containing escaped list delimiters. This also affects CombinedConfiguration when sub configurations with such property values are contained. * [CONFIGURATION-282] The default expression engine used by HierarchicalConfiguration instances is now lazily initialized. This avoids NullPointerExceptions in certain server environments after a redeploy. * [CONFIGURATION-281] Cycles in the JNDI tree no longer cause a stack overflow in JNDIConfiguration. * [CONFIGURATION-280] Using file-based configurations in auto-save mode together with a reloading strategy could cause data loss. This has been fixed. * [CONFIGURATION-279] A PropertiesConfiguration that was created from a non existing file lost its content when it was saved. This problem has been solved. * [CONFIGURATION-275] AbstractConfiguration.addProperty() now correctly deals with list and array properties if delimiter parsing is disabled. * [CONFIGURATION-274] PropertiesConfiguration now supports escaping the escape character for list delimiters. * [CONFIGURATION-272] New copy() and append() methods have been added to AbstractConfiguration. They replace the methods with the same names in ConfigurationUtils, which do not handle all features of AbstractConfiguration properly (e.g. list delimiters in property values are incorrectly treated). To avoid such problems, the new methods should be used. * [CONFIGURATION-270] List properties and properties containing interpolated variables are now properly saved by INIConfiguration. * [CONFIGURATION-269] PropertiesConfiguration no longer escapes the list delimiter on saving if the list delimiter has been disabled. * [CONFIGURATION-268] When delimiter parsing was disabled for XMLConfiguration, saving and loading the configuration accidently added escape characters to properties containing the list delimiter character. This has been fixed. It is now also possible to escape the escape character itself. * [CONFIGURATION-267] INIConfiguration flushes the output at the end of a save operation. * [CONFIGURATION-263] XMLConfiguration used to drop attributes when an element's value was a list. This has been fixed. * [CONFIGURATION-253] The return value of FileConfiguration.getFile() is now always consistent with the result of getURL(). * [CONFIGURATION-180] Fixed a potential issue in DatabaseConfiguration where an error on closing a statement would prevent the connection from being closed. * byte[] properties are properly saved as data fields in the plist configurations (PropertyListConfiguration and XMLPropertyListConfiguration). IMPROVEMENTS IN 1.5 =================== * [CONFIGURATION-290] A new method registerEntityId() was added to XMLConfiguration, which allows to register URLs for entities. A new default implementation of the EntityResolver interface handles these entities automatically. * [CONFIGURATION-284] There is a new configuration implementation EnvironmentConfiguration, which provides access to (OS) environment variables. On Java >= 1.5 this class can be directly used; on earlier versions a dependency to ant is required. * [CONFIGURATION-285] DefaultConfigurationBuilder will now notify registered error listeners about optional configuration sources that could not be created. Before exceptions thrown by optional configurations were swallowed. * [CONFIGURATION-277] The base implementation of clear() in AbstractConfiguration now checks for a potential UnsupportedOperationException when iterating over the existing properties. * [CONFIGURATION-273] A new method interpolatedConfiguration() was added to AbstractConfiguration. This method returns a configuration with the same type and content as the original configuration, however all variables have been resolved. * [CONFIGURATION-265] For hierarchical file-based configurations the auto-save mechanism is now also triggered if a subnode configuration is changed. In such a case the new event type EVENT_SUBNODE_CHANGED will be sent to registered listeners. * [CONFIGURATION-264] A SubnodeConfiguration per default does not see certain changes of its parent configuration (e.g. reloads). With a new boolean parameter of HierarchicalConfiguration's configurationAt() method a mode can be enabled, in which the subnode configuration checks for such changes and reconstructs itself if necessary. * [CONFIGURATION-261] Date objects are now supported in ASCII plist files. * [CONFIGURATION-249] File configurations can now be saved to FTP URLs, or any other URL protocol supporting data output. * [CONFIGURATION-215] A new getSource() method was added to CompositeConfiguration and CombinedConfiguration, which returns the child configuration, in which a given property is defined. * DataConfiguration now supports java.net.InetAddress, javax.mail.internet.InternetAddress, and Java 5 enumeration types. Properties are converted to these types using the new generic getters. * Generic get methods have been added to DataConfiguration (get(), getArray() and getList()) OTHER CHANGES ============= * [CONFIGURATION-266] ConfigurationInterpolator now also invokes the default lookup object for variables with a prefix that could not be resolved by their associated lookup object. * INIConfiguration uses the platform's specific line separator instead of the Windows line separator. * Fixed INIConfiguration to handle the quoted values and the lines containing a value and a comment. * The object getters in DataConfiguration with no default value (i.e getURL(key)) now throw a NoSuchElementException if the flag throwExceptionOnMissing is set. * XMLPropertyListConfiguration no longer requires commons-digester and commons-beanutils to work. * The dependencies to commons-codec and commons-jxpath have been marked as optional. They are not required by the core classes. * The dependency to commons-logging was updated to the current version 1.1. Older versions of commons-logging will still work. * Some of the dependencies in the m2 pom have been updated to be more consistent.