First whack at 2.1 release notes.
PR: Obtained from: Submitted by: Reviewed by: git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@130799 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
pjack
parent
901deeeeff
commit
fb639bca7b
|
|
@ -0,0 +1,262 @@
|
|||
<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.
|
||||
Loading…
Reference in New Issue