## RELEASE NOTES: COLLECTIONS 2.0

### NEW COLLECTIONS AND COMPARATORS

Collections 2.0 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 Collections, see the STATUS.html file.)

These collections are new to Collections 2.0:

- Bag - A Collection that counts the number of times an object appears in the collection. Suppose you have a Bag that contains `{a, a, b, c}`. Calling getCount on `a` would return 2, while calling uniqueSet would return `{a, b, c}`. Note: this is an interface with several implementations.
- DoubleOrderedMap - 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.
- FilterListIterator - A proxy `ListIterator` which takes a `Predicate` instance to filter out objects from an underlying `ListIterator` instance. Only objects for which the specified `Predicate` evaluates to `true` are returned by the iterator.
- HashBag - An implementation of Bag that is backed by a HashMap.
- MultiMap - 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 MultiHashMap.
- ProxyMap - This `Map` wraps another `Map` 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 `Map` object which would be unavailable or inconvenient via sub-classing (but usable via composition).
- SequencedHashMap - A map of objects whose mapping entries are sequenced based on the order in which they were added.
- SortedBag - A type of Bag that maintains order among its unique representative members
- TreeBag - An implementation of Bag that is backed by a TreeMap. Order will be maintained among the unique representative members.

These are the new Comparator classes:

- ComparableComparator - A Comparator that compares Comparable objects. This Comparator is useful, for example, for enforcing the natural order in custom implementations of SortedSet and SortedMap.
- ComparatorChain - 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.
- ReverseComparator - Reverses the order of another comparator.

### CHANGED COLLECTIONS

These classes have changed since Collections 1.0:

ArrayEnumeration

ArrayEnumeration has been deprecated. 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.

ArrayIterator

Bugs fixed:

- ArrayIterator can now iterate over arrays of primatives.
- ArrayIterator.setArray(Object) will no longer throw an ArrayIndexOutOfBounds exception.

LRUMap

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.

LRUMap 2.0 compatibility changes:

- LRUMap can no longer be cast to a HashMap.
- The removeLRU() method now has a different signature, and is no longer public. Instead, use remove(getFirstKey()).
- "Externalized" LRUMap 1.0 Objects cannot be read by LRUMap 2.0.

New features:

- True LRU algorithm.
- New methods from SequencedHashMap superclass.
- processRemovedLRU(Object key, Object value) method allows subclasses to perform custom actions on keys and values that are expunged from the Map.

Bugs fixed:

- calling setMaximumSize(int) will remove excess LRUs when the current size of the Map exceeds the new maximum size

BeanMap

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.

BeanMap 2.0 compatibility changes:

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

Bugs fixed:

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

PriorityQueue

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

PriorityQueue 2.0 compatibility changes:

- The pop() and peek() methods were changed to return a generic Object rather than a comparable.
- The insert(Comparable) method was changed to take an Object argument rather than a comparable.

BinaryHeap

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.

BinaryHeap 2.0 compatibility changes:

- The pop() and peek() methods were changed to return a generic Object rather than a comparable.
- The insert(Comparable) method was changed to take an Object argument rather than a comparable.

New features:

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