xref: /aosp_15_r20/external/apache-commons-lang/src/site/resources/release-notes/RELEASE-NOTES-3.3.txt (revision 455610af95f3bf5f4bc8a9eda520f57e389a4c42)

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.

=============================================================================

                           Apache Commons Lang
                               Version 3.3
                              Release Notes


INTRODUCTION:

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

For the advice on upgrading from 2.x to 3.x, see the following page:

    https://commons.apache.org/lang/article3_0.html

NEW FEATURES
==============

o LANG-955:  Add methods for removing all invalid characters according to
             XML 1.0 and XML 1.1 in an input string to StringEscapeUtils.
             Thanks to Adam Hooper.
o LANG-970:  Add APIs MutableBoolean setTrue() and setFalse()
o LANG-962:  Add SerializationUtils.roundtrip(T extends Serializable) to
             serialize then deserialize
o LANG-637:  There should be a DifferenceBuilder with a
             ReflectionDifferenceBuilder implementation
o LANG-944:  Add the Jaro-Winkler string distance algorithm to StringUtils.
             Thanks to Rekha Joshi.
o LANG-417:  New class ClassPathUtils with methods for turning FQN into
             resource path
o LANG-834:  Validate: add inclusiveBetween and exclusiveBetween overloads
             for primitive types
o LANG-900:  New RandomUtils class. Thanks to Duncan Jones.
o LANG-966:  Add IBM OS/400 detection

FIXED BUGS
============

o LANG-621:  ReflectionToStringBuilder.toString does not debug 3rd party object
             fields within 3rd party object. Thanks to Philip Hodges,
             Thomas Neidhart.
o LANG-977:  NumericEntityEscaper incorrectly encodes supplementary characters.
             Thanks to Chris Karcher.
o LANG-973:  Make some private fields final
o LANG-971:  NumberUtils#isNumber(String) fails to reject invalid Octal numbers
o LANG-972:  NumberUtils#isNumber does not allow for hex 0XABCD
o LANG-969:  StringUtils.toEncodedString(byte[], Charset) needlessly throws
             UnsupportedEncodingException. Thanks to Matt Bishop.
o LANG-946:  ConstantInitializerTest fails when building with IBM JDK 7
o LANG-954:  uncaught PatternSyntaxException in FastDateFormat on Android.
             Thanks to Michael Keppler.
o LANG-936:  StringUtils.getLevenshteinDistance with too big of a threshold
             returns wrong result. Thanks to Yaniv Kunda, Eli Lindsey.
o LANG-943:  Test DurationFormatUtilsTest.testEdgeDuration fails in
             JDK 1.6, 1.7 and 1.8, BRST time zone
o LANG-613:  ConstructorUtils.getAccessibleConstructor() Does Not Check the
             Accessibility of Enclosing Classes
o LANG-951:  Fragments are wrong by 1 day when using fragment YEAR or MONTH.
             Thanks to Sebastian Götz.
o LANG-950:  FastDateParser does not handle two digit year parsing like
             SimpleDateFormat
o LANG-949:  FastDateParserTest.testParses does not test FastDateParser
o LANG-915:  Wrong locale handling in LocaleUtils.toLocale().
             Thanks to Sergio Fernández.

CHANGES
=========

o LANG-961:  org.apache.commons.lang3.reflect.FieldUtils.removeFinalModifier(Field)
             does not clean up after itself
o LANG-958:  FastDateParser javadoc incorrectly states that SimpleDateFormat
            is used internally
o LANG-956:  Improve Javadoc of WordUtils.wrap methods
o LANG-939:  Move Documentation from user guide to package-info files
o LANG-953:  Convert package.html files to package-info.java files
o LANG-940:  Fix deprecation warnings
o LANG-819:  EnumUtils.generateBitVector needs a "? extends"

                        Release Notes for version 3.2.1

BUG FIXES
===========

