$Id: RELEASE-NOTES.txt 1599092 2014-06-02 05:56:51Z ebourg $

   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.


                          Commons BeanUtils Package
                               Version 1.9.2
                               Release Notes

INTRODUCTION:
============

This document contains the release notes for this version of the Commons
BeanUtils package, and highlights changes since the previous version.

For more information on Commons BeanUtils, see
o http://commons.apache.org/beanutils/

Release 1.9.2 mainly addresses a potential security issue when accessing
properties in an uncontrolled way. In a nutshell, if an application that uses
Commons BeanUtils passes property paths from an external source directly to
the getProperty() method of BeanUtilsBean, an attacker can access the class
loader via the class property available on all Java objects.

In version 1.9.2 now a special BeanIntrospector class was added which allows
suppressing this property. Note that this BeanIntrospector is NOT enabled by
default! Commons BeanUtils is a low-level library, and on this layer it cannot
be decided whether access to a certain property is legal or not. Therefore,
an application has to activate this suppressing BeanIntrospector explicitly.
This can be done with the following lines of code:

BeanUtilsBean bub = new BeanUtilsBean();
bub.getPropertyUtils().addBeanIntrospector(
    SuppressPropertiesBeanIntrospector.SUPPRESS_CLASS);

Now all access to properties has to be done via the specially configured
BeanUtilsBean instance. More information about this issue can be found at
https://issues.apache.org/jira/browse/BEANUTILS-463 or in section 2.5 of the
user's guide.

BUGFIXES in version 1.9.2
=========================
* [BEANUTILS-458]
  BaseLocaleConverter.checkConversionResult() no longer throws a
  ConversionException if the result of a conversion is null.

New features in version 1.9.2
=============================
* [BEANUTILS-463]
  Added new SuppressPropertiesBeanIntrospector class to deal with a potential
  class loader vulnerability.

                        Release Notes for version 1.9.1

Release 1.9.1 is a bug fix release which addresses a problem with the new
feature of custom introspection introduced with release 1.9.0. It is fully
binary compatible with the previous release. The minimum required Java version
is 1.5.

BUGFIXES in version 1.9.1
=========================
* [BEANUTILS-456]
  For PropertyDescriptors obtained via custom introspection now additional
  information is stored to prevent that write methods are lost during
  garbage collection.

                        Release Notes for version 1.9.0

Release 1.9.0 contains some bug fixes and improvements that have accumulated
after the 1.8.3 release. The most obvious change is that the new version now
requires JDK 1.5 or higher, and that language features introduced with Java 5
(mainly generics) are used. A new feature has been introduced, too: the support
for customizing bean introspection.

Compatibility with 1.8.3
========================
Adding generics to the BeanUtils API has been done in a backwards compatible
way. This means that after type erasure the resulting classes look the same as
in the previous version. A drawback of this approach is that sometimes it is
not possible to use the logically correct type parameters because then
backwards compatibility would be broken. One example is the BeanMap class: The
class is now a Map<Object, Object> while its keys actually are strings.
However, implementing Map<String, Object> would change the signatures of some
methods in an incompatible way. More details about limitations of the
generification can be found at
https://issues.apache.org/jira/browse/BEANUTILS-452

One exception from the compatibility rule is the ResultSetIterator class which
now implements the Iterator<DynaBean> interface. This causes a change in the
return value of its next() method. ResultSetIterator is used internally as the
iterator implementation within ResultSetDynaClass (it is probably a mistake that
it is public). So chances are minimal that this change affects existing code.

