Java Collections API Quirks

Posted on by lukaseder
So we tend to think we’ve seen it all, when it comes to the Java Collections API. We know our ways around Lists, Sets, Maps, Iterables, Iterators. We’re ready for Java 8’s Collections API enhancements. But then, every once in a while, we stumble upon one of these weird quirks that originate from the depths of the JDK and its long history of backwards-compatibility. Let’s have a look at unmodifiable collections

Unmodifiable Collections

Whether a collection is modifiable or not is not reflected by the Collections API. There is no immutable List, Set or Collection base type, which mutable subtypes could extend. So, the following API doesn’t exist in the JDK: 

// Immutable part of the Collection API
public interface Collection {
  boolean  contains(Object o);
  boolean  containsAll(Collection<?> c);
  boolean  isEmpty();
  int      size();
  Object[] toArray();
  <T> T[]  toArray(T[] array);
}

// Mutable part of the Collection API
public interface MutableCollection 
extends Collection {
  boolean  add(E e);
  boolean  addAll(Collection<? extends E> c);
  void     clear();
  boolean  remove(Object o);
  boolean  removeAll(Collection<?> c);
  boolean  retainAll(Collection<?> c);
}
Now, there are probably reasons, why things hadn’t been implemented this way in the early days of Java. Most likely, mutability wasn’t seen as a feature worthy of occupying its own type in the type hierarchy. So, along came the Collections helper class, with useful methods such as unmodifiableList(), unmodifiableSet(), unmodifiableCollection(), and others. But beware when using unmodifiable collections! There is a very strange thing mentioned in the Javadoc:
The returned collection does not pass the hashCode and equals operations through to the backing collection, but relies on Object’s equals and hashCode methods. This is necessary to preserve the contracts of these operations in the case that the backing collection is a set or a list.
“To preserve the contracts of these operations”. That’s quite vague. What’s the reasoning behind it? A nice explanation is given in this Stack Overflow answer here:
An UnmodifiableList is an UnmodifiableCollection, but the same is not true in reverse — an UnmodifiableCollection that wraps a List is not an UnmodifiableList. So if you compare an UnmodifiableCollection that wraps a List a with an UnmodifiableList that wraps the same List a, the two wrappers should not be equal. If you just passed through to the wrapped list, they would be equal.
While this reasoning is correct, the implications may be rather unexpected.

The bottom line

The bottom line is that you cannot rely on Collection.equals(). While List.equals() and Set.equals() are well-defined, don’t trust Collection.equals(). It may not behave meaningfully. Keep this in mind, when accepting a Collection in a method signature: 

public class MyClass {
  public void doStuff(Collection<?> collection) {
    // Don't rely on collection.equals() here!
  }
}

Published by lukaseder

I made jOOQ

2 thoughts on “Java Collections API Quirks”

  1. Not to provide unmodifiable collections was a deliberate design decision: http://docs.oracle.com/javase/6/docs/technotes/guides/collections/designfaq.html#1
    Regarding equals(), I tend to think of collection equality as use-case dependent, especially for lists. Sometimes one needs the “strong” equals() as defined in the JavaDoc, sometimes a “weaker” one (eg. same items, but not necessarily in the same order) will do. As a consequence I implement a Comparator in order to compare two collections to make the details of the comparison explicit.
    Bottom line: no quirks, but careful decisions where no one-size-fits-all solutions were possible.

    Reply

    1. Thanks for the link about the design decision. I was too lazy to look that up :-)

      I personally tend to feel that collection equality should be implemented by default through “iteration equality”. I.e. two collections are equal if their Iterators return the same amount of equal objects. Subtypes could then further refine such a contract, although I don’t quite understand the point of the current List and Set contracts. In fact, I don’t think that List and Set deserve their own types. They’re both just specific Collection implementations. get(int) and other methods should be moved up to Collection, as that method, too, can be defined through iteration behaviour… But that’s just me, around 20 years late ;-)

      I like the Comparator idea. Given the current situation, a bit of explicitness won’t do any harm…

      Reply

Leave a Reply