You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by pj...@apache.org on 2002/08/18 23:20:51 UTC
cvs commit: jakarta-commons/collections RELEASE-NOTES-2.1.html
pjack 2002/08/18 14:20:51
Added: collections RELEASE-NOTES-2.1.html
Log:
First whack at 2.1 release notes.
Revision Changes Path
1.1 jakarta-commons/collections/RELEASE-NOTES-2.1.html
Index: 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>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) 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 map 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.
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>