265 lines
9.9 KiB
HTML
265 lines
9.9 KiB
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>
|