// this is easy since everything are Strings
scala> List("one", "two", "three")
res0: List[java.lang.String] = List(one, two, three)

scala> res0.foreach(x => println(x.length()))
3
3
5

// with a mixed collection it gets harder
scala> List("one", 2, "three", 4.0)
res2: List[Any] = List(one, 2, three, 4.0)

scala> res2.foreach(x => println(x.length()))
<console>:6: error: value length is not a member of Any

// it is not enough to just filter out the objects that are Strings
scala> res2.filter(_.isInstanceOf[String])
res4: List[Any] = List(one, three)

// as we still have a List of Any
scala> res4.foreach(x => println(x.length()))
<console>:7: error: value length is not a member of Any

// both filtering and mapping is needed
scala> res2.filter(_.isInstanceOf[String]).map(_.asInstanceOf[String])
res6: List[String] = List(one, three)

// finally it works
scala> res6.foreach(x => println(x.length()))
3
5

// another option is to use pattern matching
scala> res2.foreach(_ match { case x:String => println(x.length); case _ => })
3
5

I wanted a more elegant solution with less boiler plate so after playing around with implicit conversions and reified types I managed to come up with rather nice solution:

// define a class that implements a restrictTo method
scala> class IterableWithRestrictTo[A](from:Iterable[A]) {
     | def restrictTo[B](implicit m: scala.reflect.Manifest[B]) = {
     | from.filter(m.erasure.isInstance(_)).map(_.asInstanceOf[B])
     | }
     | }
defined class IterableWithRestrictTo

// define implicit conversion
scala> implicit def makeIterableWithRestrictTo[A](from : Iterable[A]) = {
     | new IterableWithRestrictTo(from)
     | }
makeIterableWithRestrictTo: [A](from: Iterable[A])IterableWithRestrictTo[A]

scala> List("one", 2, "three", 4.0)
res0: List[Any] = List(one, 2, three, 4.0)

// restrict to objects of type String
scala> res0.restrictTo[String]
res1: Iterable[String] = List(one, three)

// works since the collection have correct type
scala> res1.foreach(x => println(x.length()))
3
5

Using the name restrictTo clearly shows that not only is there a type conversion, but also a restriction to a subset of the elements. Notice that the manifest is needed to get the reified type, since the type B is actually erased at compile time. Read more about reified types in Scala.

Let me know you have another solution!

Here is a list of useful facts before we throw ourselves into the code.

• Open Source Apache 2 library
• Hosted at Google Code: http://google-collections.googlecode.com/
• Requires Java 1.5
• 1.0 Release Candidate 3 now
• 25,000 unit tests
• Used by Google in production

Immutable Collections

A big part of the collections library is focused on immutability, the reason for this is the increased demand for concurrent code in order to be able to utilize the ever increasing number of cores in modern computers.

Immutable data are thread-safe because it can never be changed and can therefore be shared between multiple threads without worrying. This is a huge improvement because of the complexity involved writing thread safe code that uses mutable data. furthermore immutable data can be handed to untrusted code without worrying about the data being changed by the untrusted code, this really helps sustaining the security boundaries of your system.

Another benefit of using immutable collections is that they are in most cases more memory efficient and perform better than the regular collections.

In a way it was also possible to create immutable collections with the standard Java API, as an example a set could be made immutable the following way:

 
Set<Integer> numbers = new TreeSet<Integer>(Arrays.asList(0,1,2,3,4,5,6,7,8,9));
Set<Integer> immutableNumbers = Collections.unmodifiableSet(numbers);
 

With Google Collections it would look the following way:

 
ImmutableSet<Integer> immutableNumbers = ImmutableSet.of(0,1,2,3,4,5,6,7,8,9);
 

There are several things that are better in the version using Google Collections. You only need to know about the ImmutableSet class, where as in the standard Java version, four classes are combined to achieve the same effect, that is just confusing. When using the new keyword to construct generic classes, the generic type can't be inferred from the constructor arguments, this limitation is not present for methods. Google Collections uses static factory methods to create their collections meaning the generic type will be inferred in this case and therefore turning the code noise down. The third benefit is that the immutable collections are guaranteed to be immutable where as an unmodifiable collection is just an immutable view of the collection and can be changed by code holding a reference to the actual collection. The last benefit is that the information about immutability is captured in the type and clients of this type therefore will be able to count on that the collection is immutable, which means that defensive copying is unnecessary. Be aware that it is only the collection that is promised to be immutable, if the objects contained in the collection are not immutable they can still be changed. Notice that ImmutableSet implements the Set interface so it can be used seamlessly with existing code.

