Commons Collections - Users guide Commons Documentation Team

Commons-Collections provides a large number of classes to aid day to day programming. This document highlights some key features to get you started.

A Utility class is provided for each major collection interface. Thus, the Set and SortedSet interfaces are provided for by SetUtils. These classes provide useful methods for working with that collection type.

The most methods are found on the two 'root' collection utility classes - CollectionUtils and MapUtils. As all other collection interfaces extend Collection or Map these utilities can be used widely. They include intersection, counting, iteration, functor and typecasting operations amongst others. The utility classes also provide access to collection decorator classes in a way similar to the JDK Collections class.

The JDK Map interface always suffered from being difficult to iterate over. API users are forced to either iterate over an EntrySet or over the KeySet. Commons-Collections now provides a new interface - MapIterator that allows simple iteration over maps.

IterableMap map = new HashedMap(); MapIterator it = map.mapIterator(); while (it.hasNext()) { Object key = it.next(); Object value = it.getValue(); it.setValue(newValue); }

A new interface is provided for maps that have an order but are not sorted - OrderedMap. Two implementations are provided - LinkedMap and ListOrderedMap (a decorator). This interface supports the map iterator, and also allows iteration both forwards and backwards through the map.

OrderedMap map = new LinkedMap(); map.put("FIVE", "5"); map.put("SIX", "6"); map.put("SEVEN", "7"); map.firstKey(); // returns "FIVE" map.nextKey("FIVE"); // returns "SIX" map.nextKey("SIX"); // returns "SEVEN"

A new interface hierarchy has been added to support bidirectional maps - BidiMap. These represent maps where the the key can lookup the value and the value can lookup the key with equal ease.

BidiMap bidi = new TreeBidiMap(); bidi.put("SIX", "6"); bidi.get("SIX"); // returns "6" bidi.getKey("6"); // returns "SIX" bidi.removeValue("6"); // removes the mapping BidiMap inverse = bidi.inverseBidiMap(); // returns a map with keys and values swapped

Additional interfaces are provided for ordered and sorted bidirectional maps. Implementations are provided for each bidirectional map type.

A new interface hierarchy has been added to support queues and buffers - Buffer. These represent collections that have a well defined removal order.

Buffer buffer = new UnboundedFifoBuffer(); bidi.add("ONE"); bidi.add("TWO"); bidi.add("THREE"); bidi.remove(); // removes and returns the next in order, "ONE" as this is a FIFO bidi.remove(); // removes and returns the next in order, "TWO" as this is a FIFO

Implementations are provided for FIFO (queue), LIFO (stack) and Priority (removal in comparator order).

A new interface hierarchy has been added to support bags - Bag. These represent collections where a certain number of copies of each element is held.

Bag bag = new HashBag(); bag.add("ONE", 6); // add 6 copies of "ONE" bag.remove("ONE", 2); // removes 2 copies of "ONE" bag.getCount("ONE"); // returns 4, the number of copies in the bag (6 - 2)

Implementations are provided for both unsorted and sorted Bags.