I think the class JavaDoc should give a better answer here.
In general, I think the JavaDoc at Cache should be heavily extended. It doesn't cater for the fact that it is the main entry point for every new developer. Most developers will probably never read the introduction in the Spec.
Simple but good question on StackOverflow: When to use Java Cache and how it differs from HashMap
I think the class JavaDoc should give a better answer here.
In general, I think the JavaDoc at
Cacheshould be heavily extended. It doesn't cater for the fact that it is the main entry point for every new developer. Most developers will probably never read the introduction in the Spec.