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