libcommons-collections-java 2.1.1-10 / usr / share / doc / libcommons-collections-java / RELEASE-NOTES-2.1.html

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

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

<p><i>Collections 2.1</i> includes a significant number of new collections
in addition to various bug fixes and refactoring changes. The major additions
are:
</p>
<ul>
<li><strong>Buffers</strong> - A new collection interface for queues and 
queue-like things.</li>
<li><strong>Decorators</strong> - A group of static utility classes that provide
decorators for other collections</li>
</ul>
<p>
The decorators are found on classes named <code>XxxUtils</code> where Xxx is the
collection type. The decorators are:
</p>
<ul>
<li><strong>Synchronized</strong> - Synchronized decorators where not provided 
by <code>Collections</code>.</li>
<li><strong>Unmodifiable</strong> - Unmodifiable decorators where not provided 
by <code>Collections</code>.</li>
<li><strong>Predicated</strong> - Decorators that only allow the addition of an
element to the collection if it matches a <code>Predicate</code>.</li>
<li><strong>FixedSize</strong> - Decorators that ensure that the list/map 
cannot change size.</li>
<li><strong>Lazy</strong> - Decorators that create objects on demand using a
<code>Factory</code>.</li>
</ul>
<p>
Access to Iterators and Comparators has also been brought in line, by the provision
of <code>IteratorUtils</code> and <code>ComparatorUtils</code>.
</p>

<hr />

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

<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 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 can also be achieved
by using the individual classes in the comparators subpackage.</li>
<li><strong>IteratorUtils</strong> - 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.</li>
<li><strong>SetUtils</strong> - Contains static utility methods for dealing
with sets.</li>
</ul>


<hr />

<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().  The class has also
been altered to allow null elements inline with ArrayList.</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.
</p>

<p><u>StringStack</u></p>

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

<hr />


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