o LANG-937:  Fix missing Hamcrest dependency in Ant Build
o LANG-941:  Test failure in LocaleUtilsTest when building with JDK 8
o LANG-942:  Test failure in FastDateParserTest and FastDateFormat_ParserTest
             when building with JDK8. Thanks to Bruno P. Kinoshita,
             Henri Yandell.
o LANG-938:  Build fails with test failures when building with JDK 8

                        Release Notes for version 3.2

COMPATIBILITY WITH 3.1
========================

This release introduces backwards incompatible changes in
org.apache.commons.lang3.time.FastDateFormat:
o Method 'protected java.util.List parsePattern()' has been removed
o Method 'protected java.lang.String parseToken(java.lang.String, int[])' has
  been removed
o Method 'protected org.apache.commons.lang3.time.FastDateFormat$NumberRule
  selectNumberRule(int, int)' has been removed

These changes were the result of [LANG-462]. It is assumed that this change
will not break clients as Charles Honton pointed out on 25/Jan/12:
"
 1. Methods "FastDateFormat$NumberRule selectNumberRule(int, int)" and
    "List<Rule> parsePattern()" couldn't have been overridden because
    NumberRule and Rule were private to FastDateFormat.
 2. Due to the factory pattern used, it's unlikely other two methods would have
    been overridden.
 3. The four methods are highly implementation specific. I consider it a
    mistake that the methods were exposed.
"
For more information see https://issues.apache.org/jira/browse/LANG-462.

NEW FEATURES
==============

o LANG-934:  Add removeFinalModifier to FieldUtils
o LANG-863:  Method returns number of inheritance hops between parent and
             subclass. Thanks to Daneel S. Yaitskov.
o LANG-774:  Added isStarted, isSuspended and isStopped to StopWatch.
             Thanks to Erhan Bagdemir.
o LANG-848:  Added StringUtils.isBlank/isEmpty CharSequence... methods.
             Thanks to Alexander Muthmann.
o LANG-926:  Added ArrayUtils.reverse(array, from, to) methods.
o LANG-795:  StringUtils.toString(byte[], String) deprecated in favour of a new
             StringUtils.toString(byte[], CharSet). Thanks to Aaron Digulla.
o LANG-893:  StrSubstitutor now supports default values for variables.
             Thanks to Woonsan Ko.
o LANG-913:  Adding .gitignore to commons-lang. Thanks to Allon Mureinik.
o LANG-837:  Add ObjectUtils.toIdentityString methods that support
             StringBuilder, StrBuilder, and Appendable.
o LANG-886:  Added CharSetUtils.containsAny(String, String).
o LANG-797:  Added escape/unescapeJson to StringEscapeUtils.
o LANG-875:  Added appendIfMissing and prependIfMissing methods to StringUtils.
o LANG-870:  Add StringUtils.LF and StringUtils.CR values.
o LANG-873:  Add FieldUtils getAllFields() to return all the fields defined in
             the given class and super classes.
o LANG-835:  StrBuilder should support StringBuilder as an input parameter.
o LANG-857:  StringIndexOutOfBoundsException in CharSequenceTranslator.
o LANG-856:  Code refactoring in NumberUtils.
o LANG-855:  NumberUtils#createBigInteger does not allow for hex and octal
             numbers.
o LANG-854:  NumberUtils#createNumber - does not allow for hex numbers to be
             larger than Long.
o LANG-853:  StringUtils join APIs for primitives.
o LANG-841:  Add StringUtils API to call String.replaceAll in DOTALL a.k.a.
             single-line mode.
o LANG-825:  Create StrBuilder APIs similar to
             String.format(String, Object...).
o LANG-675:  Add Triple class (ternary version of Pair).
o LANG-462:  FastDateFormat supports parse methods.

BUG FIXES
===========

o LANG-932:  Spelling fixes. Thanks to Ville Skyttä.
o LANG-929:  OctalUnescaper tried to parse all of \279.
o LANG-928:  OctalUnescaper had bugs when parsing octals starting with a zero.
o LANG-905:  EqualsBuilder returned true when comparing arrays, even when the
             elements are different.
o LANG-917:  Fixed exception when combining custom and choice format in
             ExtendedMessageFormat. Thanks to Arne Burmeister.
