xdocs/upgradeto2_1.xml - commons-lang - Git at Google

 <?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.0 to 2.1</title>
   <author email="dev@commons.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.0 to version 2.1.
 <source>
 INTRODUCTION:

 This document contains the release notes for the 2.1 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:

 - 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:

 - 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_*.


 NEW FEATURES:

 New:
 - Mutable package - contains basic classes that hold an Object or primitive
 and provide both get and set methods.
 - DurationFormatUtils - provides various methods for formatting durations
 - CharEncoding - definitions of constants for character encoding work
 - CharUtils - utilities for working with characters

 Updated:
 - ArrayUtils - many more methods, especially List-like methods
 - BooleanUtils - isTrue and isFalse methods that handle null
 - ClassUtils - primitive to wrapper class conversion methods
 - ClassUtils - class name comparator
 - IllegalClassException - extra constructor for common instanceof case
 - NotImplementedException - supports nested exceptions
 - ObjectUtils - hashcode method handling null
 - StringUtils - isAsciiPrintable to check the contents of a string
              -- ordinalIndexOf to find the nth index of a string
              -- various remove methods to remove parts of a string
              -- various split methods to provide more control over splitting a string
              -- defaultIfEmpty to default a string if null or empty
 - SystemUtils - methods to get system properties as File objects
              -- extra constants representing system properties
 - Validate - new methods to check whether all elements in a collection are of a specific type
 - WordUtils - new methods to capitalize based on a set of specified delimiters

 - EqualsBuilder - now provides setter to internal state
 - ToStringStyle - new style, short prefix style
 - ReflectionToStringBuilder - more flags to control the output with regards to statics

 - ExceptionUtils - added indexOfType methods that check subclasses, thus leaving the existing
 indexOfThrowable method untouched (see incompatible changes section)

 - NumberUtils - various string to number parsing methods added

 - DateUtils - methods added to compare dates in various ways
            -- method to parse a date string using multiple patterns
 - FastDateFormat - extra formatting methods that take in a millisecond long value
                 -- additional static factory methods
 - StopWatch - new methods for split behaviour


 BUG FIXES:

 19331  General case: infinite loop: ToStringBuilder.reflectionToString
 23174  EqualsBuilder.append(Object[], Object[]) throws NPE
 23356  Make DurationFormatUtils public!
 23557  WordUtils.capitalizeFully(String str) should take a delimiters
 23683  New method for converting a primitive Class to its corresponding wrapper
 23430  Minor javadoc fixes for StringUtils.contains(String, String)
 23590  make optional parameters in FastDateFormat really optional
 24056  Documentation error in StringUtils.replace
 25227  StringEscapeUtils.unescapeHtml() doesn't handle hex entities
 25454  new StringUtils.replaceChars behaves differently from old Ch
 25560  DateUtils.truncate() is off by one hour when using a date in DST switch 'zone'
 25627  DateUtils constants should be long
 25683  Add method that validates Collection elements are a correct
 25849  Add SystemUtils methods for directory properties.
 26616  ClassCastException in Enum.equals(Object)
 26699  Tokenizer Enhancements: reset input string, static CSV
 26734  NullPointerException in EqualsBuilder.append(Object[], Object[])
 26877  Add SystemUtils.AWT_TOOLKIT and others.
 26922  public static boolean DateUtils.equals(Date dt1, Date dt2)
 27592  WordUtils capitalize improvement
 27876  ReflectionToStringBuilder.toString(null) throws exception by design
 27877  Make ClassUtils methods null-safe and not throw an IAE.
 28468  StringUtils.defaultString: Documentation error
 28554  Add hashCode-support to class ObjectUtils
 29082  Enhancement of ExceptionUtils.CAUSE_METHOD_NAMES
 29149  StringEscapeUtils.unescapeHtml() doesn't handle an empty entity
 29294  lang.math.Fraction class deficiencies
 29673  ExceptionUtils: new getCause() methodname (for tomcat)
 29794  Add convenience format(long) methods to FastDateForma
 30328  HashCodeBuilder does not use the same values as Boolean (fixed as documentation)
 30334  New class proposal: CharacterEncoding
 30674  parseDate class from HttpClient's DateParser class
 30815  ArrayUtils.isEquals() throws ClassCastException when array1
 30929  Nestable.indexOfThrowable(Class)  uses Class.equals() to match
 31395  DateUtils.truncate oddity at the far end of the Date spectrum
 31478  Compile error with JDK 5 "enum" is a keyword
 31572  o.a.c.lang.enum.ValuedEnum: 'enum'is a keyword in JDK1.5.0
 31933  ToStringStyle setArrayEnd handled null incorrectly
 32133  SystemUtils fails init on HP-UX
 32198  Error in JavaDoc for StringUtils.chomp(String, String)
 32625  Can't subclass EqualsBuilder because isEquals is private
 33067  EqualsBuilder.append(Object[], Object[]) crashes with a NullPointerException if an element of the first array is null
 33069  EqualsBuilder.append(Object[], Object[]) incorrectly checks that rhs[i] is instance of lhs[i]'s class
 33574  unbalanced ReflectionToStringBuilder
 33737  ExceptionUtils.addCauseMethodName(String) does not check for duplicates.
 </source>
 </p>
 </section>

 </body>
 </document>
	<?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.0 to 2.1</title>
	<author email="dev@commons.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.0 to version 2.1.
	<source>
	INTRODUCTION:

	This document contains the release notes for the 2.1 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:

	- 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:

	- 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_*.


	NEW FEATURES:

	New:
	- Mutable package - contains basic classes that hold an Object or primitive
	and provide both get and set methods.
	- DurationFormatUtils - provides various methods for formatting durations
	- CharEncoding - definitions of constants for character encoding work
	- CharUtils - utilities for working with characters

	Updated:
	- ArrayUtils - many more methods, especially List-like methods
	- BooleanUtils - isTrue and isFalse methods that handle null
	- ClassUtils - primitive to wrapper class conversion methods
	- ClassUtils - class name comparator
	- IllegalClassException - extra constructor for common instanceof case
	- NotImplementedException - supports nested exceptions
	- ObjectUtils - hashcode method handling null
	- StringUtils - isAsciiPrintable to check the contents of a string
	-- ordinalIndexOf to find the nth index of a string
	-- various remove methods to remove parts of a string
	-- various split methods to provide more control over splitting a string
	-- defaultIfEmpty to default a string if null or empty
	- SystemUtils - methods to get system properties as File objects
	-- extra constants representing system properties
	- Validate - new methods to check whether all elements in a collection are of a specific type
	- WordUtils - new methods to capitalize based on a set of specified delimiters

	- EqualsBuilder - now provides setter to internal state
	- ToStringStyle - new style, short prefix style
	- ReflectionToStringBuilder - more flags to control the output with regards to statics

	- ExceptionUtils - added indexOfType methods that check subclasses, thus leaving the existing
	indexOfThrowable method untouched (see incompatible changes section)

	- NumberUtils - various string to number parsing methods added

	- DateUtils - methods added to compare dates in various ways
	-- method to parse a date string using multiple patterns
	- FastDateFormat - extra formatting methods that take in a millisecond long value
	-- additional static factory methods
	- StopWatch - new methods for split behaviour


	BUG FIXES:

	19331 General case: infinite loop: ToStringBuilder.reflectionToString
	23174 EqualsBuilder.append(Object[], Object[]) throws NPE
	23356 Make DurationFormatUtils public!
	23557 WordUtils.capitalizeFully(String str) should take a delimiters
	23683 New method for converting a primitive Class to its corresponding wrapper
	23430 Minor javadoc fixes for StringUtils.contains(String, String)
	23590 make optional parameters in FastDateFormat really optional
	24056 Documentation error in StringUtils.replace
	25227 StringEscapeUtils.unescapeHtml() doesn't handle hex entities
	25454 new StringUtils.replaceChars behaves differently from old Ch
	25560 DateUtils.truncate() is off by one hour when using a date in DST switch 'zone'
	25627 DateUtils constants should be long
	25683 Add method that validates Collection elements are a correct
	25849 Add SystemUtils methods for directory properties.
	26616 ClassCastException in Enum.equals(Object)
	26699 Tokenizer Enhancements: reset input string, static CSV
	26734 NullPointerException in EqualsBuilder.append(Object[], Object[])
	26877 Add SystemUtils.AWT_TOOLKIT and others.
	26922 public static boolean DateUtils.equals(Date dt1, Date dt2)
	27592 WordUtils capitalize improvement
	27876 ReflectionToStringBuilder.toString(null) throws exception by design
	27877 Make ClassUtils methods null-safe and not throw an IAE.
	28468 StringUtils.defaultString: Documentation error
	28554 Add hashCode-support to class ObjectUtils
	29082 Enhancement of ExceptionUtils.CAUSE_METHOD_NAMES
	29149 StringEscapeUtils.unescapeHtml() doesn't handle an empty entity
	29294 lang.math.Fraction class deficiencies
	29673 ExceptionUtils: new getCause() methodname (for tomcat)
	29794 Add convenience format(long) methods to FastDateForma
	30328 HashCodeBuilder does not use the same values as Boolean (fixed as documentation)
	30334 New class proposal: CharacterEncoding
	30674 parseDate class from HttpClient's DateParser class
	30815 ArrayUtils.isEquals() throws ClassCastException when array1
	30929 Nestable.indexOfThrowable(Class) uses Class.equals() to match
	31395 DateUtils.truncate oddity at the far end of the Date spectrum
	31478 Compile error with JDK 5 "enum" is a keyword
	31572 o.a.c.lang.enum.ValuedEnum: 'enum'is a keyword in JDK1.5.0
	31933 ToStringStyle setArrayEnd handled null incorrectly
	32133 SystemUtils fails init on HP-UX
	32198 Error in JavaDoc for StringUtils.chomp(String, String)
	32625 Can't subclass EqualsBuilder because isEquals is private
	33067 EqualsBuilder.append(Object[], Object[]) crashes with a NullPointerException if an element of the first array is null
	33069 EqualsBuilder.append(Object[], Object[]) incorrectly checks that rhs[i] is instance of lhs[i]'s class
	33574 unbalanced ReflectionToStringBuilder
	33737 ExceptionUtils.addCauseMethodName(String) does not check for duplicates.
	</source>
	</p>
	</section>

	</body>
	</document>