来自Guava的@CompatibleWith注释的目的是什么？

Question

From the documentation of com.google.errorprone.annotations.CompatibleWith :

Declares that a parameter to a method must be "compatible with" one of the type parameters in the method's enclosing class, or on the method itself. "Compatible with" means that there can exist a "reference casting conversion" from one type to the other (JLS 5.5.1).

For example, Collection.contains(java.lang.Object) would be annotated as follows:

 interface Collection<E> { boolean contains(@CompatibleWith("E") Object o); } 

To indicate that invocations of Collection.contains(java.lang.Object) must be passed an argument whose type is compatible with the generic type argument of the Collection instance:

Here is a usage from com.google.common.cache.Cache :

public interface Cache<K, V> {

    V getIfPresent(@CompatibleWith("K") Object key);

    V get(K key, Callable<? extends V> loader) throws ExecutionException;
...

What is the benefit of having @CompatibleWith("E") Object instead of E as the type of the parameter? And why did they use the @CompatibleWith annotation in the getIfPresent but not in the get method from Cache?

Answer 1

It's safe for getIfPresent operation to allow objects of "too broad" type (you don't get anything from cache with string keys from getIfPresent(42) ). On the other hand, for hypothetical get(Object, Callable) allowing inserting an object of wrong type (eg. 42 instead of a string "foo" ) would damage the underlying collection, that's why you have compile time checking won't allow it.

Having said that, this code:

Cache<String, Foo> cache = CacheBuilder.newBuilder()
// and later
Foo value = cache.getIfPresent(42);

is most probably wrong, and it makes sense for framework like Error Prone to signal that as a possible bug.

More detailed clarification about "use Object not generic type in safe operations" convention (which isn't used only in Guava, but also in JDK collections framework) is explained in this old, but still relevant blog post "Why does Set.contains() take an Object, not an E?" , where you read:

Why should code like the following compile?

 Set<Long> set = new HashSet<Long>(); set.add(10L); if (set.contains(10)) { // we won't get here! } 

We're asking if the set contains the Integer ten; it's an "obvious" bug, but the compiler won't catch it because Set.contains() accepts Object . Isn't this stupid and evil?

and later answers the question in title:

The real difference is that add() can cause "damage" to the collection when called with the wrong type, and contains() and remove() cannot.

The conclusion is also relevant:

Static analysis plays an extremely important role in the construction of bug-free software.

Which makes sense, because the author, Kevin Bourrillion, is also lead developer of Guava.