commons-collections/RELEASE-NOTES-2.0.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>Collections 2.0 includes a significant number of new collections, in addition to several 
useful Comparator classes.</p> 

<p>These collections are new to Collections 2.0:</p>

<ul>
<li><strong>Bag</strong> - A Collection that keeps a count of its members of the same
    type, using <code>hashCode</code> to check for equality. 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>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 Collections 1.0:

<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>