## RELEASE NOTES: COLLECTIONS 3.1

This release adds various new classes and fixes a number of bugs. All feedback should be directed to commons-user at jakarta.apache.org.

### COMPATABILITY

This release is fully source and binary compatible with v3.0. (Checks performed using JDiff and Clirr, thanks).

The only new deprecations are in AbstractDualBidiMap. These only impact non commons-collections subclasses, and existing code will still work.

This release also enables a workaround of the binary compatability issue with IteratorUtils in v3.0. Collections v2.1.1 (with deprecations solved) and v3.1 are compatible with regards to iterators.

### NEW CLASSES

- TreeList - A list implementation that is faster than ArrayList for insertions and removals
- MultiKeyMap - A map that allows multiple keys to be used to map the value
- SingletonMap - fully featured singleton Map implementation
- ObjectGraphIterator - An iterator that can iterate over a graph of objects
- MapBackedSet - Set created by decorating a map
- ReferenceIdentityMap - Similar to ReferenceMap, but matching keys and values by identity [26503]
- AbstractReferenceMap - New base class for reference maps [26503]
- Empty*Iterator - Iterators over empty collections
- TransformedPredicate - A predicate where the input object is transformed [26946]
- PredicateDecorator - An interface to provide a uniform interface to the decorated predicates
- AbstractSerializable*Decorator - Abstract classes for decorators that are Serializable

### ENHANCEMENTS

- ReferenceMap - Changed to extend AbstractReferenceMap, thus gaining a mapIterator() and subclassability [26503]
- Fast3Map - Add clone() method
- MultiKey - Add getKey(index) and size() methods and make constructor public
- MultiHashMap - Add five methods to improve the API
- AbstractHashedMap,AbstractLinkedMap - Add methods to access entry methods when protected scope blocks
- Functors - Add get methods to retrieve internal state [27515]
- Functors - Add additional getInstance() methods for consistency [27856,27857]
- CollectionUtils - get(Object,int) method now supports primitive arrays
- CollectionUtils - cardinality() now works faster for Set and Bag instances [28629]
- CollectionUtils - Add size(Object) method to find the size of various collection-like objects [27909]
- SingletonIterator - make remove() functionality optional
- AbstractLinkedList/NodeCachingLinkedList - added getValue() and setValue() to Node, and made everything use them
- LRUMap - The addMapping() method now uses isFull() to determine whether it is full
- LRUMap - Add boolean flag, scanUntilRemovable, giving the removeLRU() method more power [28887]
- InvokerTransformer - Add additional getInstance() method
- Reduced inter-class and inter-package dependencies, especially via *Utils classes
- ListOrderedSet - Add new factory method decorate(Set,List)
- ListOrderedSet - Add public constructor that uses a HashSet and ArrayList
- ListOrderedMap - Add public constructor that uses a HashMap and ArrayList

#### Made Serializable

- Fast3Map [27946]
- ReferenceMap
- UnboundedFifoBuffer
- BoundedFifoBuffer
- CircularFifoBuffer
- TiedMapEntry
- FixedSize* [18815]
- Predicated* [18815]
- Synchronized* [18815]
- Transformed* [18815]
- Typed* [18815]
- Unmodifiable* [18815]
- Lazy* [18815]
- ListOrdered* [18815]
- SetUniqueList [18815]

### BUG FIXES

- Map/BidiMap implementations only checked key and not value in entry set contains(Object) and remove(Object)
- AbstractHashedMap subclasses failed to clone() correctly [27159]
- ExtendedProperties - Close input stream in constructor [27737]
- ExtendedProperties - Handle comma separated data in multiple keys
- Flat3Map - Handle infinite loops in toString
- LRUMap - The removeLRU() method was passed the wrong LinkEntry [28433]
- EnumIterator/MapUtils - Changed enum references to enable JDK 1.5 compliance
- UnmodifiableSortedBag - Fix to ensure unmodifiable
- MultiHashMap - Fix copy constructor and clone to work properly [28972]
- ListOrderedSet - Fix to throw IllegalArgumentException instead of NPE on null factory decorate(List)
- *Dual*BidiMap - Fix poorly designed subclass method call from superclass constructor [29519]

### JAVADOC

- Bag - Indicate that no changes are likely to the interface despite its problems
- TreeBidiMap - Add javadoc about requiring Comparable entries [26470]
- MultiKey - Add extra explanatations, examples and warnings
- MultiMap,MultiHashMap - Add extra documentation to clarify the interface and implementation
- XxxUtils - Clarify the internal workings of the predicated decorator classes [28115]
- BidiMap - Clarify 1 to 1 nature of the map
- AbstractHashedMap - Fix isEqualValue() javadoc to refer to value not key
- LRUMap - Added extra javadoc about method implementations
- BoundedCollection/UnmodifiableBoundedCollection - reword to avoid misunderstandings
- Closure/Predicate/Transformer/Factory - Additional javadoc with links
- ClosureUtils/PredicateUtils/TransformerUtils/FactoryUtils - Additional links to implementations
- Predicated* - Additional usage explanation [29018]