commons-collections/RELEASE-NOTES-2.1.html

<title>RELEASE NOTES: COLLECTIONS 2.1</title>

<center><h2>RELEASE NOTES: COLLECTIONS 2.1</h2></center>

<center><h3>REFACTORING</h3></center>

<p><u>Documentation</u></p>

<p>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.</p>

<p><u>New Testing Suite</u></p>

<p>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.</p>

<p><u>New iterators Subpackage</u></p>

<p>All of the iterator classes released in <i>Collections 2.0</i> have been
moved to an iterators subpackage in <i>Collections 2.1</i>.  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.</p>

<p>The affected classes from 2.0 are:</p>

<ul>
<li>ArrayIterator</li>
<li>EnumerationIterator</li>
<li>FilterIterator</li>
<li>FilterListIterator</li>
<li>IteratorEnumeration</li>
<li>ProxyIterator</li>
<li>ProxyListIterator</li>
<li>SingletonIterator</li>
<li>UniqueFilterIterator</li>
</ul>

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

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

<center><h3>
NEW COLLECTIONS, COMPARATORS, ITERATORS AND UTILITY CLASSES
</h3></center>

<p><i>Collections 2.1</i> includes a significant number of new collections, 
including a new Collection interface for queues and queue-like things.  In
addition, a new package was created to house collections that operate on 
primitive elements.  New comparators were added to the comparators 
subpackage, and new iterators were added to the iterators subpackage.</p>

<p>Also, many new utility classes were added to the main package.  The 
new utility classes primarly provide decorators for various collection
or collection-related interfaces.</p>

<p>Descriptions of the new collections, comparators, iterators and utility
classes follow.  (For descriptions of all classes in <i>Collections</i>, 
see the <i>STATUS.html</i> file.)</p> 

<p>These collections are new to <i>Collections 2.1</i>:</p>

<ul>

<li><strong>Buffer</strong> - 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.  <I>Note: this is an interface with several 
    implementations.</I></li>
<li><strong>BoundedFifoBuffer</strong> - A very efficient FIFO queue 
    implementation of Buffer.  Places an upper limit on the number of elements
    that can be added.</li>
<li><strong>ReferenceMap</strong> - Hash-based Map implementation that allows 
    mappings to be removed by the garbage collector.</li>
<li><strong>StaticBucketMap</strong> - An efficient, thread-safe 
    implementation of java.util.Map that performs well in in a highly 
    thread-contentious environment.</li>
<li><strong>UnboundedFifoBuffer</strong> - A very efficient buffer 
    implementation.  It places no upper limit on the number of elements.</li>
</ul>

<p>These are the new collections in the primitives subpackage:</P>

<ul>
<li><strong>AbstractIntArrayList</strong> - Abstract base class for lists 
    backed by an int array.</li>
<li><strong>AbstractLongArrayList</strong> - Abstract base class for lists 
    backed by a long array.</li>
<li><strong>AbstractShortArrayList</strong> - Abstract base class for lists 
    backed by a short array.</li>
<li><strong>FloatArrayList</strong> - A list backed by a float array.</li>
<li><strong>IntArrayList</strong> - A list of int elements.</li>
<li><strong>LongArrayList</strong> - A list of long elements.</li>
<li><strong>ShortArrayList</strong> - A list of short elements.</li>
<li><strong>UnsignedByteArrayList</strong> - A list of unsigned 8-bit values, 
    stored in a short array.</li>
<li><strong>UnsignedIntArrayList</strong> - A list of unsigned 32-bit values, 
    stored in a long array.</li>
<li><strong>UnsignedShortArrayList</strong> - A list of unsigned 16-bit 
    values, stored in an int array.</li>
</ul>

<p>These comparators are new to <i>Collections 2.1</i>:</p>

<ul>
<li><strong>NullComparator</strong> - A Comparator that will compare nulls 
    to be either lower or higher than other objects.</li>
<li><strong>TransformingComparator</strong> - Decorates another Comparator 
    with transformation behavior.</li>
</ul>

<p>These iterators are new to <i>Collections 2.1</i>:</p>

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

<p>These are the new utility classes:</p>

<ul>
<li><strong>BagUtils</strong> - Contains static utility methods for dealing
with bags.</li>
<li><strong>BufferUtils</strong> - Contains static utility methods for 
dealing with buffers.</li>
<li><strong>ComparatorUtils</strong> - Contains static utility methods for
dealing with comparators.  Note that the functionality provided by this
class is redundant; users can also use the individual classes in the 
comparators subpackage.</li>
<li><strong>IteratorUtils</strong> - Contains static utility methods for
dealing with iterators.  Note that the functionality provided by this
class is redundant; users can also use the individual classes in the 
iterators subpackage.</li>
<li><strong>SetUtils</strong> - Contains static utility methods for dealing
with sets.</li>
</ul>


<center><h3>CHANGED CLASSES</h3></center>

These classes have changed since <i>Collections 2.0</i>:

<p><u>ArrayStack</u></p>

<p>Now implements the Buffer interface.  The Buffer.get() and Buffer.remove()
methods are implemented in terms of peek() and pop().</p>

<p><u>BeanMap</u></p>

<p>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.</p>

<p><u>BinaryHeap</u></p>

<p>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().</p>

<p><u>CollectionUtils</u></p>

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

<p><u>CursorableLinkedList</u></p>

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

<p><u>DefaultMapBag</u></p>

<p>A basic toString() method was added to aid in debugging.</p>

<p><u>FastArrayList</u></p>

<p>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.</p>

<p><u>FastHashMap</u></p>

<p>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.</p>

<p><u>FastTreeMap</u></p>

<p>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.</p>

<p><u>LRUMap</u></p>

<p>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.</p>

<p><u>ListUtils</u></p>

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

<p><u>MapUtils</u></p>

<p>Added decorators to allow predicated, lazy and fixed-size maps and
sorted maps.</p>

<p><u>ProxyMap</u></p>

<p>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.</p>

<p><u>SequencedHashMap</u></p>

<p>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.</p>

<p><u>SoftRefHashMap</u></p>

<p>SoftRefHashMap has been <b>deprecated</b> 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.