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