RELEASE-NOTES.txt

$Id$

                           Commons Configuration Package
                               Version 1.4
                               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 focus of release 1.4 lies in bug-fixing, but there are also some new
features. Some highlights are

- The support for variable interpolation has been improved.
- A new configuration class for windows ini files was added.
- In addition to configuration event listeners now so-called configuration
  error listeners are supported, which can be used to track internal errors.

A complete list of changes can be found below.

BUG FIXES IN 1.4
================
* [CONFIGURATION-227]
  The compatibility of ConfigurationDynaBean with other configuration types
  than those that inherit from BaseConfiguration was improved.

* [CONFIGURATION-228]
  Some of the methods of file-based hierarchical configurations (e.g. subset()
  or configurationAt()) did not take an eventually set reloading strategy into
  account. This is now fixed by overriding the internal fetchNodeList() method
  in AbstractHierarchicalFileConfiguration and letting it always check for a
  reload.

* [CONFIGURATION-229]
  For file-based configurations loaded by ConfigurationFactory the load()
  method was called before all of the properties specified by attributes of
  the XML element have been initialized. Now load() is called after property
  initialization.

* [CONFIGURATION-230]
  XPathExpressionEngine used to create wrong keys for attribute nodes. This
  caused some operations on XMLConfiguration to fail when such an expression
  engine was set (e.g. reloading). Now correct keys for attributes are
  constructed.

* [CONFIGURATION-233]
  The getList() method of CompositeConfiguration does now fully support
  variable interpolation. So it is possible to refer to a variable in one
  (sub) configuration that is defined in another configuration.

* [CONFIGURATION-235]
  Interpolation of non string values did not work when SubsetConfiguration
  was involved. This has now been fixed.

* [CONFIGURATION-240]
  File-based configurations with a reloading strategy did not work well
  together with CombinedConfiguration because the reloading strategy is only
  checked when its associated configuration is accessed (which does not happen
  when only the combined configuration is queried). As a workaround
  CombinedConfiguration now provides the boolean forceReloadCheck property.
  If this is set to true, all contained configurations will be triggered when
  a property is queried. This will cause a reload if necessary.

* [CONFIGURATION-241]
  CompositeConfiguration.clearProperty() now generates the correct update
  events.

* [CONFIGURATION-244]
  The number of dependencies needed for DefaultConfigurationBuilder was reduced
  by letting some of the default configuration providers resolve their classes
  per reflection.

* [CONFIGURATION-251]
  The dependency to xml-apis was changed to the version 1.0.b2. The so far
  used version 2.0.2 is reported to be bogus.

* [CONFIGURATION-252]
  ConfigurationUtils.getFile() now always checks first whether the passed in
  file name is absolute. If it is, this file will be returned. This prevents
  that on Unix under certain circumstances absolute file names are interpreted
  as relative ones.

* [CONFIGURATION-254]
  After cloning a XMLConfiguration there was still a connection to the original
  configuration. So when the clone was modified and then saved the content of
  the original configuration was written. This has now been fixed.

* [CONFIGURATION-255]
  DatabaseConfiguration now handles list delimiters in property values
  correctly.

* [CONFIGURATION-256]
  MapConfiguration and the web-based configurations now treat strings that
  contain an escaped list delimiter correctly: The escape character will be
  removed, so that for instance "foo\,bar" becomes "foo,bar".

IMPROVEMENTS IN 1.4
===================
* [CONFIGURATION-155]
  SubsetConfiguration and CompositeConfiguration were updated to fully support
  an instance specific list delimiter. Concerning splitting of string
  properties that contain a list delimiter character, these classes now
  behave like a "normal" configuration.

* [CONFIGURATION-192]
  Variable interpolation features have been improved. A variable can now have
  the form ${prefix:variableName} where the prefix defines the type of the
  variable. The standard types sys for system properties and const for
  constants are supported. Variables without a prefix are treated as references
  to other configuration properties (which is compatible to earlier versions).

* [CONFIGURATION-197]
  A new configuration class for windows ini files was added.

* [CONFIGURATION-236]
  HierarchicalConfiguration and some of its sub classes now define a copy
  constructor.

* [CONFIGURATUON-237]
  With ManagedReloadingStrategy a new reloading strategy for file-based
  configurations was added that can be triggered through JMX.

* [CONFIGURATION-243]
  Configuration declarations in the configuration definition file for
  DefaultConfigurationBuilder that are marked as optional now support a new
  attribute config-forceCreate. If this attribute is set to true and the
  initialization of the configuration fails, DefaultConfigurationBuilder
  tries to add an empty configuration of the correct type to the resulting
  combined configuration. Before this change optional configurations that
  caused errors were never added to the combined configuration.

* [CONFIGURATION-245]
  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. The new
  enableRuntimeExceptions() method of ConfigurationUtils registers a special
  error listener at the passed in configuration that generates a runtime
  exception when an error event is received.

CHANGES THAT MIGHT IMPACT EXISTING CODE:
========================================

* [CONFIGURATION-234]
  DefaultConfigurationBuilder now internally uses the standard expression
  engine for hierarchical configurations. So the dependency to Commons JXPath
  is no more needed when this class is used. Note that this change has some
  impact on exist ing code that manually sets properties before the combined
  configuration is created; this code must now be adapted to the changed
  syntax of property keys.

* [CONFIGURATION-242]
  The configuration returned by HierarchicalConfiguration.subset() performed
  variable interpolation only in the keys that belong to the subset. Now the
  parent configuration is searched, too, to resolve the value of the
  referenced property. This is consistent with the way SubnodeConfiguration
  works, but it slightly changes the behavior of interpolation for
  configurations that are loaded by DefaultConfigurationBuilder and are
  stored in the resulting CombinedConfiguration under a prefix. If a
  subset is fetched for this prefix, in version 1.3 variables could be
  resolved that belong to the same subset. This does not work any more in
  version 1.4

OTHER CHANGES
=============

* AbstractConfiguration now allows to set an instance specific logger using
  the setLogger() method. This gives clients more control over a
  configuration's logging behavior.

* Commons Configuration now depends on Commons Lang 2.2 minimum. Some features of
  Lang's new text package are used. The dependency in the pom was set to 2.3
  because this is the recent available version of Lang.

* The dependencies to Commons Collections and Commons Digester are updated to
  use the recent available version. However older versions will still work.

* A pom for maven 2 was added.

* Class loading in BeanHelper is now done using ClassUtils of Commons Lang.