Those of you who are familiar with functional programming languages, may expect, that mutating methods like add returns a modified copy of the collection. But in order to implement the standard Java collections interfaces, this is not possible, so instead they just throw an exception. You can of cause still combine existing immutable collections into new ones. If you for example want to create the union of two sets, you can do it the following way:

 
ImmutableSet<Integer> lowNumbers = ImmutableSet.of(0,1,2,3,4,5,6,7,8,9);
ImmutableSet<Integer> highNumbers = ImmutableSet.of(5,6,7,8,9,10,11,12,13,14,15);
SetView<Integer> union = Sets.union(lowNumbers, highNumbers);
 

Notice how we use the static union method on the Sets class to create a new SetView based on the two given sets. The SetView is an unmodifiable implementation of the standard Set interface but can change if the underlying collections changes. Google Collections provide similar convenience classes for working with all the popular collections interfaces from the standard Java API, improving your productivity a lot.

Numerous immutable collections exist in the library, for more information see the API documentation.

New collections types

Google Collections also provides implementations of a few collections that is not included in the standard Java. These collections can be very useful in special cases.

Multisets

Multiset is a very useful collection for collecting statistic data of some kind. The collection is basically just a set where a count of how many instances has been added of each element is maintained. So if we as an example want to count the occurrences of each number in a list of numbers it can be done the following way.

 
ImmutableList<Integer> numbers = ImmutableList.of(2,3,0,1,0,1,2,3,2,3);
Multiset<Integer> multiset = TreeMultiset.create(numbers);
multiset.remove(0); // Decreasing the count for 0 by 1
multiset.add(1, 4); // Increasing the count for 1 by 4
 

The resulting multiset after adding the list of numbers contains to following information:

• 0 has 1 occurrences
• 1 has 6 occurrences
• 2 has 3 occurrences
• 3 has 3 occurrences

Numerous implementations of the Multiset exists, so it is a good idea to match your requirement against the capabilities of the different implementations before choosing one.

Multimaps

Have you ever implemented a Map where each key could be associated to a list of values - that's exactly what a Multimap is. This is useful in many cases, for example indexing. To show the functionality I'll index fruits by colors. The Fruit class is just a class with a name and a color and the fruits collection contains banana, strawberry, cucumber, kiwifruit, tomato and lemon. First we create a new multimap for the color index, then we look through all the fruits and add them to the color index using the color of the fruit as index. After we have constructed the index, we get a collection of red fruits using the get method. And finally, we assert that a tomato is a red fruit.

 
Multimap<Color, Fruit> colorIndex = HashMultimap.create();
for (Fruit fruit : fruits) {
    colorIndex.put(fruit.getColor(), fruit);
}
Collection<Fruit> redFruits = colorIndex.get(Color.RED);
assertTrue("Tomato is a red fruit", redFruits.contains(TOMATO));
 

BiMap

A BiMap is an implementation of a bidirectional map, that is a map where a one-to-one relation between each key and value exists. The BiMap is special because it is capable of producing the inverse mapping using the inverse method. Bidirectional maps are also useful for indexing in cases where an one-to-one relationship exists and you don't want the relationship encoded in the objects. As an example we will look at mapping numbers to their names and back again.

 
ImmutableBiMap<Integer, String> biMap = ImmutableBiMap.of(0, "Zero", 1, "One",
        2, "Two", 3, "Three");
assertEquals("2 should be mapped to Two", "Two" , biMap.get(2));
 

We can easily create a mapping between the numbers and their names using the of method on the ImmutableBiMap implementation. As with the Multisets and Multimaps numerous implementations exists to fit your exact needs.

For a BiMap we can get the inverse BiMap the following way:

 
BiMap<String, Integer> inverseBiMap = biMap.inverse();
assertEquals("Two should be mapped to 2", Integer.valueOf(2),
        inverseBiMap.get("Two"));
 

Ordering

If you ever have struggled with implementing Java's Comparator interface the Ordering class from Google Collections is you friend. The Ordering class provides you with everything you need for handling ordering of collections. Furthermore the Ordering class implements the Comparator interface to handle backwards compatibility. If you, for example, want to sort the fruits earlier mentioned first by color then by name it can be done the following way.

 
Function<Fruit, Color> getColorFunction = new Function<Fruit, Color>() {
    public Color apply(Fruit from) {
        return from.getColor();
    }
};
 