o LANG-902:  RandomStringUtils.random javadoc was incorrectly promising letters
             and numbers would, as opposed to may, appear  Issue:. Thanks to
             Andrzej Winnicki.
o LANG-921:  BooleanUtils.xor(boolean...) produces wrong results.
o LANG-896:  BooleanUtils.toBoolean(String str) javadoc is not updated. Thanks
             to Mark Bryan Yu.
o LANG-879:  LocaleUtils test fails with new Locale "ja_JP_JP_#u-ca-japanese"
             of JDK7.
o LANG-836:  StrSubstitutor does not support StringBuilder or CharSequence.
             Thanks to Arnaud Brunet.
o LANG-693:  Method createNumber from NumberUtils doesn't work for floating
             point numbers other than Float  Issue: LANG-693. Thanks to
             Calvin Echols.
o LANG-887:  FastDateFormat does not use the locale specific cache correctly.
o LANG-754:  ClassUtils.getShortName(String) will now only do a reverse lookup
             for array types.
o LANG-881:  NumberUtils.createNumber() Javadoc says it does not work for octal
             numbers.
o LANG-865:  LocaleUtils.toLocale does not parse strings starting with an
             underscore.
o LANG-858:  StringEscapeUtils.escapeJava() and escapeEcmaScript() do not
             output the escaped surrogate pairs that are Java parsable.
o LANG-849:  FastDateFormat and FastDatePrinter generates Date objects
             wastefully.
o LANG-845:  Spelling fixes.
o LANG-844:  Fix examples contained in javadoc of StringUtils.center methods.
o LANG-832:  FastDateParser does not handle unterminated quotes correctly.
o LANG-831:  FastDateParser does not handle white-space properly.
o LANG-830:  FastDateParser could use \Q \E to quote regexes.
o LANG-828:  FastDateParser does not handle non-Gregorian calendars properly.
o LANG-826:  FastDateParser does not handle non-ASCII digits correctly.
o LANG-822:  NumberUtils#createNumber - bad behavior for leading "--".
o LANG-818:  FastDateFormat's "z" pattern does not respect timezone of Calendar
             instances passed to format().
o LANG-817:  Add org.apache.commons.lang3.SystemUtils.IS_OS_WINDOWS_8.
o LANG-813:  StringUtils.equalsIgnoreCase doesn't check string reference
             equality.
o LANG-810:  StringUtils.join() endIndex, bugged for loop.
o LANG-807:  RandomStringUtils throws confusing IAE when end <= start.
o LANG-805:  RandomStringUtils.random(count, 0, 0, false, false, universe,
             random) always throws java.lang.ArrayIndexOutOfBoundsException.
o LANG-802:  LocaleUtils - unnecessary recursive call in SyncAvoid class.
o LANG-800:  Javadoc bug in DateUtils#ceiling for Calendar and Object versions.
o LANG-788:  SerializationUtils throws ClassNotFoundException when cloning
             primitive classes.
o LANG-786:  StringUtils equals() relies on undefined behavior.
o LANG-783:  Documentation bug: StringUtils.split.
o LANG-777:  jar contains velocity template of release notes.
o LANG-776:  TypeUtilsTest contains incorrect type assignability assertion.
o LANG-775:  TypeUtils.getTypeArguments() misses type arguments for
             partially-assigned classes.
o LANG-773:  ImmutablePair doc contains nonsense text.
o LANG-772:  ClassUtils.PACKAGE_SEPARATOR Javadoc contains garbage text.
o LANG-765:  EventListenerSupport.ProxyInvocationHandler no longer defines
             serialVersionUID.
o LANG-764:  StrBuilder is now serializable.
o LANG-761:  Fix Javadoc Ant warnings.
o LANG-747:  NumberUtils does not handle Long Hex numbers.
o LANG-743:  Javadoc bug in static inner class DateIterator.

CHANGES
=========

o LANG-931:  Misleading Javadoc comment in StrBuilderReader class. Thanks
             to Christoph Schneegans.
