1<?xml version="1.0"?> 2<!-- 3Licensed to the Apache Software Foundation (ASF) under one or more 4contributor license agreements. See the NOTICE file distributed with 5this work for additional information regarding copyright ownership. 6The ASF licenses this file to You under the Apache License, Version 2.0 7(the "License"); you may not use this file except in compliance with 8the License. You may obtain a copy of the License at 9 10 http://www.apache.org/licenses/LICENSE-2.0 11 12Unless required by applicable law or agreed to in writing, software 13distributed under the License is distributed on an "AS IS" BASIS, 14WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15See the License for the specific language governing permissions and 16limitations under the License. 17--> 18<document> 19 <properties> 20 <title>Upgrade from 2.5 to 3.0</title> 21 <author email="dev@commons.apache.org">Commons Documentation Team</author> 22 </properties> 23<body> 24 25<section name="Upgrade to 3.0"> 26<p> 27For advice on upgrading Commons-Lang from version 2.5 to version 3.0 see 28'<a href="article3_0.html">What's new in 3.0?</a>'. 29<source> 30INTRODUCTION: 31 32This document contains the release notes for the 3.0 version of Apache Commons Lang. 33Commons Lang is a set of utility functions and reusable components that should be of use in any 34Java environment. 35 36Lang 3.0 now targets Java 5.0, making use of features that arrived with Java 5.0 such as generics, 37variable arguments, autoboxing, concurrency and formatted output. 38 39ADDITIONS IN 3.0 40================ 41 42 [LANG-276] MutableBigDecimal and MutableBigInteger. 43 [LANG-285] Wish : method unaccent. 44 [LANG-358] ObjectUtils.coalesce. 45 [LANG-386] LeftOf/RightOfNumber in Range convenience methods necessary. 46 [LANG-435] Add ClassUtils.isAssignable() variants with autoboxing. 47 [LANG-444] StringUtils.emptyToNull. 48 [LANG-482] Enhance StrSubstitutor to support nested ${var-${subvr}} expansion 49 [LANG-482] StrSubstitutor now supports substitution in variable names. 50 [LANG-496] A generic implementation of the Lazy initialization pattern. 51 [LANG-497] Addition of ContextedException and ContextedRuntimeException. 52 [LANG-498] Add StringEscapeUtils.escapeText() methods. 53 [LANG-499] Add support for the handling of ExecutionExceptions. 54 [LANG-501] Add support for background initialization. 55 [LANG-529] Add a concurrent package. 56 [LANG-533] Validate: support for validating blank strings. 57 [LANG-537] Add ArrayUtils.toArray to create generic arrays. 58 [LANG-545] Add ability to create a Future for a constant. 59 [LANG-546] Add methods to Validate to check whether the index is valid for the array/list/string. 60 [LANG-553] Add TypeUtils class to provide utility code for working with generic types. 61 [LANG-559] Added isAssignableFrom and isInstanceOf validation methods. 62 [LANG-559] Added validState validation method. 63 [LANG-560] New TimedSemaphore class. 64 [LANG-582] Provide an implementation of the ThreadFactory interface. 65 [LANG-588] Create a basic Pair<L, R> class. 66 [LANG-594] DateUtils equal & compare functions up to most significant field. 67 [LANG-601] Add Builder Interface / Update Builders to Implement It. 68 [LANG-609] Support lazy initialization using atomic variables 69 [LANG-610] Extend exception handling in ConcurrentUtils to runtime exceptions. 70 [LANG-614] StringUtils.endsWithAny method 71 [LANG-640] Add normalizeSpace to StringUtils 72 [LANG-644] Provide documentation about the new concurrent package 73 [LANG-649] BooleanUtils.toBooleanObject to support single character input 74 [LANG-651] Add AnnotationUtils 75 [LANG-653] Provide a very basic ConcurrentInitializer implementation 76 [LANG-655] Add StringUtils.defaultIfBlank() 77 [LANG-667] Add a Null-safe compare() method to ObjectUtils 78 [LANG-676] Documented potential NPE if auto-boxing occurs for some BooleanUtils methods 79 [LANG-678] Add support for ConcurrentMap.putIfAbsent() 80 [LANG-692] Add hashCodeMulti varargs method 81 82REMOVALS IN 3.0 83=============== 84 85 [LANG-438] Remove @deprecateds. 86 [LANG-492] Remove code handled now by the JDK. 87 [LANG-493] Remove code that does not hold enough value to remain. 88 [LANG-590] Remove JDK 1.2/1.3 bug handling in StringUtils.indexOf(String, String, int). 89 [LANG-673] WordUtils.abbreviate() removed 90 [LANG-691] Removed DateUtils.UTC_TIME_ZONE 91 92IMPROVEMENTS IN 3.0 93=================== 94 95 [LANG-290] EnumUtils for JDK 5.0. 96 [LANG-336] Finally start using generics. 97 [LANG-355] StrBuilder should implement CharSequence and Appendable. 98 [LANG-396] Investigate for vararg usages. 99 [LANG-424] Improve Javadoc for StringUtils class. 100 [LANG-458] Refactor Validate.java to eliminate code redundancy. 101 [LANG-479] Document where in SVN trunk is. 102 [LANG-504] bring ArrayUtils.isEmpty to the generics world. 103 [LANG-505] Rewrite StringEscapeUtils. 104 [LANG-507] StringEscapeUtils.unescapeJava should support \u+ notation. 105 [LANG-510] Convert StringUtils API to take CharSequence. 106 [LANG-513] Better EnumUtils. 107 [LANG-528] Mutable classes should implement an appropriately typed Mutable interface. 108 [LANG-539] Compile commons.lang for CDC 1.1/Foundation 1.1. 109 [LANG-540] Make NumericEntityEscaper immutable. 110 [LANG-541] Replace StringBuffer with StringBuilder. 111 [LANG-548] Use Iterable on API instead of Collection. 112 [LANG-551] Replace Range classes with generic version. 113 [LANG-562] Change Maven groupId. 114 [LANG-563] Change Java package name. 115 [LANG-570] Do the test cases really still require main() and suite() methods?. 116 [LANG-579] Add new Validate methods. 117 [LANG-599] ClassUtils.getClass(): Allow Dots as Inner Class Separators. 118 [LANG-605] DefaultExceptionContext overwrites values in recursive situations. 119 [LANG-668] Change ObjectUtils min() & max() functions to use varargs rather than just two parameters 120 [LANG-681] Push down WordUtils to "text" sub-package. 121 122BUG FIXES IN 3.0 123================ 124 125 [LANG-11] Depend on JDK 1.5+. 126 [LANG-302] StrBuilder does not implement clone(). 127 [LANG-339] StringEscapeUtils.escapeHtml() escapes multibyte characters like Chinese, Japanese, etc. 128 [LANG-369] ExceptionUtils not thread-safe. 129 [LANG-418] Javadoc incorrect for StringUtils.endsWithIgnoreCase. 130 [LANG-428] StringUtils.isAlpha, isAlphanumeric and isNumeric now return false for "" 131 [LANG-439] StringEscapeUtils.escapeHTML() does not escape chars (0x00-0x20). 132 [LANG-448] Lower Ascii Characters don't get encoded by Entities.java. 133 [LANG-468] JDK 1.5 build/runtime failure on LANG-393 (EqualsBuilder). 134 [LANG-474] Fixes for thread safety. 135 [LANG-478] StopWatch does not resist to system time changes. 136 [LANG-480] StringEscapeUtils.escapeHtml incorrectly converts Unicode characters above U+00FFFF into 2 characters. 137 [LANG-481] Possible race-conditions in hashCode of the range classes. 138 [LANG-564] Improve StrLookup API documentation. 139 [LANG-568] @SuppressWarnings("unchecked") is used too generally. 140 [LANG-571] ArrayUtils.add(T[] array, T element) can create unexpected ClassCastException. 141 [LANG-585] exception.DefaultExceptionContext.getFormattedExceptionMessage catches Throwable. 142 [LANG-596] StrSubstitutor should also handle the default properties of a java.util.Properties class 143 [LANG-600] Javadoc is incorrect for public static int lastIndexOf(String str, String searchStr). 144 [LANG-602] ContextedRuntimeException no longer an 'unchecked' exception. 145 [LANG-606] EqualsBuilder causes StackOverflowException. 146 [LANG-608] Some StringUtils methods should take an int character instead of char to use String API features. 147 [LANG-617] StringEscapeUtils.escapeXML() can't process UTF-16 supplementary characters 148 [LANG-624] SystemUtils.getJavaVersionAsFloat throws StringIndexOutOfBoundsException on Android runtime/Dalvik VM 149 [LANG-629] Charset may not be threadsafe, because the HashSet is not synch. 150 [LANG-638] NumberUtils createNumber throws a StringIndexOutOfBoundsException when argument containing "e" and "E" is passed in 151 [LANG-643] Javadoc StringUtils.left() claims to throw on negative len, but doesn't 152 [LANG-645] FastDateFormat.format() outputs incorrect week of year because locale isn't respected 153 [LANG-646] StringEscapeUtils.unescapeJava doesn't handle octal escapes and Unicode with extra u 154 [LANG-656] Example StringUtils.indexOfAnyBut("zzabyycdxx", '') = 0 incorrect 155 [LANG-658] Some entities like &Ouml; are not matched properly against its ISO8859-1 representation 156 [LANG-659] EntityArrays typo: {"\u2122", "&minus;"}, // minus sign, U+2212 ISOtech 157 [LANG-66] StringEscaper.escapeXml() escapes characters > 0x7f. 158 [LANG-662] org.apache.commons.lang3.math.Fraction does not reduce (Integer.MIN_VALUE, 2^k) 159 [LANG-663] org.apache.commons.lang3.math.Fraction does not always succeed in multiplyBy and divideBy 160 [LANG-664] NumberUtils.isNumber(String) is not right when the String is "1.1L" 161 [LANG-672] Doc bug in DateUtils#ceiling 162 [LANG-677] DateUtils.isSameLocalTime compares using 12-hour clock and not 24-hour 163 [LANG-685] EqualsBuilder synchronizes on HashCodeBuilder. 164 [LANG-703] StringUtils.join throws NPE when toString returns null for one of objects in collection 165 [LANG-710] StringIndexOutOfBoundsException when calling unescapeHtml4("&#03") 166 167</source> 168</p> 169</section> 170 171</body> 172</document> 173