Function<Fruit, String> getNameFunction = new Function<Fruit, String>() {
    public String apply(Fruit from) {
        return from.getName();
    }
};
 
Ordering<Fruit> colorOrdering = Ordering.natural().onResultOf(getColorFunction);
Ordering<Fruit> nameOrdering = Ordering.natural().onResultOf(getNameFunction);
 
Ordering<Fruit> colorAndNameOrdering = colorOrdering.compound(nameOrdering);
 
ImmutableSortedSet<Fruit> sortedFruits = ImmutableSortedSet.orderedBy(
        colorAndNameOrdering).addAll(fruits).build();
 
System.out.println(Joiner.on(", ").join(sortedFruits));
 

Prints out:

Green Cucumber, Green Kiwifruit, Red Strawberry, Red Tomato, Yellow Banana,
Yellow Lemon

First I create the ordering of fruits by color. The Color enumeration implements Comparable, so we just want to promote the ordering of fruits to use the natural order of the Color class. To do this we create a natural order on the result of the function that retrieves the color from a fruit. To verify that the ordering works, I create a new ImmutableSortedSet with the ordering we just created and print the result. Notice that it is necessary to used the builder pattern in order to create the ImmutableSortedSet with a specified order.

The ordering on fruit names is similar to the way we order by colors except we use a function that retrieves the name of the fruit.

When we have the two orderings we can make a compound ordering by using the compound method on the ordering that should be applied first. A compound ordering applies each ordering in turn to achieve a hierarchical ordering. In this case the color-ordering is first applied, if the objects are equal, according to that ordering, the naming-ordering is applied.

Another use case of the Ordering class is sorting Iterable classes where elements are not guaranteed to be unique. Normally you would have to first convert the iterable to a list and then use the sort method on the Collections class to sort the elements. Consider the case of sorting an iterable of numbers in reverse order, this can be done the following way in standard Java:

 
List<Integer> sortedNumbers = new ArrayList<Integer>(numberIterable);
Collections.sort(sortedNumbers, Collections.reverseOrder());
 

The same result can be achieved with Google Collections the following way:

 
List<Integer> sortedNumbers = Ordering.natural().reverse().sortedCopy(numberIterable);
 

This doesn't seem like a big difference. But in the standard Java example involves three different classes and the generics is specified two times.

Iterables and Iterators

Iterables and iterators are a powerful abstraction that lets you handle streams of data in an uniform way. But the standard Java library doesn't provide you with many tools to handle these types. Google Collections includes two classes with several convenience methods to work on these types. The two classes contains the same methods so I'll only focus on iterables.

Imagine that you are given an iterable of numbers should find all the even numbers, square them and return a new iterable of the result. Of course this should be done without reading all the numbers in the given iterable. In standard Java you would need to implement two iterators and two iterables in order to achieve this. In Google Collection it can be done the following way:

 
Predicate<Integer> evenPredicate = new Predicate<Integer>() {
    public boolean apply(Integer input) {
        return input % 2 == 0;
    }
};
 
Iterable<Integer> evenNumbers = Iterables.filter(numbers, evenPredicate);
 
Function<Integer, Integer> squareFunction = new Function<Integer, Integer>() {
    public Integer apply(Integer from) {
        return from * from;
    }
};
 
Iterable<Integer> squareOfEvenNumbers = Iterables.transform(evenNumbers,
        squareFunction);
 

First we create a predicate function that only accepts even numbers and filters the given numbers by this predicate function. Notice this is done lazily so the original iterable is not touched, which means at no time is a collection containing all the results constructed and stored in memory. All the methods on Iterables and Iterators classes is as lazy as possible.

Then we create a square function and apply it to the iterable of even numbers giving us a new iterable with the squared even numbers.

It is important to understand that the predicate and square functions will first be applied when the iterable is used to iterate through the squared even numbers.

Conclusion

In my opinion Google Collection will definitely improve your code, making it more readable and save you from creating your own error-prone implementation of the functionality already provided and tested by Google. I think that it is especially good that the library extends the standard library in a non intrusive way, instead of creating a parallel collection library. This also means that you can choose to use only the convenience classes and not spreading Google specific types all over your system if that worries you.