Deleted unwanted methods, added Javadoc to the ones we keep

May want to check the javadoc there... It's probably less than ideal. Maybe we should pull in the docs team on that?
Also, review the comments on the `Cache` interface... am unsure about some methods there
Yes - I think we do.  JSR-107 has this too.  One thing I'd like to avoid is this becoming mutable in the way that Map.Entry is.