Clarify Cache Javadoc for behavior on null

[GoogleCodeExporter]

If you build a cache without a CacheLoader

Cache cache = CacheBuilder.newBuilder()
    .concurrencyLevel(10)
    .maximumSize(500)
    .expireAfterWrite(2, TimeUnit.HOURS)
    .build();

and when try to retieve an element with a null key

String key = null;
...
o = cache.getIfPresent(key);

The Cache throws a NullPointerException

java.lang.NullPointerException
        at com.google.common.base.Preconditions.checkNotNull(Preconditions.java:187)
        at com.google.common.cache.LocalCache.getIfPresent(LocalCache.java:3953)
        at com.google.common.cache.LocalCache$LocalManualCache.getIfPresent(LocalCache.java:4758)

It could be great to be able to create a cache that doesn't return NPE but just 
return a null value, maybe using something like this:

Cache cache = CacheBuilder.newBuilder()
    .concurrencyLevel(10)
    .maximumSize(500)
    .expireAfterWrite(2, TimeUnit.HOURS)
    .allowNullKey()
    .build();

Also this info should be added to the javadoc on the getIfPresent() method: If 
the key is null, then the cache will throw a NullPointerException.

Original issue reported on code.google.com by jmsa...@gmail.com on 11 Jan 2012 at 7:38

[GoogleCodeExporter]

Cache very deliberately fails fast with an NPE rather than permitting null 
values.  This behavior could be made clearer in the Javadoc, however.

Original comment by wasserman.louis on 11 Jan 2012 at 7:48

• Changed title: Clarify Cache Javadoc for behavior on null
• Changed state: Triaged
• Added labels: Type-Documentation

[GoogleCodeExporter]

A slight issue with this is that Cache is an interface...and it specifically 
says "The implementation may support null as a valid cached value, or may 
return null without caching it, or may not permit null results at all."

The implementation of Cache that you get when you use CacheBuilder (a 
ComputingCache) does *not* support null values (as you saw), but it's not clear 
where the best place to mention that would be.  CacheLoader does mention that 
it can never load a null value.

I'll let Charles decide where, if at all, it's appropriate to mention this.

Original comment by kurt.kluever on 11 Jan 2012 at 8:40

• Added labels: Package-Cache

[GoogleCodeExporter]

Kurt's response has more to do with null *values*, not null keys.

We don't have any intention of either supporting null keys in caches or adding 
a "feature" that would return null if you ask for a null key. It's much better 
to do something like this:

  return (key == null) ? null : cache.get(key);

As far as javadoc, we made a global decision long ago that ALL methods throw 
NPE on null input, except when the parameter is marked @Nullable -- this saves 
us a *lot* of time and space in docs.

Is there anything else you were asking about?

Original comment by kevinb@google.com on 30 Jan 2012 at 6:22

• Changed state: WorkingAsIntended

[GoogleCodeExporter]

This issue has been migrated to GitHub.

It can be found at https://github.com/google/guava/issues/<id>

Original comment by cgdecker@google.com on 1 Nov 2014 at 4:14

• Added labels: MigratedToGitHub

[GoogleCodeExporter]

Original comment by cgdecker@google.com on 3 Nov 2014 at 9:09

• Added labels: Restrict-AddIssueComment-Commit