$Id: RELEASE-NOTES.txt 593311 2007-11-08 21:06:42Z oheger $
Commons Configuration Package
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
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.
A bug in XMLConfiguration caused that attributes of the root element could
not be changed. This has been fixed.
The subset() method of HierarchicalConfiguration now takes the value of the
subset's root node into account if it is not ambigous.
Nodes added to a XMLConfiguration using the addNodes() method could lose
their value when the configuration was saved. This is now fixed.
The addNodes() method of hierarchical file-based configurations now correctly
triggers an auto save.
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.
ConfigurationUtils.convertToHierarchical() now correctly deals with property
values containing escaped list delimiters. This also affects
CombinedConfiguration when sub configurations with such property values are
The default expression engine used by HierarchicalConfiguration instances is
now lazily initialized. This avoids NullPointerExceptions in certain server
environments after a redeploy.
Cycles in the JNDI tree no longer cause a stack overflow in
Using file-based configurations in auto-save mode together with a reloading
strategy could cause data loss. This has been fixed.
A PropertiesConfiguration that was created from a non existing file lost its
content when it was saved. This problem has been solved.
AbstractConfiguration.addProperty() now correctly deals with list and array
properties if delimiter parsing is disabled.
PropertiesConfiguration now supports escaping the escape character for list
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.
List properties and properties containing interpolated variables are now
properly saved by INIConfiguration.
PropertiesConfiguration no longer escapes the list delimiter on saving if the
list delimiter has been disabled.
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.
INIConfiguration flushes the output at the end of a save operation.
XMLConfiguration used to drop attributes when an element's value was a list.
This has been fixed.
The return value of FileConfiguration.getFile() is now always consistent with
the result of getURL().
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
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.
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
DefaultConfigurationBuilder will now notify registered error listeners about
optional configuration sources that could not be created. Before exceptions
thrown by optional configurations were swallowed.
The base implementation of clear() in AbstractConfiguration now checks for a
potential UnsupportedOperationException when iterating over the existing
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.
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.
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.
Date objects are now supported in ASCII plist files.
File configurations can now be saved to FTP URLs, or any other URL protocol
supporting data output.
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()
ConfigurationInterpolator now also invokes the default lookup object for
variables with a prefix that could not be resolved by their associated lookup
* 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