o LANG-910:  StringUtils.normalizeSpace now handles non-breaking spaces
             (Unicode 00A0). Thanks to Timur Yarosh.
o LANG-804:  Redundant check for zero in HashCodeBuilder ctor. Thanks to
             Allon Mureinik.
o LANG-884:  Simplify FastDateFormat; eliminate boxing.
o LANG-882:  LookupTranslator now works with implementations of CharSequence
             other than String.
o LANG-846:  Provide CharSequenceUtils.regionMatches with a proper green
             implementation instead of inefficiently converting to Strings.
o LANG-839:  ArrayUtils removeElements methods use unnecessary HashSet.
o LANG-838:  ArrayUtils removeElements methods clone temporary index arrays
             unnecessarily.
o LANG-799:  DateUtils#parseDate uses default locale; add Locale support.
o LANG-798:  Use generics in SerializationUtils.

CHANGES WITHOUT TICKET
========================

o Fixed URLs in javadoc to point to new oracle.com pages


                        Release Notes for version 3.1

NEW FEATURES
==============

o LANG-801:  Add Conversion utility to convert between data types on byte level
o LANG-760:  Add API StringUtils.toString(byte[] input, String charsetName)
o LANG-756:  Add APIs ClassUtils.isPrimitiveWrapper(Class<?>) and
             isPrimitiveOrWrapper(Class<?>)
o LANG-695:  SystemUtils.IS_OS_UNIX doesn't recognize FreeBSD as a Unix system

BUG FIXES
===========

o LANG-749:  Incorrect Bundle-SymbolicName in Manifest
o LANG-746:  NumberUtils does not handle upper-case hex: 0X and -0X
o LANG-744:  StringUtils throws java.security.AccessControlException on Google
             App Engine
o LANG-741:  Ant build has wrong component.name
o LANG-698:  Document that the Mutable numbers don't work as expected with
             String.format

CHANGES
=========

o LANG-758:  Add an example with whitespace in StringUtils.defaultIfEmpty
o LANG-752:  Fix createLong() so it behaves like createInteger()
o LANG-751:  Include the actual type in the Validate.isInstance and
             isAssignableFrom exception messages
o LANG-748:  Deprecating chomp(String, String)
o LANG-736:  CharUtils static final array CHAR_STRING is not needed to compute
             CHAR_STRING_ARRAY


                        Release Notes for version 3.0

ADDITIONS
===========

o LANG-276:  MutableBigDecimal and MutableBigInteger.
o LANG-285:  Wish : method unaccent.
o LANG-358:  ObjectUtils.coalesce.
o LANG-386:  LeftOf/RightOfNumber in Range convenience methods necessary.
o LANG-435:  Add ClassUtils.isAssignable() variants with autoboxing.
o LANG-444:  StringUtils.emptyToNull.
o LANG-482:  Enhance StrSubstitutor to support nested ${var-${subvr}} expansion
o LANG-482:  StrSubstitutor now supports substitution in variable names.
o LANG-496:  A generic implementation of the Lazy initialization pattern.
o LANG-497:  Addition of ContextedException and ContextedRuntimeException.
o LANG-498:  Add StringEscapeUtils.escapeText() methods.
o LANG-499:  Add support for the handling of ExecutionExceptions.
o LANG-501:  Add support for background initialization.
o LANG-529:  Add a concurrent package.
o LANG-533:  Validate: support for validating blank strings.
o LANG-537:  Add ArrayUtils.toArray to create generic arrays.
o LANG-545:  Add ability to create a Future for a constant.
o LANG-546:  Add methods to Validate to check whether the index is valid for
             the array/list/string.
o LANG-553:  Add TypeUtils class to provide utility code for working with generic
             types.
