RELEASE-NOTES.txt - commons-configuration - Git at Google

 $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.
	$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.