Collections – User guide

User guide

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

Utilities for the standard collections.
Maps
Bags
Bloom filters (starting in 4.5.0)

Note On Synchronization

Commons-collections uses a design approach to synchronization similar to the standard Java collections. The majority of the various implementations of collections, maps and bags are not thread safe without additional synchronization. The appropriate synchronizeXXX method on Collections is one way that these implementations can be synchronized for use in a multithreaded application.

The class level javadocs should indicate whether a particular implementation is safe for multithreaded access without additional synchronization. Where there is no explicit indication that the implementation is thread safe then it should be assumed that synchronization is required. Please report the missing documentation to the commons development team.

Utilities

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.

Maps

Map Iteration

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);
}

Ordered Maps

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"

Bidirectional Maps

A new interface hierarchy has been added to support bidirectional maps - BidiMap. These represent maps where the key can lookup the value and the value can look up 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.

Bags

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.