o LANG-559:  Added isAssignableFrom and isInstanceOf validation methods.
o LANG-559:  Added validState validation method.
o LANG-560:  New TimedSemaphore class.
o LANG-582:  Provide an implementation of the ThreadFactory interface.
o LANG-588:  Create a basic Pair<L, R> class.
o LANG-594:  DateUtils equal & compare functions up to most significant field.
o LANG-601:  Add Builder Interface / Update Builders to Implement It.
o LANG-609:  Support lazy initialization using atomic variables
o LANG-610:  Extend exception handling in ConcurrentUtils to runtime exceptions.
o LANG-614:  StringUtils.endsWithAny method
o LANG-640:  Add normalizeSpace to StringUtils
o LANG-644:  Provide documentation about the new concurrent package
o LANG-649:  BooleanUtils.toBooleanObject to support single character input
o LANG-651:  Add AnnotationUtils
o LANG-653:  Provide a very basic ConcurrentInitializer implementation
o LANG-655:  Add StringUtils.defaultIfBlank()
o LANG-667:  Add a Null-safe compare() method to ObjectUtils
o LANG-676:  Documented potential NPE if auto-boxing occurs for some BooleanUtils
             methods
o LANG-678:  Add support for ConcurrentMap.putIfAbsent()
o LANG-692:  Add hashCodeMulti varargs method
o LANG-697:  Add FormattableUtils class
o LANG-684:  Levenshtein Distance Within a Given Threshold

REMOVALS
==========

o LANG-438:  Remove @deprecateds.
o LANG-492:  Remove code handled now by the JDK.
o LANG-493:  Remove code that does not hold enough value to remain.
o LANG-590:  Remove JDK 1.2/1.3 bug handling in
             StringUtils.indexOf(String, String, int).
o LANG-673:  WordUtils.abbreviate() removed
o LANG-691:  Removed DateUtils.UTC_TIME_ZONE

IMPROVEMENTS
==============

o LANG-290:  EnumUtils for JDK 5.0.
o LANG-336:  Finally start using generics.
o LANG-355:  StrBuilder should implement CharSequence and Appendable.
o LANG-396:  Investigate for vararg usages.
o LANG-424:  Improve Javadoc for StringUtils class.
o LANG-458:  Refactor Validate.java to eliminate code redundancy.
o LANG-479:  Document where in SVN trunk is.
o LANG-504:  bring ArrayUtils.isEmpty to the generics world.
o LANG-505:  Rewrite StringEscapeUtils.
o LANG-507:  StringEscapeUtils.unescapeJava should support \u+ notation.
o LANG-510:  Convert StringUtils API to take CharSequence.
o LANG-513:  Better EnumUtils.
o LANG-528:  Mutable classes should implement an appropriately typed Mutable
             interface.
o LANG-539:  Compile commons.lang for CDC 1.1/Foundation 1.1.
o LANG-540:  Make NumericEntityEscaper immutable.
o LANG-541:  Replace StringBuffer with StringBuilder.
o LANG-548:  Use Iterable on API instead of Collection.
o LANG-551:  Replace Range classes with generic version.
o LANG-562:  Change Maven groupId.
o LANG-563:  Change Java package name.
o LANG-570:  Do the test cases really still require main() and suite() methods?
o LANG-579:  Add new Validate methods.
o LANG-599:  ClassUtils.getClass(): Allow Dots as Inner Class Separators.
o LANG-605:  DefaultExceptionContext overwrites values in recursive situations.
o LANG-668:  Change ObjectUtils min() & max() functions to use varargs rather
             than just two parameters
o LANG-681:  Push down WordUtils to "text" sub-package.
o LANG-711:  Add includeantruntime=false to javac targets to quell warnings in
             ant 1.8.1 and better (and modest performance gain).
o LANG-713:  Increase test coverage of FieldUtils read methods and tweak
             javadoc.
o LANG-718:  build.xml Java 1.5+ updates.

BUG FIXES
===========

o LANG-11:   Depend on JDK 1.5+.
o LANG-302:  StrBuilder does not implement clone().
o LANG-339:  StringEscapeUtils.escapeHtml() escapes multibyte characters like
             Chinese, Japanese, etc.
