1*455610afSAndroid Build Coastguard Worker<?xml version="1.0"?> 2*455610afSAndroid Build Coastguard Worker<!-- 3*455610afSAndroid Build Coastguard WorkerLicensed to the Apache Software Foundation (ASF) under one or more 4*455610afSAndroid Build Coastguard Workercontributor license agreements. See the NOTICE file distributed with 5*455610afSAndroid Build Coastguard Workerthis work for additional information regarding copyright ownership. 6*455610afSAndroid Build Coastguard WorkerThe ASF licenses this file to You under the Apache License, Version 2.0 7*455610afSAndroid Build Coastguard Worker(the "License"); you may not use this file except in compliance with 8*455610afSAndroid Build Coastguard Workerthe License. You may obtain a copy of the License at 9*455610afSAndroid Build Coastguard Worker 10*455610afSAndroid Build Coastguard Worker http://www.apache.org/licenses/LICENSE-2.0 11*455610afSAndroid Build Coastguard Worker 12*455610afSAndroid Build Coastguard WorkerUnless required by applicable law or agreed to in writing, software 13*455610afSAndroid Build Coastguard Workerdistributed under the License is distributed on an "AS IS" BASIS, 14*455610afSAndroid Build Coastguard WorkerWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15*455610afSAndroid Build Coastguard WorkerSee the License for the specific language governing permissions and 16*455610afSAndroid Build Coastguard Workerlimitations under the License. 17*455610afSAndroid Build Coastguard Worker--> 18*455610afSAndroid Build Coastguard Worker<document> 19*455610afSAndroid Build Coastguard Worker <properties> 20*455610afSAndroid Build Coastguard Worker <title>What's new in Commons Lang 3.0?</title> 21*455610afSAndroid Build Coastguard Worker <author email="[email protected]">Commons Documentation Team</author> 22*455610afSAndroid Build Coastguard Worker </properties> 23*455610afSAndroid Build Coastguard Worker<body> 24*455610afSAndroid Build Coastguard Worker 25*455610afSAndroid Build Coastguard Worker<section name="What's new in Commons Lang 3.0?"> 26*455610afSAndroid Build Coastguard Worker<p>Commons Lang 3.0 is out, and the obvious question is: <em>"So what? What's changed?"</em>.</p> 27*455610afSAndroid Build Coastguard Worker<section name="The big story"> 28*455610afSAndroid Build Coastguard Worker<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 29*455610afSAndroid Build Coastguard Workerthat are now supported by Java itself. We've removed the deprecated parts of the API and have also removed some features that 30*455610afSAndroid Build Coastguard Workerwere deemed weak or unnecessary. All of this means that Lang 3.0 is not backwards compatible. </p> 31*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker<p>As you'd expect, there are also new features, enhancements and bugs fixed. </p> 33*455610afSAndroid Build Coastguard Worker</section> 34*455610afSAndroid Build Coastguard Worker<!-- 35*455610afSAndroid Build Coastguard Worker<section name="The build"> 36*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker</section> 38*455610afSAndroid Build Coastguard Worker--> 39*455610afSAndroid Build Coastguard Worker<section name="Migrating from 2.x"> 40*455610afSAndroid Build Coastguard Worker<h3>Java code</h3> 41*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker<p>Change: <code>import org.apache.commons.lang</code> -> <code>import org.apache.commons.lang3</code></p> 43*455610afSAndroid Build Coastguard Worker<h3>Maven</h3> 44*455610afSAndroid Build Coastguard Worker<p><code>groupId</code>: <code>commons-lang</code> -> <code>org.apache.commons</code></p> 45*455610afSAndroid Build Coastguard Worker<p><code>artifactId</code>: <code>commons-lang</code> -> <code>commons-lang3</code></p> 46*455610afSAndroid Build Coastguard Worker</section> 47*455610afSAndroid Build Coastguard Worker 48*455610afSAndroid Build Coastguard Worker<section name="What's gone?"> 49*455610afSAndroid Build Coastguard Worker<h3>Enum package</h3> 50*455610afSAndroid Build Coastguard Worker<p>Java 5 provided enums out of the box, therefore we dispensed with both the deprecated enum package, 51*455610afSAndroid Build Coastguard Workerand the enums package. Instead you should migrate over to the standard Java enum. An EnumUtils class has been born 52*455610afSAndroid Build Coastguard Workerfrom the ashes of the old code, focused on providing additional functionality to the standard Java enum API. </p> 53*455610afSAndroid Build Coastguard Worker<h3>NestedExceptions</h3> 54*455610afSAndroid Build Coastguard Worker<p>In Java 1.4, the notion that all Throwables could be linked to a cause was introduced. In Lang we 55*455610afSAndroid Build Coastguard Workerhad provided a NestedException framework to support the same feature, and now that we're jumping from Java 1.3 to 56*455610afSAndroid Build Coastguard WorkerJava 5 we are remove this feature. The deprecation section below covers one part of ExceptionUtils that remains until 57*455610afSAndroid Build Coastguard Workerwe are on Java 6, where the last remaining parts of the JDK appear to have embraced the new cause API. </p> 58*455610afSAndroid Build Coastguard Worker<h3>JVMRandom</h3> 59*455610afSAndroid Build Coastguard Worker<p>This class was introduced in Lang 2.0 to support a Random object built around the system seed. This 60*455610afSAndroid Build Coastguard Workerproved to be both an uncommon use case and one with bugs and so was dropped. </p> 61*455610afSAndroid Build Coastguard Worker<h3>StringEscapeUtils.escapeSql</h3> 62*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker<h3>*Exceptions removed</h3> 64*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker<h3>math.*Range</h3> 66*455610afSAndroid Build Coastguard Worker<p>The various Range classes in the <code>math</code> package were removed in favour of a new generic Range class. </p> 67*455610afSAndroid Build Coastguard Worker<h3>Previous Deprecations</h3> 68*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker</section> 71*455610afSAndroid Build Coastguard Worker<section name="Deprecations"> 72*455610afSAndroid Build Coastguard Worker<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 73*455610afSAndroid Build Coastguard Workerneeded to handle some JDK classes that have not been migrated to the getCause API. In Java 6.0 things appear to be resolved and 74*455610afSAndroid Build Coastguard Workerwe will remove the related methods in Lang 4.0. </p> 75*455610afSAndroid Build Coastguard Worker</section> 76*455610afSAndroid Build Coastguard Worker<section name="New packages"> 77*455610afSAndroid Build Coastguard Worker<p>Two new packages have shown up. org.apache.commons.lang3.concurrent, which unsurprisingly provides support classes for 78*455610afSAndroid Build Coastguard Workermultithreaded programming, and org.apache.commons.lang3.text.translate, which provides a pluggable API for text transformation. </p> 79*455610afSAndroid Build Coastguard Worker 80*455610afSAndroid Build Coastguard Worker<h3>concurrent.*</h3> 81*455610afSAndroid Build Coastguard Worker<p>Java 1.5 adds a great bunch of functionality related to multithreaded programming 82*455610afSAndroid Build Coastguard Workerbelow the <code>java.util.concurrent</code> package. Commons Lang 3.0 provides 83*455610afSAndroid Build Coastguard Workersome additional classes in this area which are intended to further simplify the 84*455610afSAndroid Build Coastguard Workerdevelopment of concurrent applications.</p> 85*455610afSAndroid Build Coastguard Worker<p>The classes located in the <code>concurrent</code> package can be roughly 86*455610afSAndroid Build Coastguard Workerdivided into the following categories: 87*455610afSAndroid Build Coastguard Worker<ul> 88*455610afSAndroid Build Coastguard Worker<li>Utility classes</li> 89*455610afSAndroid Build Coastguard Worker<li>Initializer classes</li> 90*455610afSAndroid Build Coastguard Worker</ul> 91*455610afSAndroid Build Coastguard Worker</p> 92*455610afSAndroid Build Coastguard Worker<p>Classes of the former category provide some basic functionality a developer 93*455610afSAndroid Build Coastguard Workertypically has to implement manually again and again. Examples are a configurable 94*455610afSAndroid Build Coastguard Worker<code>ThreadFactory</code> implementation or utility methods for the handling of 95*455610afSAndroid Build Coastguard Worker<code>ExecutionException</code>s thrown by Java's executor service framework.</p> 96*455610afSAndroid Build Coastguard Worker<p>Initializer classes deal with the creation of objects in a multithreaded 97*455610afSAndroid Build Coastguard Workerenvironment. There are several variants of initializer implementations serving 98*455610afSAndroid Build Coastguard Workerdifferent purposes. For instance, there are a couple of concrete initializers 99*455610afSAndroid Build Coastguard Workersupporting lazy initialization of objects in a safe way. Another example is 100*455610afSAndroid Build Coastguard Worker<code>BackgroundInitializer</code> which allows pushing the creation of an 101*455610afSAndroid Build Coastguard Workerexpensive object to a background thread while the application can continue with 102*455610afSAndroid Build Coastguard Workerthe execution of other tasks. Here is an example of the usage of <code>BackgroundInitializer</code> 103*455610afSAndroid Build Coastguard Workerwhich creates an <code>EntityManagerFactory</code> object:</p> 104*455610afSAndroid Build Coastguard Worker<pre> 105*455610afSAndroid Build Coastguard Worker public class DBInitializer extends BackgroundInitialize<EntityManagerFactory> { 106*455610afSAndroid Build Coastguard Worker protected EntityManagerFactory initialize() { 107*455610afSAndroid Build Coastguard Worker return Persistence.createEntityManagerFactory("mypersistenceunit"); 108*455610afSAndroid Build Coastguard Worker } 109*455610afSAndroid Build Coastguard Worker } 110*455610afSAndroid Build Coastguard Worker</pre> 111*455610afSAndroid Build Coastguard Worker<p>An application creates an instance of the <code>DBInitializer</code> class 112*455610afSAndroid Build Coastguard Workerand calls its <code>start()</code> method. When it later needs access to the 113*455610afSAndroid Build Coastguard Worker<code>EntityManagerFactory</code> created by the initializer it calls the 114*455610afSAndroid Build Coastguard Worker<code>get()</code> method; <code>get()</code> returns the object produced by the 115*455610afSAndroid Build Coastguard Workerinitializer if it is already available or blocks if necessary until initialization 116*455610afSAndroid Build Coastguard Workeris complete. Alternatively a convenience method of the <code>ConcurrentUtils</code> 117*455610afSAndroid Build Coastguard Workerclass can be used to obtain the object from the initializer which hides the 118*455610afSAndroid Build Coastguard Workerchecked exception declared by <code>get()</code>:</p> 119*455610afSAndroid Build Coastguard Worker<pre> 120*455610afSAndroid Build Coastguard Worker DBInitializer init = new DBInitializer(); 121*455610afSAndroid Build Coastguard Worker init.start(); 122*455610afSAndroid Build Coastguard Worker 123*455610afSAndroid Build Coastguard Worker // now do some other stuff 124*455610afSAndroid Build Coastguard Worker 125*455610afSAndroid Build Coastguard Worker EntityManagerFactory factory = ConcurrentUtils.initializeUnchecked(init); 126*455610afSAndroid Build Coastguard Worker</pre> 127*455610afSAndroid Build Coastguard Worker<p>Comprehensive documentation about the <code>concurrent</code> package is 128*455610afSAndroid Build Coastguard Workeravailable in the <a href="userguide.html#lang.concurrent.">user guide</a>.</p> 129*455610afSAndroid Build Coastguard Worker<h3>text.translate.*</h3> 130*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker<p>The simplest way to show this is to look at the code that implements escapeXml:</p> 132*455610afSAndroid Build Coastguard Worker<pre> 133*455610afSAndroid Build Coastguard Worker return ESCAPE_XML.translate(input); 134*455610afSAndroid Build Coastguard Worker</pre> 135*455610afSAndroid Build Coastguard Worker<p>Very simple. Maybe a bit too very simple, let's look a bit deeper. </p> 136*455610afSAndroid Build Coastguard Worker<pre> 137*455610afSAndroid Build Coastguard Worker public static final CharSequenceTranslator ESCAPE_XML = 138*455610afSAndroid Build Coastguard Worker new AggregateTranslator( 139*455610afSAndroid Build Coastguard Worker new LookupTranslator(EntityArrays.BASIC_ESCAPE()), 140*455610afSAndroid Build Coastguard Worker new LookupTranslator(EntityArrays.APOS_ESCAPE()) 141*455610afSAndroid Build Coastguard Worker ); 142*455610afSAndroid Build Coastguard Worker</pre> 143*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker<pre> 145*455610afSAndroid Build Coastguard Worker StringEscapeUtils.ESCAPE_XML.with( NumericEntityEscaper.between(0x7f, Integer.MAX_VALUE) ); 146*455610afSAndroid Build Coastguard Worker</pre> 147*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker<pre> 149*455610afSAndroid Build Coastguard Worker StringEscapeUtils.ESCAPE_XML.with( 150*455610afSAndroid Build Coastguard Worker new AggregateTranslator( 151*455610afSAndroid Build Coastguard Worker NumericEntityEscaper.between(0, 31), 152*455610afSAndroid Build Coastguard Worker NumericEntityEscaper.between(0x80, Integer.MAX_VALUE) 153*455610afSAndroid Build Coastguard Worker ) 154*455610afSAndroid Build Coastguard Worker ) 155*455610afSAndroid Build Coastguard Worker</pre> 156*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker</section> 158*455610afSAndroid Build Coastguard Worker<section name="New classes + methods"> 159*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker<p>Here is a summary of the new classes: </p> 161*455610afSAndroid Build Coastguard Worker<ul> 162*455610afSAndroid Build Coastguard Worker<li><code>AnnotationUtils</code></li> 163*455610afSAndroid Build Coastguard Worker<li><code>CharSequenceUtils</code></li> 164*455610afSAndroid Build Coastguard Worker<li><code>EnumUtils</code></li> 165*455610afSAndroid Build Coastguard Worker<li><code>JavaVersion</code> - used in SystemUtils</li> 166*455610afSAndroid Build Coastguard Worker<li><code>Pair, ImmutablePair and MutablePair</code></li> 167*455610afSAndroid Build Coastguard Worker<li><code>Range</code> - replaces the old math.*Range classes</li> 168*455610afSAndroid Build Coastguard Worker<li><code>builder.Builder</code></li> 169*455610afSAndroid Build Coastguard Worker<li><code>exception.ContextedException</code></li> 170*455610afSAndroid Build Coastguard Worker<li><code>exception.CloneFailedException</code></li> 171*455610afSAndroid Build Coastguard Worker<li><code>reflect.ConstructorUtils</code></li> 172*455610afSAndroid Build Coastguard Worker<li><code>reflect.FieldUtils</code></li> 173*455610afSAndroid Build Coastguard Worker<li><code>reflect.MethodUtils</code></li> 174*455610afSAndroid Build Coastguard Worker<li><code>reflect.TypeUtils</code></li> 175*455610afSAndroid Build Coastguard Worker<li><code>text.WordUtils</code></li> 176*455610afSAndroid Build Coastguard Worker</ul> 177*455610afSAndroid Build Coastguard Worker</section> 178*455610afSAndroid Build Coastguard Worker 179*455610afSAndroid Build Coastguard Worker<section name="Bugfixes?"> 180*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker</section> 182*455610afSAndroid Build Coastguard Worker 183*455610afSAndroid Build Coastguard Worker<section name="Other Notable Changes"> 184*455610afSAndroid Build Coastguard Worker<ul> 185*455610afSAndroid Build Coastguard Worker<li>StringUtils.isAlpha, isNumeric and isAlphanumeric now all return false when passed an empty String. Previously they returned true. </li> 186*455610afSAndroid Build Coastguard Worker<li>SystemUtils.isJavaVersionAtLeast now relies on the <code>java.specification.version</code> and not the <code>java.version</code> System property. </li> 187*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker<li>Validate utility methods have been changed and genericized to return the 189*455610afSAndroid Build Coastguard Workervalidated argument where possible, to allow for inline use. </li> 190*455610afSAndroid Build Coastguard Worker<li>Validate utility methods handle validity violations arising from 191*455610afSAndroid Build Coastguard Worker<code>null</code> values by throwing <code>NullPointerException</code>s. 192*455610afSAndroid Build Coastguard WorkerThis better aligns with standard JDK behavior (lang <em>is</em> intended to 193*455610afSAndroid Build Coastguard Workercomplement <code>java.lang</code>, after all). Users upgrading from v2.x may 194*455610afSAndroid Build Coastguard Workerneed to adjust to this change. See <code>Validate#isTrue()</code> for a 195*455610afSAndroid Build Coastguard Workergeneral-purpose mechanism to raise an <code>IllegalArgumentException</code>.</li> 196*455610afSAndroid Build Coastguard Worker</ul> 197*455610afSAndroid Build Coastguard Worker</section> 198*455610afSAndroid Build Coastguard Worker 199*455610afSAndroid Build Coastguard Worker<!-- 200*455610afSAndroid Build Coastguard Worker<section name="What next???"> TODO: Add Beta info. 201*455610afSAndroid Build Coastguard Worker<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*455610afSAndroid Build Coastguard Worker</section> 203*455610afSAndroid Build Coastguard Worker--> 204*455610afSAndroid Build Coastguard Worker 205*455610afSAndroid Build Coastguard Worker</section> 206*455610afSAndroid Build Coastguard Worker 207*455610afSAndroid Build Coastguard Worker</body> 208*455610afSAndroid Build Coastguard Worker</document> 209