Tutorial: Coding With Google Collections


The Google Collections library (or just Google Collections) is an extension to the Java Collections Framework[1]. As the name implies, it’s developed and maintained by Google. The library is available under the Apache 2.0 license and can be downloaded from Google Code Hosting[2].

Google’s mission with their Collections library is to provide a set of new Collection types and implementations with a stable API, just like the JDK does. It’s mostly developed with Google’s needs in mind, as well as with the notion to strongly adhere to the Java Collection Framework’s contracts.

The project’s inception was in 2007 and it took Google quite a while to get it to a final release, which was a couple of weeks ago[3]. Although Google couldn’t promise a stable API until a final release, Google Collections gained a lot of traction even in earlier versions.

Get The Sample Code

You can download all code sample presented here in a prepackaged maven-based project from github[4]. It uses the latest Google Collections release, which is 1.0 at the time of writing. Everything presented here is available in a JUnit TestCase, which you can run using Maven or your favorite IDE.

Utility Classes

Google Collections provides a bunch of really helpful utility classes and methods, which save a ton of boilerplate code. The first example shows how to instantiate a generified Map with the traditional means of Java’s Collections Framework:

Google Collections’ utility classes combined with static imports, make things a lot easier:

Note here, that you don’t get any compiler warnings about unchecked assignments. Google made sure that their library is nicely generified and type-safe. These utility classes with their factory methods are also available for java.util.List and Map.

A common pattern when writing unit tests is to instantiate a List and add a couple of fixtures to it, which are being used later on in the test to assert correct results. Let’s take a look at an example:

Google Collections provides a neat List type, which makes it even easier to instantiate your fixtures and make them immutable to ensure correct results when asserting your data:

ImmutableList and its siblings ImmutableMap and ImmutableSet not only provide a view on a Collection, which is what you get when you are using Collections.unmodifieableList(), but a really immutable Collection, which will never change.

Enhanced Collection Types

The Google Collections library provides a set of enhanced Collections types and implementations. Next to the immutable types, there’s another interesting category – the Multimap types. A Multimap implementation allows duplicate key value pairs. It is quite tricky to achieve this kind of behavior with the tradition means of the Java Collections Framework:

  Using Google Collections’ Multimap implementation associating multiple values with one key is easy. It also lets you retrieve all the values of particular key and convert it back to a traditional java.util.Map:

  A common problem where this type of Collection might be useful, is associating information with a particular type where it’s not reasonable to create a wrapper class. One example could be associating various information about a User to display it on a website.

There’s also a non immutable counterpart to this type of Multimap, just in case you were wondering. Although the name indicates the use of a map-like data structure, there’s also a List and Set implementation of the Multimap type.

Functional Goodies

The Google Collections library comes complete with a couple of goodies, resembling a functional approach. If you are familiar with, for example, Groovy, then the following code should be everyday business for you. There’s classes to define functions and utility classes to transform traditional or Google’s Collections, using those functions. Let’s take a look at an example:

The Google Collections’ utility class Lists provides a method called transform, which lets you pass in a List and a Function implementation, to return a transformed view of a List. Everything is generified here, too. Function defines the type it expects as well as the type it’s going to return. The return type of the Function yields the type of the transformed List.

With the utility class Ordering, you can even order the results of the transformation. The transform method is also available on the utility class Maps. Unfortunately, there is no equivalent for Sets.

Another really neat Google Collections utility class providing some functional-esque methods for List and Set implementations, is Iterables:

With Iterables you can provide a simple type-safe search functionality. Furthermore, there’s also a method which lets you filter a List or Set, based on a Predicate:

terables has even more utility methods resembling a functional approach. It lets you combine two or more Iterables and provides methods to partition or remove elements from an Iterable.


The Google Collections library provides practical solutions for many problems developers face every day. Those solutions are well-designed, tested and approved by a huge community of developers. Since Google is using the library for their internal codebase, it’s unlikely that they drop support for it. With the final release, which brings a stable API, Google Collections is ready for mission critical applications.

Inline Feedbacks
View all comments