170 lines
6.8 KiB
HTML
170 lines
6.8 KiB
HTML
<title>RELEASE NOTES: COLLECTIONS 2.0</title>
|
|
|
|
<center><h2>RELEASE NOTES: COLLECTIONS 2.0</h2></center>
|
|
|
|
|
|
<center><h3>NEW COLLECTIONS AND COMPARATORS</h3></center>
|
|
|
|
<p><i>Collections 2.0</i> includes a significant number of new collections, in addition to several
|
|
useful Comparator classes. Descriptions of the new collections and comparators 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.0</i>:</p>
|
|
|
|
<ul>
|
|
|
|
<li><strong>Bag</strong> - A Collection that counts the number of times an
|
|
object appears in the collection. Suppose
|
|
you have a Bag that contains <code>{a, a, b, c}</code>. Calling
|
|
getCount on <code>a</code> would return 2, while calling
|
|
uniqueSet would return <code>{a, b, c}</code>. <i>Note: this is an
|
|
interface with several implementations.</i></li>
|
|
<li><strong>DoubleOrderedMap</strong> - Red-Black tree-based implementation of Map.
|
|
This class guarantees
|
|
that the map will be in both ascending key order and ascending
|
|
value order, sorted according to the natural order for the key's
|
|
and value's classes.</li>
|
|
<li><strong>FilterListIterator</strong> - A proxy <code>ListIterator</code> which
|
|
takes a <code>Predicate</code> instance to filter
|
|
out objects from an underlying <code>ListIterator</code>
|
|
instance. Only objects for which the specified
|
|
<code>Predicate</code> evaluates to <code>true</code> are
|
|
returned by the iterator.</li>
|
|
<li><strong>HashBag</strong> - An implementation of <strong>Bag</strong> that is backed by a
|
|
HashMap.</li>
|
|
<li><strong>MultiMap</strong> - This is simply a Map with slightly different semantics.
|
|
Instead of returning an Object, it returns a Collection.
|
|
So for example, you can put( key, new Integer(1) );
|
|
and then a Object get( key ); will return you a Collection
|
|
instead of an Integer. This is an interface implemented
|
|
by <strong>MultiHashMap</strong>.</li>
|
|
<li><strong>ProxyMap</strong> - This <code>Map</code> wraps another <code>Map</code>
|
|
implementation, using the wrapped instance for its default
|
|
implementation. This class is used as a framework on which to
|
|
build to extensions for its wrapped <code>Map</code> object which
|
|
would be unavailable or inconvenient via sub-classing (but usable
|
|
via composition).</li>
|
|
<li><strong>SequencedHashMap</strong> - A map of objects whose mapping entries are
|
|
sequenced based on the order in
|
|
which they were added.</li>
|
|
<li><strong>SortedBag</strong> - A type of <strong>Bag</strong> that maintains order among its unique
|
|
representative members</li>
|
|
<li><strong>TreeBag</strong> - An implementation of <strong>Bag</strong> that is backed by a
|
|
TreeMap. Order will be maintained among the unique representative
|
|
members.</li>
|
|
</ul>
|
|
|
|
<p>These are the new Comparator classes:</p>
|
|
|
|
<ul>
|
|
<li><strong>ComparableComparator</strong> - A Comparator that compares Comparable objects.
|
|
This Comparator is useful, for example,
|
|
for enforcing the natural order in custom implementations
|
|
of SortedSet and SortedMap.</li>
|
|
<li><strong>ComparatorChain</strong> - ComparatorChain is a Comparator that wraps one or
|
|
more Comparators in sequence. The ComparatorChain
|
|
calls each Comparator in sequence until either 1)
|
|
any single Comparator returns a non-zero result
|
|
(and that result is then returned),
|
|
or 2) the ComparatorChain is exhausted (and zero is
|
|
returned). This type of sorting is very similar
|
|
to multi-column sorting in SQL, and this class
|
|
allows Java classes to emulate that kind of behaviour
|
|
when sorting a List.</li>
|
|
<li><strong>ReverseComparator</strong> - Reverses the order of another comparator.</li>
|
|
</ul>
|
|
|
|
|
|
<center><h3>CHANGED COLLECTIONS</h3></center>
|
|
|
|
These classes have changed since <i>Collections 1.0</i>:
|
|
|
|
<p><u>ArrayEnumeration</u></p>
|
|
|
|
<p>ArrayEnumeration has been <b>deprecated</b>. This class has significant overlap with
|
|
ArrayIterator, and Collections focuses mainly on Java2-style
|
|
collections. If you need to enumerate an array,
|
|
create an ArrayIterator and wrap it with an
|
|
IteratorEnumeration instead.</p>
|
|
|
|
<p><u>ArrayIterator</u></p>
|
|
|
|
<p><i>Bugs fixed:</i></p>
|
|
<ul>
|
|
<li>ArrayIterator can now iterate over arrays of primatives</li>
|
|
</ul>
|
|
|
|
<p><u>LRUMap</u></p>
|
|
|
|
<p>LRUMap has been reimplemented as a subclass of
|
|
SynchronizedHashMap. The new implementation of
|
|
LRUMap should be faster, and it also offers true LRU
|
|
capabilities; now any get(Object) or
|
|
put(Object,Object) from this collection
|
|
promotes the key to the Most Recently Used position.</p>
|
|
|
|
<p><i>LRUMap 2.0 compatibility changes:</i></p>
|
|
<ul>
|
|
<li>LRUMap can no longer be cast to a HashMap.</li>
|
|
<li>The removeLRU() method now has a different
|
|
signature, and is no longer public. Instead, use
|
|
remove(getFirstKey()).</li>
|
|
<li>"Externalized" LRUMap 1.0 Objects cannot be
|
|
read by LRUMap 2.0.</li>
|
|
</ul>
|
|
|
|
<p><i>New features:</i></p>
|
|
<ul>
|
|
<li>True LRU algorithm.</li>
|
|
<li>New methods from SequencedHashMap superclass.</li>
|
|
<li>processRemovedLRU(Object key, Object value) method
|
|
allows subclasses to perform custom actions on
|
|
keys and values that are expunged from the Map.</li>
|
|
</ul>
|
|
|
|
<p><i>Bugs fixed:</i></p>
|
|
<ul>
|
|
<li>calling setMaximumSize(int) will remove excess LRUs
|
|
when the current size of the Map exceeds the new
|
|
maximum size</li>
|
|
</ul>
|
|
|
|
|
|
<p><u>BeanMap</u></p>
|
|
|
|
<p>BeanMap's entrySet() now properly returns a set containing Map.Entry
|
|
objects. Previously, entrySet() was equivalent to keySet() (returns a set of
|
|
the readable properties) and there was no mechanism to retrieve all of the
|
|
readable properties along with their values. Additionally, the BeanMap clone
|
|
method has been revamped to work better for subclasses. </p>
|
|
|
|
<p><i>BeanMap 2.0 compatibility changes:</i></p>
|
|
<ul>
|
|
|
|
<li>BeanMap's clone() method now declares it throws
|
|
CloneNotSupportedException. This allows subclasses of BeanMap to not require
|
|
being Cloneable and facilitates subclasses that wish to be cloneable (allows
|
|
the subclass to call super.clone() and have it return an instance of the
|
|
child rather than the parent).</li>
|
|
|
|
<li>If a BeanMap is not cloneable because a new instance of the underlying
|
|
bean cannot be constructed, a CloneNotSupportedException is thrown rather
|
|
than an UnsupportedOperationException or other RuntimeException.</li>
|
|
|
|
<li>BeanMap's entrySet() method now returns a set of Map.Entry objects rather
|
|
than the set of readable properties. To retrieve a set of readable
|
|
properties, use keySet() instead.</li>
|
|
|
|
</ul>
|
|
|
|
<p><i>Bugs fixed:</i></p>
|
|
<ul>
|
|
|
|
<li>If no bean is set in the BeanMap, or setBean(Object) was called with a
|
|
null argument, many BeanMap methods threw NullPointerExceptions. These have
|
|
been fixed to properly handle the case where there is no bean established in
|
|
the map.</li>
|
|
|
|
</ul>
|
|
|