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

• Buffers - A new collection interface for queues and queue-like things.
• Decorators - A group of static utility classes that provide decorators for other collections

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

• Synchronized - Synchronized decorators where not provided by Collections.
• Unmodifiable - Unmodifiable decorators where not provided by Collections.
• Predicated - Decorators that only allow the addition of an element to the collection if it matches a Predicate.
• FixedSize - Decorators that ensure that the list/map cannot change size.
• Lazy - Decorators that create objects on demand using a Factory.

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

These collections are new to Collections 2.1:

• Buffer - A collection that allows elements to be removed in some well-defined order. Can describe queues, stacks, priority queues, LRU caches or any other structure that allows elements to be removed in a well-defined order. Note: this is an interface with several implementations.
• BoundedFifoBuffer - A very efficient FIFO queue implementation of Buffer. Places an upper limit on the number of elements that can be added.
• ReferenceMap - Hash-based Map implementation that allows mappings to be removed by the garbage collector.
• StaticBucketMap - An efficient, thread-safe implementation of java.util.Map that performs well in in a highly thread-contentious environment.
• UnboundedFifoBuffer - A very efficient buffer implementation. It places no upper limit on the number of elements.

These comparators are new to Collections 2.1:

• NullComparator - A Comparator that will compare nulls to be either lower or higher than other objects.
• TransformingComparator - Decorates another Comparator with transformation behavior.

These iterators are new to Collections 2.1:

• CollatingIterator - Provides an ordered iteration over the elements contained in a collection of ordered Iterators.
• IteratorChain - An Iterator that wraps one or more Iterators.
• ListIteratorWrapper - As the wrapped Iterator is traversed, ListIteratorWrapper builds a LinkedList of its values, permitting all required operations of ListIterator.
• UniqueFilterIterator - A FilterIterator which only returns unique objects.

These are the new utility classes:

• BagUtils - Contains static utility methods for dealing with bags.
• BufferUtils - Contains static utility methods for dealing with buffers.
• ComparatorUtils - Contains static utility methods for dealing with comparators. Note that the functionality can also be achieved by using the individual classes in the comparators subpackage.
• IteratorUtils - Contains static utility methods for dealing with iterators. Note that the functionality can also be achieved by using the individual classes in the iterators subpackage.
• SetUtils - Contains static utility methods for dealing with sets.

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.

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:

• ArrayIterator
• EnumerationIterator
• FilterIterator
• FilterListIterator
• IteratorEnumeration
• ProxyIterator
• ProxyListIterator
• SingletonIterator

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.