Java Collections API Change Summary

We received hundreds of excellent suggestions concerning previous releases of the collections API. Suggestions came from companies, universities, and individuals all around the world. We're truly thankful for these suggestions, and we've incorporated many of them. This page summarizes the differences between the Beta3 and Beta4 releases, along with a brief rationale for each change.

The changes are modest compared to previous Beta releases. The biggest news is that the "subList" functionality has been "promoted" from the Collections class into the List interface. Also, we've added a few more polymorphic algorithms to the Collections class, and a special-purpose implementation of the Map interface that stores only weak references to its keys.

Core Collection Interfaces - List

Added subList method, which returns a List view of a contiguous portion of the List. (This functionality was previously provided by an identically named "factory method" in the Collections class, which has been eliminated.) Adding this method to the List interface allowed us to eliminate three other methods (removeRange, indexOf(Object, int), and lastIndexOf(Object, index)). In addition to reducing the size of the List interface, this change provides a single (and powerful) form for all range operations, allows sublists to detect harmful modifications of the backing List, and allows for greatly increased performance of many sublist operations.

Core Collection Interfaces - Map

Renamed entries method to entrySet. This provides consistency with keySet. (Now both of the Set returning methods have names ending in "Set".)

Concrete Implementations

Added WeakHashMap, a special-purpose implementation of the Map interface that stores only weak references to its keys, which allows key-value pairs to be garbage-collected when the key is no longer referenced outside of the WeakHashMap. This class provides the easiest way to harness the power of weak references. It is useful for implementing "registry-like" data structures, where the utility of an entry vanishes when its key is no longer reachable by any thread.
Eliminated the notion of "capacity increment" from ArrayList This feature (which allowed users to specify a linear growth increment) was of questionable utility, restricted implementors' choices, and complicated the API unnecessarily. The only affected method is the constructor ArrayList(int initialCapacity, int capacityIncrement), which was eliminated.

Algorithms and Convenience Implementations

Added several new algorithms. Adding these common utility algorithms will save programmers the trouble of "reinventing the wheel" each time they need to perform one of these operations:
- fill(List, Object) - Overwrites every element in a List with the specified value.
- copy(List dest, List src) - Copies the source List into the destination List.
- reverse(List) - Reverses the order of the elements in the a List.
- shuffle(List) - Randomly permutes the elements in a List.
Added singleton "factory method", which returns an immutable singleton Set containing a specified object. This is useful, for instance, in the following one-liner, which removes all occurrences of a specified key from a collection:
```
    c.removeAll(Collections.singleton(o));
```
Added EMPTY_SET and EMPTY_LIST constants. These constants will save programmers the trouble of providing their own, and they offer a standard appearance for these fairly commonly used values.
Replaced REVERSE_ORDER constant by reverseOrder method. This change enables possible enhancements in the type system that are being considered for the future.

Array Operations

Added range versions of the fill calls. These calls, which will eventually be implemented as native methods, are useful for high speed image processing.
Renamed toList to asList. The new name emphasizes the fact that this method provides an aliased "view" of its array argument, rather than a copy.
Modified signatures of equals methods from:
```
    public static boolean equals(<type>[], Object);
```
to:
```
    public static boolean equals(<type>[], <type>[]);
```
The new signatures are less confusing, and the methods run faster as they type check their second argument statically at compile time.

Please send comments to: collections-comments@java.sun.com

Java Software