o LANG-369:  ExceptionUtils not thread-safe.
o LANG-418:  Javadoc incorrect for StringUtils.endsWithIgnoreCase.
o LANG-428:  StringUtils.isAlpha, isAlphanumeric and isNumeric now return false
             for ""
o LANG-439:  StringEscapeUtils.escapeHTML() does not escape chars (0x00-0x20).
o LANG-448:  Lower Ascii Characters don't get encoded by Entities.java.
o LANG-468:  JDK 1.5 build/runtime failure on LANG-393 (EqualsBuilder).
o LANG-474:  Fixes for thread safety.
o LANG-478:  StopWatch does not resist to system time changes.
o LANG-480:  StringEscapeUtils.escapeHtml incorrectly converts unicode
             characters above U+00FFFF into 2 characters.
o LANG-481:  Possible race-conditions in hashCode of the range classes.
o LANG-564:  Improve StrLookup API documentation.
o LANG-568:  @SuppressWarnings("unchecked") is used too generally.
o LANG-571:  ArrayUtils.add(T[:  array, T element) can create unexpected
             ClassCastException.
o LANG-585:  exception.DefaultExceptionContext.getFormattedExceptionMessage
             catches Throwable.
o LANG-596:  StrSubstitutor should also handle the default properties of a
             java.util.Properties class
o LANG-600:  Javadoc is incorrect for public static int
             lastIndexOf(String str, String searchStr).
o LANG-602:  ContextedRuntimeException no longer an 'unchecked' exception.
o LANG-606:  EqualsBuilder causes StackOverflowException.
o LANG-608:  Some StringUtils methods should take an int character instead of
             char to use String API features.
o LANG-617:  StringEscapeUtils.escapeXML() can't process UTF-16 supplementary
             characters
o LANG-624:  SystemUtils.getJavaVersionAsFloat throws
             StringIndexOutOfBoundsException on Android runtime/Dalvik VM
o LANG-629:  Charset may not be threadsafe, because the HashSet is not synch.
o LANG-638:  NumberUtils createNumber throws a StringIndexOutOfBoundsException
             when argument containing "e" and "E" is passed in
o LANG-643:  Javadoc StringUtils.left() claims to throw on negative len, but
             doesn't
o LANG-645:  FastDateFormat.format() outputs incorrect week of year because
             locale isn't respected
o LANG-646:  StringEscapeUtils.unescapeJava doesn't handle octal escapes and
             Unicode with extra u
o LANG-656:  Example StringUtils.indexOfAnyBut("zzabyycdxx", '') = 0 incorrect
o LANG-658:  Some entities like &Ouml; are not matched properly against its
             ISO8859-1 representation
o LANG-659:  EntityArrays typo: {"\u2122", "&minus;"}, // minus sign, U+2212
             ISOtech
o LANG-66:   StringEscaper.escapeXml() escapes characters > 0x7f.
o LANG-662:  org.apache.commons.lang3.math.Fraction does not reduce
             (Integer.MIN_VALUE, 2^k)
o LANG-663:  org.apache.commons.lang3.math.Fraction does not always succeed in
             multiplyBy and divideBy
o LANG-664:  NumberUtils.isNumber(String) is not right when the String is
             "1.1L"
o LANG-672:  Doc bug in DateUtils#ceiling
o LANG-677:  DateUtils.isSameLocalTime compares using 12-hour clock and not
             24-hour
o LANG-685:  EqualsBuilder synchronizes on HashCodeBuilder.
o LANG-703:  StringUtils.join throws NPE when toString returns null for one of
             objects in collection
o LANG-710:  StringIndexOutOfBoundsException when calling unescapeHtml4("&#03")
o LANG-714:  StringUtils doc/comment spelling fixes.
o LANG-715:  CharSetUtils.squeeze() speedup.
o LANG-716:  swapCase and *capitalize speedups.


Historical list of changes: https://commons.apache.org/lang/changes-report.html

For complete information on Commons Lang, including instructions on how to
submit bug reports, patches, or suggestions for improvement, see the
Apache Commons Lang website:

https://commons.apache.org/lang/

Have fun!
-Apache Commons Lang team