Java code

Despite the label of backwards incompatibility, in the vast majority of cases the simple addition of a '3' to an import statement will suffice for your migration.

Change: import org.apache.commons.lang -> import org.apache.commons.lang3

Maven

groupId: commons-lang -> org.apache.commons

artifactId: commons-lang -> commons-lang3

Enum package

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.

NestedExceptions

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.

JVMRandom

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.

StringEscapeUtils.escapeSql

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.

*Exceptions removed

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.

math.*Range

The various Range classes in the math package were removed in favour of a new generic Range class.

Previous Deprecations

All deprecated fields/methods/classes - with a new major version, all of the previously deprecated parts of the API could finally go away.

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.

concurrent.*

Java 1.5 adds a great bunch of functionality related to multithreaded programming below the java.util.concurrent package. Commons Lang 3.0 provides some additional classes in this area which are intended to further simplify the development of concurrent applications.

The classes located in the concurrent package can be roughly divided into the following categories:

• Utility classes
• Initializer classes

Classes of the former category provide some basic functionality a developer typically has to implement manually again and again. Examples are a configurable ThreadFactory implementation or utility methods for the handling of ExecutionExceptions thrown by Java's executor service framework.

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 BackgroundInitializer 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 BackgroundInitializer which creates an EntityManagerFactory object:

    public class DBInitializer extends BackgroundInitialize<EntityManagerFactory> {
        protected EntityManagerFactory initialize() {
            return Persistence.createEntityManagerFactory("mypersistenceunit");
        }
    }

An application creates an instance of the DBInitializer class and calls its start() method. When it later needs access to the EntityManagerFactory created by the initializer it calls the get() method; get() 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 ConcurrentUtils class can be used to obtain the object from the initializer which hides the checked exception declared by get():

    DBInitializer init = new DBInitializer();
    init.start();

    // now do some other stuff

    EntityManagerFactory factory = ConcurrentUtils.initializeUnchecked(init);

Comprehensive documentation about the concurrent package is available in the user guide.

text.translate.*

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.

The simplest way to show this is to look at the code that implements escapeXml:

    return ESCAPE_XML.translate(input);

Very simple. Maybe a bit too very simple, let's look a bit deeper.

    public static final CharSequenceTranslator ESCAPE_XML =
        new AggregateTranslator(
            new LookupTranslator(EntityArrays.BASIC_ESCAPE()),
            new LookupTranslator(EntityArrays.APOS_ESCAPE())
        );

Here we see that ESCAPE_XML is a 'CharSequenceTranslator', 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):

          StringEscapeUtils.ESCAPE_XML.with( NumericEntityEscaper.between(0x7f, Integer.MAX_VALUE) );

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:

          StringEscapeUtils.ESCAPE_XML.with(
              new AggregateTranslator(
                  NumericEntityEscaper.between(0, 31),
                  NumericEntityEscaper.between(0x80, Integer.MAX_VALUE)
              )
          )

You can also implement your own translators (be they for escaping, unescaping or some aspect of your own). See the CharSequenceTranslator and its CodePointTranslator helper subclass for details - primarily a case of implementing the translate(CharSequence, int, Writer);int method.