Another change which may affect compatibility is [BEANUTILS-379] (details can
be found at https://issues.apache.org/jira/browse/BEANUTILS-379). Older
versions of BeanUtils contained some classes that were copied from Commons
Collections. These classes have now been removed, and a dependency to Commons
Collections has been added; the collections jar now has to be contained in the
classpath, too.

Except for the change on ResultSetIterator and the additional dependency to
Commons Collections, Commons BeanUtils 1.9.0 is fully binary compatible with
the previous version 1.8.3.

Changes on Converters
=====================
The convert() method in the Converter interface now uses a type parameter in
the following way:

    <T> T convert(Class<T> type, Object value);

This makes it possible to access the converter's result in a type-safe way.
Applying generics in this way revealed some inconsistencies in the Converter
implementations. There were situations in which converters could return a
result object of a different type as was requested. This was not a problem
before because the result type was just Object. Now the compiler complains if
a converter's result is not compatible with the desired target type.

Because of that Converter implementations have been made more strict. A
converter now checks the passed in target type, and if it cannot handle it,
throws a ConversionException. This prevents unexpected results and makes
converters more reliable (it could be considered a bug that a converter returns
a result object of a different data type as the passed in target type). In a
typical scenario, when converters are accessed via ConvertUtils, this change
should not cause any problems because the converters are only called for the
data types they have been registered for. But if converters are used directly,
they might now throw ConversionExceptions when they did not in a previous
version.

BUGFIXES in version 1.9.0
=========================
* [BEANUTILS-454]
  BeanUtilsBean.copyProperties() no longer throws a ConversionException for
  null properties of certain data types. This fixes a regression introduced in
  version 1.8.0. The issue is related to [BEANUTILS-387].
* [BEANUTILS-411]
  BeanUtilsBean.setProperty throws IllegalArgumentException if getter of nested
  property returns null.
* [BEANUTILS-408]
  MethodUtils.invokeMethod() throws NullPointerException when args==null.
* [BEANUTILS-426]
  ConstructorUtils.invokeConstructor(Class klass, Object arg) throws
  NullPointerException when arg==null.
* [BEANUTILS-380]
  BeanMap methods should initialize the root cause of exceptions that are
  thrown when running on JDK 1.4+.
* [BEANUTILS-379]
  Remove copied Collection classes.
* [BEANUTILS-378]
  BeanMap does not work in osgi (fixed by BEANUTILS-378).
* [BEANUTILS-381]
  MethodUtils getMatchingAccessibleMethod() does not correctly handle
  inheritance and method overloading.

New features in version 1.9.0
=============================
* [BEANUTILS-425]
  Support customization of introspection mechanism.
* [BEANUTILS-428]
  Provide a BeanIntrospector implementation which supports properties in a
  fluent API.
* [BEANUTILS-455]
  WrapDynaBeans can now be configured to use a specific instance of
  PropertyUtilsBean for introspection or property access.

Other changes in version 1.9.0
==============================
* [BEANUTILS-452]
  Add generics.
* [BEANUTILS-449]
  LocaleConverters do not take the target type into account.
* [BEANUTILS-448]
  LocaleConverters do not check their default value.
* [BEANUTILS-447]
  LazyDynaList.toArray() is not conform to the contract defined by the
  Collection interface.
* [BEANUTILS-446]
  Some of the converters ignore the passed in target type.
* [BEANUTILS-445]
  Converters can return an invalid result object if a default value is set.
* [BEANUTILS-441]
  Replace UnmodifiableSet.decorate with Collections.unModifiableSet.
* [BEANUTILS-436]
  Replace package.html with package-info.java.
* [BEANUTILS-438]
  Add @Deprecated and @Override Annotations.
* [BEANUTILS-437]
  Replace Date and Revision SVN keywords with Id.
* [BEANUTILS-431]
  Remove @author tags and move missing authors to pom.xml.
* [BEANUTILS-432]
  Switch to Java 1.5.
* [BEANUTILS-429]
  Delete trailing white spaces and white spaces on empty lines from all files.
* [BEANUTILS-427]
  Configure Checkstyle to check for trailing white spaces and white spaces on
  empty lines.


                        Release Notes for version 1.8.3

Compatibility with 1.8.2
========================
BeanUtils 1.8.3 is binary compatible release with Beanutils 1.8.2, containing only bug fixes.

BeanUtils 1.8.3 requires a minimum of JDK 1.3.

Memory Leak
===========
A memory leak was found in BeanUtils 1.7.0 (see BEANUTILS-291) which was fixed
in BeanUtils 1.8.0 for JDK 1.5+.

Testing of BeanUtils 1.8.1 revealed that the leak still appears to exist
in IBM's JDK 1.6 implementation.


see http://issues.apache.org/jira/browse/BEANUTILS-291
    http://issues.apache.org/jira/browse/BEANUTILS-366


BUGS FIXED:
===========

The following is a list of the bugs fixed in this release, with their Jira issue number:

  * [BEANUTILS-373] - MethodUtils is not thread safe because WeakFastHashMap which uses WeakHashMap is not thread-safe
  * [BEANUTILS-371] - Add constructors which have useColumnLabel parameter to ResultSetDynaClass and RowSetDynaClass

