Update to reflect most up to date set of changes for release
git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@130823 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Stephen Colebourne
parent
4e2452d242
commit
472cf4f569
|
|
@ -2,75 +2,48 @@
|
||||||
|
|
||||||
<center><h2>RELEASE NOTES: COLLECTIONS 2.1</h2></center>
|
<center><h2>RELEASE NOTES: COLLECTIONS 2.1</h2></center>
|
||||||
|
|
||||||
<center><h3>REFACTORING</h3></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
|
||||||
<p><u>Documentation</u></p>
|
are:
|
||||||
|
</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>
|
<ul>
|
||||||
<li>ArrayIterator</li>
|
<li><strong>Buffers</strong> - A new collection interface for queues and
|
||||||
<li>EnumerationIterator</li>
|
queue-like things.</li>
|
||||||
<li>FilterIterator</li>
|
<li><strong>Primitives</strong> - A new package for collections that store the
|
||||||
<li>FilterListIterator</li>
|
data as primitive elements instead of objects.</li>
|
||||||
<li>IteratorEnumeration</li>
|
<li><strong>Decorators</strong> - A group of static utility classes that provide
|
||||||
<li>ProxyIterator</li>
|
decorators for other collections</li>
|
||||||
<li>ProxyListIterator</li>
|
|
||||||
<li>SingletonIterator</li>
|
|
||||||
<li>UniqueFilterIterator</li>
|
|
||||||
</ul>
|
</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>
|
||||||
|
|
||||||
<p>In addition, new iterators were added to the subpackage; these are
|
<hr />
|
||||||
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>
|
<center><h3>
|
||||||
NEW COLLECTIONS, COMPARATORS, ITERATORS AND UTILITY CLASSES
|
NEW COLLECTIONS, COMPARATORS, ITERATORS AND UTILITY CLASSES
|
||||||
</h3></center>
|
</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>
|
<p>These collections are new to <i>Collections 2.1</i>:</p>
|
||||||
|
|
||||||
<ul>
|
<ul>
|
||||||
|
|
||||||
<li><strong>Buffer</strong> - A collection that allows elements to be removed
|
<li><strong>Buffer</strong> - A collection that allows elements to be removed
|
||||||
in some well-defined order. Can describe queues, stacks, priority queues,
|
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
|
LRU caches or any other structure that allows elements to be removed in a
|
||||||
|
|
@ -91,6 +64,12 @@ see the <i>STATUS.html</i> file.)</p>
|
||||||
<p>These are the new collections in the primitives subpackage:</P>
|
<p>These are the new collections in the primitives subpackage:</P>
|
||||||
|
|
||||||
<ul>
|
<ul>
|
||||||
|
<li><strong>AbstractIntList</strong> - Abstract base class for lists
|
||||||
|
of ints.</li>
|
||||||
|
<li><strong>AbstractLongList</strong> - Abstract base class for lists
|
||||||
|
of longs.</li>
|
||||||
|
<li><strong>AbstractShortList</strong> - Abstract base class for lists
|
||||||
|
of shorts.</li>
|
||||||
<li><strong>AbstractIntArrayList</strong> - Abstract base class for lists
|
<li><strong>AbstractIntArrayList</strong> - Abstract base class for lists
|
||||||
backed by an int array.</li>
|
backed by an int array.</li>
|
||||||
<li><strong>AbstractLongArrayList</strong> - Abstract base class for lists
|
<li><strong>AbstractLongArrayList</strong> - Abstract base class for lists
|
||||||
|
|
@ -140,18 +119,18 @@ with bags.</li>
|
||||||
<li><strong>BufferUtils</strong> - Contains static utility methods for
|
<li><strong>BufferUtils</strong> - Contains static utility methods for
|
||||||
dealing with buffers.</li>
|
dealing with buffers.</li>
|
||||||
<li><strong>ComparatorUtils</strong> - Contains static utility methods for
|
<li><strong>ComparatorUtils</strong> - Contains static utility methods for
|
||||||
dealing with comparators. Note that the functionality provided by this
|
dealing with comparators. Note that the functionality can also be achieved
|
||||||
class is redundant; users can also use the individual classes in the
|
by using the individual classes in the comparators subpackage.</li>
|
||||||
comparators subpackage.</li>
|
|
||||||
<li><strong>IteratorUtils</strong> - Contains static utility methods for
|
<li><strong>IteratorUtils</strong> - Contains static utility methods for
|
||||||
dealing with iterators. Note that the functionality provided by this
|
dealing with iterators. Note that the functionality can also be achieved
|
||||||
class is redundant; users can also use the individual classes in the
|
by using the individual classes in the iterators subpackage.</li>
|
||||||
iterators subpackage.</li>
|
|
||||||
<li><strong>SetUtils</strong> - Contains static utility methods for dealing
|
<li><strong>SetUtils</strong> - Contains static utility methods for dealing
|
||||||
with sets.</li>
|
with sets.</li>
|
||||||
</ul>
|
</ul>
|
||||||
|
|
||||||
|
|
||||||
|
<hr />
|
||||||
|
|
||||||
<center><h3>CHANGED CLASSES</h3></center>
|
<center><h3>CHANGED CLASSES</h3></center>
|
||||||
|
|
||||||
These classes have changed since <i>Collections 2.0</i>:
|
These classes have changed since <i>Collections 2.0</i>:
|
||||||
|
|
@ -254,3 +233,53 @@ unintuitive side-effects, it violated the java.util.Map contract in several
|
||||||
places and its internal algorithms were inefficient. A new class,
|
places and its internal algorithms were inefficient. A new class,
|
||||||
ReferenceMap, is a more general solution that can be used in place of
|
ReferenceMap, is a more general solution that can be used in place of
|
||||||
SoftRefHashMap.
|
SoftRefHashMap.
|
||||||
|
</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>
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue