## RELEASE NOTES: COLLECTIONS 3.0

Originally, Collections was a general place for placing useful collection classes. With version 3.0, this changes. Collections now has a design and package structure of its own. As a result, several well-used classes have been deprecated and moved to new packages.

This release also includes a lot of new functionality, including new interfaces and new implementations in addition to various bug fixes and refactoring changes. All previously deprecated classes have been removed.

The major changes are:

- New package structure - One package now exists for each major interface
- Bidirectional maps - New interface and implementations for maps that need bidirectional lookup
- Map iterator - New interface to enable iteration over map keys and values in one easy step
- Resettable iterator - Interfaces that defines a reset() method to reset the iterator back to the start
- Functors - A default set of functor implementations is now provided for Predicate, Transformer, Closure and Factory
- KeyValue - A new package full of key-value pairs and map entry implementations
- Abstract Hash-based Map - Highly extensible hash-based, and hash-link-based map abstract classes
- PriorityQueue deprecated - The top level interface PriorityQueue has been deprecated in favour of Buffer

### NEW PACKAGES

These packages are new to Collections 3.0:

- collection - Package of Collection implementations
- list - Package of List implementations
- set - Package of Set implementations
- bag - Package of Bag implementations
- buffer - Package of Buffer implementations
- map - Package of Map implementations
- bidimap - Package of BidiMap implementations
- keyvalue - Package of key-value pair implementations

### NEW CLASSES

These implementations are new to Collections 3.0:

- CompositeCollection/Set/Map - Merges multiple collections into a single view
- NodeCachingLinkedList - A list that caches nodes, performing well if long-lived
- HashedMap - An alternative to HashMap that supports a MapIterator
- LinkedMap - A map that retains the order of its entries
- Flat3Map - A map optimised for size 3 or less
- IdentityMap - A map that uses == not equals()
- CaseInsenstiveMap - A map that ignores case when comparing keys
- ListOrderedSet/Map - A set/map that behaves like a List
- SetUniqueList - A list that behaves like a Set
- CircularFifoBuffer - A buffer that eliminates the oldest entry when full
- DualHashBidiMap - BidiMap implementation
- DualTreeBidiMap - SortedBidiMap implementation
- TreeBidiMap - OrderedBidiMap implementation
- FixedOrderComparator - A comparator in a fixed pre-determined order
- BooleanComparator - A comparator over Boolean instances
- ArrayListIterator - A ListIterator over an array of any type (including primitive arrays)
- LoopingIterator - An Iterator that loops repeatedly over the collection
- ObjectArray*Iterator - Iterators over an Object array
- EntrySetMapIterator - A MapIterator implemented using an entry set

### CHANGED CLASSES

These classes have changed in a potentially incompatible way:

- BufferUnderflowException - Now extends NoSuchElementException
- BeanMap.MyMapEntry - Superclass changed
- MultiHashMap - Name facility and getName() method removed
- FilterIterator - Superclass changed
- FilterListIterator - Superclass changed
- TransformIterator - Superclass changed

These collections have changed since Collections 3.0:

- PriorityQueue - Deprecated, use Buffer interface
- BinaryHeap - Deprecated, use PriorityBuffer
- SynchronizedPriorityQueue - Deprecated, use SynchronizedBuffer
- BoundedFifoBuffer - Deprecated, moved to buffer subpackage
- UnboundedFifoBuffer - Deprecated, moved to buffer subpackage
- SequencedHashMap - Deprecated, rewritten as LinkedMap in map subpackage
- DefaultMapBag - Deprecated, rewritten as AbstractMapBag in bag subpackage
- HashBag - Deprecated, moved and rewritten in bag subpackage
- TreeBag - Deprecated, moved and rewritten in bag subpackage
- DefaultMapEntry - Deprecated, moved to keyvalue subpackage
- DoubleOrderedMap - Deprecated, replaced by bidimap interface and implementations
- LRUMap - Deprecated, moved and rewritten in map subpackage
- ReferenceMap - Deprecated, moved to map subpackage
- StaticBucketMap - Deprecated, moved to map subpackage
- ProxyMap - Deprecated, moved as AbstractMapDecorator in map subpackage
- ExtendedProperties - Bug fixes. Please consider using Commons-Configuration `PropertiesConfiguration`

These comparators have changed since Collections 3.0:

- ComparableComparator - Simpler implementation that respects interface better.
- ComparatorChain - Equals and HashCode added.
- ReverseComparator - Equals and HashCode added.

These iterators have changed since Collections 3.0:

- ArrayIterator - This now implements the ResetableIterator interface. It also supports a start index to iterate from.
- CollatingIterator - The remove() method now throws IllegalStateException not NoSuchElementException.
- FilterIterator - The remove() method is now supported, with some limitations.
- IteratorChain - Now supports a chain of zero iterators. Bug fix for when remove() called before hasNext()/next().
- Singleton*Iterator - These now implement the ResetableIterator interface.
- Proxy*Iterator - Now deprecated in favour of AbstractIteratorDecorator/AbstractListIteratorDecorator.
- Filter*Iterator/TransformIterator - No longer extend ProxyIterator.