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 3.0?</title> 21 <author email="[email protected]">Commons Documentation Team</author> 22 </properties> 23<body> 24 25<section name="What's new in Commons Lang 3.0?"> 26<p>Commons Lang 3.0 is out, and the obvious question is: <em>"So what? What's changed?"</em>.</p> 27<section name="The big story"> 28<p>Lang is now Java 5 based. We've generified the API, moved certain APIs to support <code>varargs</code> and thrown out any features 29that are now supported by Java itself. We've removed the deprecated parts of the API and have also removed some features that 30were deemed weak or unnecessary. All of this means that Lang 3.0 is not backwards compatible. </p> 31<p>To that end we have changed the package name, allowing Lang 3.0 to sit side-by-side with your previous version of Lang without any bad side effects. The new package name is the exciting and original <code>org.apache.commons.lang3</code>. This also forces you to recompile your code, making sure the compiler can let you know if a backwards incompatibility affects you. </p> 32<p>As you'd expect, there are also new features, enhancements and bugs fixed. </p> 33</section> 34<!-- 35<section name="The build"> 36<p>We built 3.0 using Maven 2.2.1 and Java 1.5. <strong>Needs confirmation before release of actual build details</strong></p> 37</section> 38--> 39<section name="Migrating from 2.x"> 40<h3>Java code</h3> 41<p>Despite the label of backwards incompatibility, in the vast majority of cases the simple addition of a <code>'3'</code> to an import statement will suffice for your migration. </p><br/> 42<p>Change: <code>import org.apache.commons.lang</code> -> <code>import org.apache.commons.lang3</code></p> 43<h3>Maven</h3> 44<p><code>groupId</code>: <code>commons-lang</code> -> <code>org.apache.commons</code></p> 45<p><code>artifactId</code>: <code>commons-lang</code> -> <code>commons-lang3</code></p> 46</section> 47 48<section name="What's gone?"> 49<h3>Enum package</h3> 50<p>Java 5 provided enums out of the box, therefore we dispensed with both the deprecated enum package, 51and the enums package. Instead you should migrate over to the standard Java enum. An EnumUtils class has been born 52from the ashes of the old code, focused on providing additional functionality to the standard Java enum API. </p> 53<h3>NestedExceptions</h3> 54<p>In Java 1.4, the notion that all Throwables could be linked to a cause was introduced. In Lang we 55had provided a NestedException framework to support the same feature, and now that we're jumping from Java 1.3 to 56Java 5 we are remove this feature. The deprecation section below covers one part of ExceptionUtils that remains until 57we are on Java 6, where the last remaining parts of the JDK appear to have embraced the new cause API. </p> 58<h3>JVMRandom</h3> 59<p>This class was introduced in Lang 2.0 to support a Random object built around the system seed. This 60proved to be both an uncommon use case and one with bugs and so was dropped. </p> 61<h3>StringEscapeUtils.escapeSql</h3> 62<p>This was a misleading method, only handling the simplest of possible SQL cases. As SQL is not Lang's focus, it didn't make sense to maintain this method. </p> 63<h3>*Exceptions removed</h3> 64<p>Various Exception classes were removed - the lesson in defining more semantically relevant exception classes is that you can keep on coming up with more and more new classes. Simpler to focus on using the main JDK classes. </p> 65<h3>math.*Range</h3> 66<p>The various Range classes in the <code>math</code> package were removed in favour of a new generic Range class. </p> 67<h3>Previous Deprecations</h3> 68<p>All deprecated fields/methods/classes - with a new major version, all of the previously deprecated parts of the API could finally go away. </p> 69<p>If you feel that something was unfairly taken away, please feel free to contact the list. In many cases the possibility exists to reintroduce code. </p> 70</section> 71<section name="Deprecations"> 72<p>The lone deprecation in 3.0 is that of the notion of 'cause method names' in ExceptionUtils. In Java 5.0 it is still just about 73needed to handle some JDK classes that have not been migrated to the getCause API. In Java 6.0 things appear to be resolved and 74we will remove the related methods in Lang 4.0. </p> 75</section> 76<section name="New packages"> 77<p>Two new packages have shown up. org.apache.commons.lang3.concurrent, which unsurprisingly provides support classes for 78multithreaded programming, and org.apache.commons.lang3.text.translate, which provides a pluggable API for text transformation. </p> 79 80<h3>concurrent.*</h3> 81<p>Java 1.5 adds a great bunch of functionality related to multithreaded programming 82below the <code>java.util.concurrent</code> package. Commons Lang 3.0 provides 83some additional classes in this area which are intended to further simplify the 84development of concurrent applications.</p> 85<p>The classes located in the <code>concurrent</code> package can be roughly 86divided into the following categories: 87<ul> 88<li>Utility classes</li> 89<li>Initializer classes</li> 90</ul> 91</p> 92<p>Classes of the former category provide some basic functionality a developer 93typically has to implement manually again and again. Examples are a configurable 94<code>ThreadFactory</code> implementation or utility methods for the handling of 95<code>ExecutionException</code>s thrown by Java's executor service framework.</p> 96<p>Initializer classes deal with the creation of objects in a multithreaded 97environment. There are several variants of initializer implementations serving 98different purposes. For instance, there are a couple of concrete initializers 99supporting lazy initialization of objects in a safe way. Another example is 100<code>BackgroundInitializer</code> which allows pushing the creation of an 101expensive object to a background thread while the application can continue with 102the execution of other tasks. Here is an example of the usage of <code>BackgroundInitializer</code> 103which creates an <code>EntityManagerFactory</code> object:</p> 104<pre> 105 public class DBInitializer extends BackgroundInitialize<EntityManagerFactory> { 106 protected EntityManagerFactory initialize() { 107 return Persistence.createEntityManagerFactory("mypersistenceunit"); 108 } 109 } 110</pre> 111<p>An application creates an instance of the <code>DBInitializer</code> class 112and calls its <code>start()</code> method. When it later needs access to the 113<code>EntityManagerFactory</code> created by the initializer it calls the 114<code>get()</code> method; <code>get()</code> returns the object produced by the 115initializer if it is already available or blocks if necessary until initialization 116is complete. Alternatively a convenience method of the <code>ConcurrentUtils</code> 117class can be used to obtain the object from the initializer which hides the 118checked exception declared by <code>get()</code>:</p> 119<pre> 120 DBInitializer init = new DBInitializer(); 121 init.start(); 122 123 // now do some other stuff 124 125 EntityManagerFactory factory = ConcurrentUtils.initializeUnchecked(init); 126</pre> 127<p>Comprehensive documentation about the <code>concurrent</code> package is 128available in the <a href="userguide.html#lang.concurrent.">user guide</a>.</p> 129<h3>text.translate.*</h3> 130<p>A common complaint with StringEscapeUtils was that its escapeXml and escapeHtml methods should not be escaping non-ASCII characters. We agreed and made the change while creating a modular approach to let users define their own escaping constructs. </p> 131<p>The simplest way to show this is to look at the code that implements escapeXml:</p> 132<pre> 133 return ESCAPE_XML.translate(input); 134</pre> 135<p>Very simple. Maybe a bit too very simple, let's look a bit deeper. </p> 136<pre> 137 public static final CharSequenceTranslator ESCAPE_XML = 138 new AggregateTranslator( 139 new LookupTranslator(EntityArrays.BASIC_ESCAPE()), 140 new LookupTranslator(EntityArrays.APOS_ESCAPE()) 141 ); 142</pre> 143<p>Here we see that <code>ESCAPE_XML</code> is a '<code>CharSequenceTranslator</code>', which in turn is made up of two lookup translators based on the basic XML escapes and another to escape apostrophes. This shows one way to combine translators. Another can be shown by looking at the example to achieve the old XML escaping functionality (escaping non-ASCII): </p> 144<pre> 145 StringEscapeUtils.ESCAPE_XML.with( NumericEntityEscaper.between(0x7f, Integer.MAX_VALUE) ); 146</pre> 147<p>That takes the standard Commons Lang provided escape functionality, and adds on another translation layer. Another JIRA requested option was to also escape non-printable ASCII, this is now achievable with a modification of the above: </p> 148<pre> 149 StringEscapeUtils.ESCAPE_XML.with( 150 new AggregateTranslator( 151 NumericEntityEscaper.between(0, 31), 152 NumericEntityEscaper.between(0x80, Integer.MAX_VALUE) 153 ) 154 ) 155</pre> 156<p>You can also implement your own translators (be they for escaping, unescaping or some aspect of your own). See the <code>CharSequenceTranslator</code> and its <code>CodePointTranslator</code> helper subclass for details - primarily a case of implementing the translate(CharSequence, int, Writer);int method. </p> 157</section> 158<section name="New classes + methods"> 159<p>There are many new classes and methods in Lang 3.0 - the most complete way to see the changes is via this <a href="lang2-lang3-clirr-report.html">Lang2 to Lang3 Clirr report</a>. </p> 160<p>Here is a summary of the new classes: </p> 161<ul> 162<li><code>AnnotationUtils</code></li> 163<li><code>CharSequenceUtils</code></li> 164<li><code>EnumUtils</code></li> 165<li><code>JavaVersion</code> - used in SystemUtils</li> 166<li><code>Pair, ImmutablePair and MutablePair</code></li> 167<li><code>Range</code> - replaces the old math.*Range classes</li> 168<li><code>builder.Builder</code></li> 169<li><code>exception.ContextedException</code></li> 170<li><code>exception.CloneFailedException</code></li> 171<li><code>reflect.ConstructorUtils</code></li> 172<li><code>reflect.FieldUtils</code></li> 173<li><code>reflect.MethodUtils</code></li> 174<li><code>reflect.TypeUtils</code></li> 175<li><code>text.WordUtils</code></li> 176</ul> 177</section> 178 179<section name="Bugfixes?"> 180<p>See the <a href="changes-report.html#3.0">3.0 changes report</a> for the list of fixed bugs and other enhancements. </p> 181</section> 182 183<section name="Other Notable Changes"> 184<ul> 185<li>StringUtils.isAlpha, isNumeric and isAlphanumeric now all return false when passed an empty String. Previously they returned true. </li> 186<li>SystemUtils.isJavaVersionAtLeast now relies on the <code>java.specification.version</code> and not the <code>java.version</code> System property. </li> 187<li>StringEscapeUtils.escapeXml and escapeHtml no longer escape high value Unicode characters by default. The text.translate package is available to recreate the old behavior. </li> 188<li>Validate utility methods have been changed and genericized to return the 189validated argument where possible, to allow for inline use. </li> 190<li>Validate utility methods handle validity violations arising from 191<code>null</code> values by throwing <code>NullPointerException</code>s. 192This better aligns with standard JDK behavior (lang <em>is</em> intended to 193complement <code>java.lang</code>, after all). Users upgrading from v2.x may 194need to adjust to this change. See <code>Validate#isTrue()</code> for a 195general-purpose mechanism to raise an <code>IllegalArgumentException</code>.</li> 196</ul> 197</section> 198 199<!-- 200<section name="What next???"> TODO: Add Beta info. 201<p>Hopefully that was all of interest. Don't forget to download <a href="https://commons.apache.org/lang/download_lang.cgi">Lang 3.0</a>, or, for the Maven repository users, upgrade your <version> tag to 3.0 and your groupId to org.apache.commons. 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> 202</section> 203--> 204 205</section> 206 207</body> 208</document> 209