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>What's new in Commons Lang 2.5?</title> 21 <author email="dev@commons.apache.org">Commons Documentation Team</author> 22 </properties> 23<body> 24 25<section name="What's new in Commons Lang 2.5?"> 26<p>Commons Lang 2.5 is out, and the obvious question is: <em>"So what? What's changed?"</em>.</p> 27<p>This article aims to briefly cover the changes and save you from having to dig through each JIRA 28issue to see what went on in the two years of development between Lang 2.4 and 2.5.</p> 29<p>Two years?!? Yes, it's true. The reason is that 2.5 represents the backwards compatible changes in the 30nearly complete Java-5 focused Lang 3.0. </p> 31<section name="Deprecations"> 32<p>There were no new deprecations in 2.5. </p> 33</section> 34<section name="The build"> 35<p>2.5 was built using Sun's 1.6.0_17 JVM, but targets Java 1.3. </p> 36</section> 37<section name="New classes"> 38<p>A new org.apache.commons.lang.reflect package was added, accumulating common high-level uses of the java.lang.reflect APIs. The 39classes, hopefully self-evident in nature, were pulled together from the existing BeanUtils and the unreleased Reflect components. 40The classes are: </p> 41<ul> 42<li>ConstructorUtils - primarily creating new instances of classes</li> 43<li>FieldUtils - primarily reading and writing to Object/Class fields</li> 44<li>MethodUtils - primarily methods to make invoking methods simpler</li> 45</ul> 46<p>You can read more about the classes in their 47<a href="LANG_2_5/src/main/java/org/apache/commons/lang/reflect//MemberUtils.java">javadoc</a>. </p> 48</section> 49<section name="New fields"> 50<p>With both Java 7 and Windows 7 becoming a reality, 51<a href="https://commons.apache.org/proper/commons-lang/javadocs/api-2.5/org/apache/commons/lang/SystemUtils.html">SystemUtils</a> was updated to 52provide boolean fields for both versions. </p> 53</section> 54<section name="New methods"> 55<p>There were 66 new methods added to existing Commons Lang classes. </p> 56<p>The <a href="https://commons.apache.org/proper/commons-lang/javadocs/api-2.5/org/apache/commons/lang/ArrayUtils.html">ArrayUtils</a> class 57received two new types of methods. Firstly, a boolean isNotEmpty(array) set of methods, identifying whether the particular 58array is null or an empty sized array. This makes it the inverse of the existing isEmpty(array) methods. Secondly, an array 59nullToEmpty(array) set of methods that converts null or empty arrays to a singleton empty array already available from the 60ArrayUtils class. Non-null/empty arrays are left untouched. </p> 61 62<p>The constructor for the 63<a href="https://commons.apache.org/proper/commons-lang/javadocs/api-2.5/org/apache/commons/lang/CharRange.html">CharRange</a> class is somewhat 64confusing. It takes a boolean parameter that when set to true means the CharRange is negated. To make code easier to read, the 65following static helper methods were added: </p> 66<ul> 67<li>public org.apache.commons.lang.CharRange is(char)</li> 68<li>public org.apache.commons.lang.CharRange isIn(char, char)</li> 69<li>public org.apache.commons.lang.CharRange isNot(char)</li> 70<li>public org.apache.commons.lang.CharRange isNotIn(char, char)</li> 71</ul> 72<p>An iterator() method was also added to provide another way of walking the range. </p> 73 74<p>The <a href="https://commons.apache.org/proper/commons-lang/javadocs/api-2.5/org/apache/commons/lang/builder/EqualsBuilder.html">EqualsBuilder</a> 75obtained a new reset() method to allow for reuse, while the 76<a href="https://commons.apache.org/proper/commons-lang/javadocs/api-2.5/org/apache/commons/lang/builder/HashCodeBuilder.html">HashCodeBuilder</a> 77received a hashCode() method that returns the built hash code instead of the natural hash code of the builder object itself. It 78doesn't really matter what the builder chooses to use as a hash code and this stops accidental use of the hashCode() instead of 79toHashCode() method from causing lots of pain. </p> 80 81<p>Helper isFalse(), isTrue() and toBoolean() methods were added to 82<a href="https://commons.apache.org/proper/commons-lang/javadocs/api-2.5/org/apache/commons/lang/mutable/MutableBoolean.html">MutableBoolean</a>, 83while the other mutable classes received String argument constructors. </p> 84 85<p>Lastly, the <a href="https://commons.apache.org/proper/commons-lang/javadocs/api-2.5/org/apache/commons/lang/time/DateUtils.html">DateUtils</a> 86class received a new ceiling set of methods to truncate upwards, and a parseDateStrictly method to parse a Date with the 87supplied DateFormat classes leniency set to false. </p> 88 89</section> 90 91<section name="StringUtils methods"> 92<p>As with 2.4, the 93<a href="https://commons.apache.org/proper/commons-lang/javadocs/api-2.5/org/apache/commons/lang/StringUtils.html">StringUtils</a> class has 94grown and we cover its new methods in its own section. </p> 95<ul> 96<li>abbreviateMiddle(String, String, int);String - This method turns aRatherLongNameSuchAsAFileName into 'aRatherLo...AFileName'. 97This is often desirable when you want to restrict the length of a name, but you can afford to have quite long names. </li> 98<li>indexOfIgnoreCase(String, String);int - An indexOf method that ignores the case of what it's matching. Matching lastIndexOfIgnoreCase and 'start at index' variants were also added. </li> 99<li>lastOrdinalIndexOf(String, String, int);int - A matching variant for the already existing ordinalIndexOf method - they 100support finding the Nth indexOf instead of the first time the search term is found. </li> 101<li>isAllLowerCase(String);boolean - Is the String all lower case. </li> 102<li>isAllUpperCase(String);boolean - Is the String all upper case. </li> 103<li>lowerCase(String, Locale);String - Null protected toLowerCase methods for the platform independent inclined. </li> 104<li>upperCase(String, Locale);String - Null protected toUpperCase methods for the platform independent inclined. </li> 105<li>repeat(String, String, int);String - Repeat option that includes an optional separator. </li> 106<li>startsWithAny(String, String[]);boolean - Does the specified String start with any of the supplied values. </li> 107</ul> 108</section> 109 110<section name="What's fixed in Lang 2.5?"> 111<p>Per the <a href="upgradeto2_5.html">release notes</a> there are 32 bugs fixed in Lang 2.5. Some highlights are: </p> 112<ul> 113<li><a href="https://issues.apache.org/jira/browse/LANG-477">LANG-477</a> - fixing an OutOfMemoryError in ExtendedMessageFormat. </li> 114<li><a href="https://issues.apache.org/jira/browse/LANG-76">LANG-76</a> - EnumUtils.getEnum() doesn't work well in 1.5. </li> 115<li><a href="https://issues.apache.org/jira/browse/LANG-204">LANG-204</a> and 116<a href="https://issues.apache.org/jira/browse/LANG-506">LANG-506</a> - Multithreading improvements to the package private Entities 117class, used behind the scenes by StringEscapeUtils. </li> 118<li><a href="https://issues.apache.org/jira/browse/LANG-511">LANG-511</a> - Improve performance by deferring LocaleUtils initialization. </li> 119<li><a href="https://issues.apache.org/jira/browse/LANG-523">LANG-523</a> - Two orders of magnitude performance improvement in StrBuilder. </li> 120<li><a href="https://issues.apache.org/jira/browse/LANG-467">LANG-467</a> - Reverted the change to EqualsBuilder in Lang 2.4 to 121specially handle BigDecimal. While useful, it put things out of sync with HashCodeBuilder. </li> 122<li><a href="https://issues.apache.org/jira/browse/LANG-586">LANG-586</a> - Use of a ThreadLocal in HashCodeBuilder and 123ToStringStyle meant that containers could end up with memory leaks. This was rewritten to avoid this. </li> 124<li><a href="https://issues.apache.org/jira/browse/LANG-472">LANG-472</a> - RandomUtils.nextLong() was returning only even numbers. Fans of Java-based roulette wheels can breathe a sigh of relief. </li> 125</ul> 126</section> 127 128<section name="So long, farewell..."> 129<p>Hopefully that was all of interest. Don't forget to download <a href="https://commons.apache.org/lang/download_lang.cgi">Lang 2.5</a>, or, for the Maven repository users, upgrade your <version> tag to 2.5. Please feel free to raise any questions you might have on the <a href="mail-lists.html">mailing lists</a>, and report bugs or enhancements in the <a href="issue-tracking.html">issue tracker</a>.</p> 130</section> 131 132</section> 133 134</body> 135</document> 136