~ubuntu-branches/debian/squeeze/libcommons-collections-java/squeeze

<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>
  <li>ArrayIterator.setArray(Object) will no longer throw an
  ArrayIndexOutOfBounds exception.</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>


<p><u>PriorityQueue</u></p>

<p>Changed to allow priority queue implementations that support determining
priorities using means other than the object's natural ordering (i.e. a
priority queue that does not depend on the object implementing the Comparable
interface).</p>

<p><i>PriorityQueue 2.0 compatibility changes:</i></p>

<ul>

  <li>The pop() and peek() methods were changed to return a generic Object
  rather than a comparable.</li>

  <li>The insert(Comparable) method was changed to take an Object argument
  rather than a comparable.</li>

</ul>


<p><u>BinaryHeap</u></p>

<p>Changed to allow the specification of a Comparator that should be used to
compare objects to determine "priority" of the objects.  If no comparator is
specified, the object's natural ordering is used.</p>

<p><i>BinaryHeap 2.0 compatibility changes:</i></p>

<ul>

  <li>The pop() and peek() methods were changed to return a generic Object
  rather than a comparable.</li>

  <li>The insert(Comparable) method was changed to take an Object argument
  rather than a comparable.</li>

</ul>

<p><i>New features:</i></p>
<ul>

  <li>The BinaryHeap supports objects that do not implement Comparable.  To use
  such objects in the binary heap, a suitable Comparator must be provided in
  the constructor so that the binary heap is capable of ordering elements in
  their relative priorities.</li>

</ul>