<?xml version="1.0"?>
<!--
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.
-->
<document>
 <properties>
  <title>Upgrade from 2.2 to 2.3</title>
  <author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
 </properties>
<body>

<section name="Upgrade">
<p>
These are the release notes and advice for upgrading Commons-Lang from
version 2.2 to version 2.3.
<source>
INTRODUCTION:

This document contains the release notes for the 2.3 version of Apache 
Jakarta Commons Lang.
Commons Lang is a set of utility functions and reusable components that
should be of use in any Java environment.

INCOMPATIBLE CHANGES WITH VERSION 2.2:

- Calling stop on a suspended StopWatch will no longer change the underlying time. 
  It's very unlikely anyone was relying on that bug as a feature.

ADDITIONAL INCOMPATIBLE CHANGES WITH VERSION 2.0:

- The Nestable interface defines the method indexOfThrowable(Class).
Previously the implementations checked only for a specific Class.
Now they check for subclasses of that Class as well.
For most situations this will be the expected behaviour (ie. its a bug fix).
If it causes problems, please use the ExceptionUtils.indexOfThrowable(Class) method instead.
Note that the ExceptionUtils method is available in v1.0 and v2.0 of commons-lang and has not been changed.
(An alternative to this is to change the public static matchSubclasses flag on NestableDelegate.
However, we don't recommend that as a long-term solution.)

- The StopWatch class has had much extra validation added.
If your code previously relied on unusual aspects, it may no longer work.

- Starting with version 2.1, Ant version 1.6.x is required to build. Copy 
junit.jar to ANT_HOME/lib. You can get JUnit from http://www.junit.org. See the developer's guide
for more details.

DEPRECATIONS FROM 2.2 to 2.3:

- None

DEPRECATIONS FROM 2.1 to 2.2:

- None

DEPRECATIONS FROM 2.0 to 2.1:

- The enum package has been renamed to enums for JDK1.5 compilance.
All functionality is identical, just the package has changed.
This package will be removed in v3.0.

- NumberUtils.stringToInt - renamed to toInt

- DateUtils - four constants, MILLIS_IN_* have been deprecated as they were defined
as int not long. The replacements are MILLIS_PER_*. 


BUG FIXES IN 2.3:

    * [LANG-69 ] - ToStringBuilder throws StackOverflowError when an Object cycle exists
    * [LANG-102] - Refactor Entities methods
    * [LANG-153] - Can't XMLDecode an Enum
    * [LANG-262] - Use of enum prevents a classloader from being garbage collected resuling in out of memory exceptions.
    * [LANG-279] - HashCodeBuilder throws java.lang.StackOverflowError when an object contains a cycle.
    * [LANG-281] - DurationFormatUtils returns wrong result
    * [LANG-286] - Serialization - not backwards compatible
    * [LANG-292] - unescapeXml("&amp;12345678;") should be "&amp;12345678;"
    * [LANG-294] - StrBuilder.replaceAll and StrBuilder.deleteAll can throw ArrayIndexOutOfBoundsException.
    * [LANG-295] - StrBuilder contains usages of thisBuf.length when they should use size
    * [LANG-299] - Bug in method appendFixedWidthPadRight of class StrBuilder causes an ArrayIndexOutOfBoundsException
    * [LANG-300] - NumberUtils.createNumber throws NumberFormatException for one digit long
    * [LANG-303] - FastDateFormat.mRules is not transient or serializable
    * [LANG-304] - NullPointerException in isAvailableLocale(Locale)
    * [LANG-313] - Wrong behavior of Entities.unescape
    * [LANG-315] - StopWatch: suspend() acts as split(), if followed by stop()

IMPROVEMENTS IN 2.3:

    * [LANG-258] - Enum JavaDoc
    * [LANG-266] - Wish for StringUtils.join(Collection, *)
    * [LANG-268] - StringUtils.join should allow you to pass a range for it (so it only joins a part of the array)
    * [LANG-275] - StringUtils substringsBetween
    * [LANG-282] - Create more tests to test out the +=31 replacement code in DurationFormatUtils.
    * [LANG-287] - Optimize StringEscapeUtils.unescapeXml(String)
    * [LANG-289] - NumberUtils.max(byte[]) and NumberUtils.min(byte[]) are missing
    * [LANG-291] - Null-safe comparison methods for finding most recent / least recent dates.
    * [LANG-306] - StrBuilder appendln/appendAll/appendSeparator
    * [LANG-310] - BooleanUtils isNotTrue/isNotFalse
    * [LANG-314] - Tests fail to pass when building with Maven 2

</source>
</p>
</section>

</body>
</document>