RELEASE NOTES: COLLECTIONS 2.1

Collections 2.1 includes a significant number of new collections in addition to various bug fixes and refactoring changes. The major additions are:

The decorators are found on classes named XxxUtils where Xxx is the collection type. The decorators are:

Access to Iterators and Comparators has also been brought in line, by the provision of IteratorUtils and ComparatorUtils.


NEW COLLECTIONS, COMPARATORS, ITERATORS AND UTILITY CLASSES

These collections are new to Collections 2.1:

These comparators are new to Collections 2.1:

These iterators are new to Collections 2.1:

These are the new utility classes:


CHANGED CLASSES

These classes have changed since Collections 2.0:

ArrayStack

Now implements the Buffer interface. The Buffer.get() and Buffer.remove() methods are implemented in terms of peek() and pop(). The class has also been altered to allow null elements inline with ArrayList.

BeanMap

A new method was added to allow a bulk putAll(Map) operation only for bean properties that are actually writeable. The new method, named putAllWriteable(Map), can be used to set one bean's state to another's by using two BeanMaps.

BinaryHeap

Now implements the Buffer interface. Since Buffer is a subinterface of Collection, BinaryHeap is also a Collection. This makes it much more interoperable with existing APIs. The Buffer.get() and Buffer.remove() methods are implemented in terms of peek() and pop().

CollectionUtils

Modified the index(Object,Object) method to work for arbitrary collections. Previously the method only worked for Lists. Added the predicatedCollection(Collection, Predicate) method.

CursorableLinkedList

Fixed NullPointerExceptions that were raised by contains(Object), indexOf(Object), lastIndexOf(Object) and remove(Object) if the given Object was null.

DefaultMapBag

A basic toString() method was added to aid in debugging.

FastArrayList

Added severe warning about possible unexpected failures of this class on some architectures. Fixed the subList(int,int) method so that changes to the sublist are reflected in the original list, even in fast mode.

FastHashMap

Added severe warning about possible unexpected failures of this class on some architectures. Fixed the collection views so changes to the map are reflected in the collection views and vice-versa, even in fast mode.

FastTreeMap

Added severe warning about possible unexpected failures of this class on some architectures. Fixed the collection views so changes to the map are reflected in the collection views and vice-versa, even in fast mode.

LRUMap

The get(Object) method was fixed to ensure that if containsKey(foo) returns false, then get(foo) will not change that. (Before, invoking get(Object) on a nonexistent key could cause that key to incorrectly map to a null value). Also, the changes to SequencedHashMap were inherited by LRUMap.

ListUtils

The previous version of this class was deprecated; it has been un-deprecated. Decorators were added to allow predicated, lazy and fixed-size lists.

MapUtils

Added decorators to allow predicated, lazy and fixed-size maps and sorted maps.

ProxyMap

Fixed a bug in the equals(Object) method. Before the equals(Object) method infinitely recursively called itself until a StackOverflowError was raised. This version of the method properly delegates the method call to the underlying map.

SequencedHashMap

The iterators on collection views now raise a ConcurrentModificationException if the map is modified through something other than the iterator. The equals(Object) and hashCode() methods were fixed to correctly implement the Map specification. The remove(Object) methods in the keySet() and entrySet() were fixed so that they correctly return false after removing a null key.

SoftRefHashMap

SoftRefHashMap has been deprecated because it was all kinds of wonky. Its semantics were never well-defined, many of its operations had unintuitive side-effects, it violated the java.util.Map contract in several places and its internal algorithms were inefficient. A new class, ReferenceMap, is a more general solution that can be used in place of SoftRefHashMap.

StringStack

StringStack has been deprecated because it was unsuitable for inclusion in collections. It enabled a delimited String to be built up. This functionality is better placed in StringUtils in the lang project.


REFACTORING

Documentation

Almost every class released in 2.0 was touched to improve on, or in some cases complete, the JavaDoc. Those documentation changes are not described in detail below; but the goal was simply to have the public and protected Collections API completely documentated. If a class released in 2.0 had missing public or protected JavaDoc, then the class was modified to add it.

New Testing Suite

The unit testing framework used to test collections and maps underwent a major overhaul between 2.0 and 2.1. The new tests check for stricter Collection and Map contract conformance. Many bugs were found and addressed with the new tests; bug fixes are described below. The testing suite is not considered part of the binary release and may undergo further changes.

New iterators Subpackage

All of the iterator classes released in Collections 2.0 have been moved to an iterators subpackage in Collections 2.1. Versions of the iterators still exist in the main package, but have been deprecated. This was a simple organizational move that will hopefully make the packages easier to navigate and absorb.

The affected classes from 2.0 are:

In addition, new iterators were added to the subpackage; these are described below.

Note that other than being in a new package, no other changes were made to the iterator implementations.