$Id: RELEASE-NOTES.txt 1164914 2011-09-03 19:18:07Z oheger $ Commons Configuration Package Version 1.7 Release Notes INTRODUCTION ============ This document contains the release notes for this version of the Commons Configuration component, and highlights changes since the previous version. The Commons Configuration software library provides a generic configuration interface which enables an application to read configuration data from a variety of sources. It has been a while since the last release, therefore numerous bug fixes have accumulated. Most of them are not critical, but make the library more stable and consistent. There are also some new features, e.g. multi-tenant configurations, or improvements of DefaultConfigurationBuilder. With the new support for file systems a major weakness of earlier versions of Commons Configuration has been addressed: the algorithm for locating configuration files. Commons Configuration 1.7 is fully binary compatible to the previous version. Support for Java 1.3 has been dropped, a minimum of Java 1.4 is now required. There is one exception, however: Commons Configuration 1.7 supports optionally loading configuration files through Commons VFS (http://commons.apache.org/vfs/). VFS requires Java 1.5+, so if this feature is going to be used, a minimum JDK version of 1.5 is needed. More information about optional dependencies required by specific components of Commons Configuration can be found at http://commons.apache.org/configuration/dependencies.html. Following is a complete list of all changes in the new 1.7 release: BUG FIXES IN 1.7 ================ * [CONFIGURATION-460] Reloading now also works for configuration sources declared in the additional section of a configuration definition file for DefaultConfigurationBuilder. * [CONFIGURATION-445] Transforming a CombinedConfiguration with ViewNodes to an XMLConfiguration could cause problems with attributes. This has been fixed. * [CONFIGURATION-434] HierarchicalINIConfiguration now recognizes comment characters in property definitions only if they are preceded by whitespace. Thus comment characters can now be part of the property value. This is for instance required for the definition of file paths which use the semicolon as path separator. * [CONFIGURATION-433] Minor improvements of the support for indexed properties in ConfigurationDynaBean. * [CONFIGURATION-432] The methods getList() and getStringArray() of AbstractConfiguration can now handle single-valued properties of primitive types. * [CONFIGURATION-428] XMLConfiguration no longer escapes backslashs in the values of XML elements. * [CONFIGURATION-424] HierarchicalINIConfiguration now works correctly with configurations that contain only properties in the global section. * [CONFIGURATION-423] testFromClassPath() can fail when it should not because of inconsistent escaping of output from PropertiesConfiguration.getURL() and FileChangedReloadingStrategy.getFile().toURL(). * [CONFIGURATION-418] A bug related to the interpretation of escape sequences for backslashes has been fixed. The user guide has also been improved in this area. * [CONFIGURATION-415] Files with a plus character in their names are now handled correctly. * [CONFIGURATION-413] SubsetConfiguration now produces correct events. * [CONFIGURATION-409] HierarchicalINIConfiguration now correctly saves sections whose name contains delimiter characters. * [CONFIGURATION-407] Fixed a potential IllegalStateException in HierarchicalINIConfiguration that can be thrown when the global section is requested concurrently. * [CONFIGURATION-405] XMLPropertyListConfiguration no longer throws a ConfigurationException if the file to be loaded does not have an outer dict element. * [CONFIGURATION-404] The default expression engine used by hierarchical configurations used to throw a NumberFormatException if invalid indices were used in property keys. This has been fixed. As a side effect brackets can now be used in property keys. * [CONFIGURATION-403] When an empty XMLConfiguration was saved and reloaded the root element was assigned an empty text value. Because of this isEmpty() returned false for this configuration. This has been fixed. * [CONFIGURATION-397] Schema violation exceptions are now propagated back to the caller. * [CONFIGURATION-390] XMLConfiguration and CombinedConfiguraton are now synchronized to fix problems caused by reloading in a multithreaded environment. * [CONFIGURATION-396] HierarchicalConfiguration.NodeVisitor is now passed the correct key to its visitAfterChildren() method. * [CONFIGURATION-393] BaseConfiguration.clone() now also clones collections stored in the internal map. This causes list properties to be handled correctly. * [CONFIGURATION-388] Attribute or element values will not be escaped when attribute or element splitting are disabled. * [CONFIGURATION-385] DatabaseConfiguration now generates correct events for the clear() and clearProperty() methods. * [CONFIGURATION-369] SubsetConfiguration did not use locally registered lookups of its interpolator. * [CONFIGURATION-368] SubnodeConfiguration now fires an event of type EVENT_SUBNODE_CHANGED if a structural change of the parent configuration was detected. If the SubnodeConfiguration is contained in a CombinedConfiguration, the CombinedConfiguration receives this event and can update itself. * [CONFIGURATION-362] Empty dictionaries in a PropertyList configuration are now preserved when the configuration is saved. * [CONFIGURATION-361] MultiFileHierarchicalConfiguration was not using basepath to construct the file url. It also threw an exception if the file pattern resolved to a non-existent file. This is now configurable. * [CONFIGURATION-359] Fixed broken links to the API documentation in the user's guide. * [CONFIGURATION-357] The message of the ConversionException thrown by AbstractConfiguration.getBigInteger() is now correct. IMPROVEMENTS AND NEW FEATURES IN 1.7 ==================================== * [CONFIGURATION-458] HierarchicalConfiguration now provides a specific implementation of the clear() method. This is more efficient and also solves some other problems related to clearing a SubnodeConfiguration. * [CONFIGURATION-455] HierarchicalINIConfiguration.getSection() now creates a section if it does not exist. The SubnodeConfiguration returned by this method is now always connected to the parent ini configuration. * [CONFIGURATION-452] XPathExpressionEngine now provides better support for the setProperty() method. * [CONFIGURATION-448] The parsing of ini files has been improved for property definitions containing multiple separator characters. * [CONFIGURATION-447] DefaultConfigurationBuilder now supports including environment properties using the "env" tag. * [CONFIGURATION-446] XMLConfiguration now handles attributes correctly whose value is an empty string. * [CONFIGURATION-439] Child configuration builders created for a element in a configuration definition file now inherit the configuration and error listeners from the original DefaultConfigurationBuilder. This makes it possible to suppress log output created for optional configurations. * [CONFIGURATION-438] JNDIConfiguration.getKeys() no more logs an exception if the prefix does not exist. * [CONFIGURATION-437] Child configuration builders created for a element in a configuration definition file now inherit some of their properties from the builder object which processed the file. * [CONFIGURATION-412] DatabaseConfiguration can now be instructed to perform a commit after an update of the managed database table. This makes it usable in environments where the connections do not use auto-commit mode. * [CONFIGURATION-410] Added a refresh() method to AbstractFileConfiguration and AbstractHierarchicalFileConfiguration. * [CONFIGURATION-399] Default variable interpolation now supports the env: prefix for referencing environment variables. * [CONFIGURATION-389] DefaultConfigurationBuilder now supports defining ini files in its configuration definition file. * [CONFIGURATION-380] Add ExprLookup to allow expressions to be evaluated in configurations. When used, this requires that Apache Commons Jexl be added as a dependency to projects using Commons Configuration. * [CONFIGURATION-378] Added MergeCombiner to allow elements in two configurations to be merged when the element and attributes in the first file match those in the second file. * [CONFIGURATION-375, CONFIGURATION-376, CONFIGURATION-377] Align interpolation functionality of SubnodeConfiguration and SubsetConfiguration. SubsetConfiguration will now also interpolate keys of the parent configuration or use the local lookups of its parent. SubnodeConfiguration is in turn now able to lookup local keys as well. * [CONFIGURATION-374] MapConfiguration now provides a way of controlling the trimming behavior. * [CONFIGURATION-371] PropertiesConfigurationLayout now also stores the property separators used for the single properties. It is also possible to change them for specific properties or set a global properties separator. In earlier versions the separator was hard-coded to " = ". * [CONFIGURATION-370] PropertiesConfiguration now defines a nested interface IOFactory. Using this interface it is possible to inject custom PropertiesReader and PropertiesWriter implementations. * [CONFIGURATION-363] When using Commons Lang 2.6 or higher as dependency nested interpolation in variable names is supported. * [CONFIGURATION-356] Added getConfigurations and getConfigurationNameList. * [CONFIGURATION-340] File system access has been abstracted to a FileSystem interface. Two implementations are provided, DefaultFileSystem that behaves in a backward compatible manner and VFSFileSystem which uses Commons VFS to retreive and store files. * [CONFIGURATION-314] PropertiesConfigurationLayout now allows setting the line separator to be used when writing the properties file. * [CONFIGURATION-257, CONFIGURATION-355] Allow configurations to be validated using XML Schemas. OTHER CHANGES ============= * [CONFIGURATION-459] ConfigurationFactory has been deprecated. The user guide was updated to no more mention this class. * [CONFIGURATION-456] Improved Javadocs of getKeys(String) method for some configuration classes. * [CONFIGURATION-436] The optional dependency to Apache Ant has been changed to the new groupId org.apache.ant. The version was updated to the most recent version 1.8.2 (older versions should still work). * [CONFIGURATION-408] PropertiesConfiguration.save() escaped slashes in properties values. This was caused by a bug in commons-lang 2.4. Updating to a newer version of commons-lang fixed this problem. * [CONFIGURATION-358] Improvements of the user's guide for hierarchical configurations. * Dependencies to some other Commons components have been updated to use the most recent version. However, as none of the new features are used, the old versions will still work.