JDK-7166055 : Javadoc for WeakHashMap contains misleading advice
  • Type: Enhancement
  • Component: core-libs
  • Sub-Component: java.util
  • Affected Version: 7
  • Priority: P4
  • Status: Closed
  • Resolution: Fixed
  • OS: linux
  • CPU: x86
  • Submitted: 2012-05-03
  • Updated: 2013-06-26
  • Resolved: 2012-09-05
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 7 JDK 8
7u40Fixed 8 b43Fixed
Description
A DESCRIPTION OF THE PROBLEM :
In the "Implementation note:" the last sentence states:
"One way to deal with this is to wrap values themselves within WeakReferences before inserting, as in: m.put(key, new WeakReference(value)), and then unwrapping upon each get."
However, it misleads the user because the value can be GC'd if there are no strong reference to the value. We think a couple more sentences should be added for this scenario.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
One way to deal with this is to wrap values themselves within WeakReferences before inserting, as in: m.put(key, new WeakReference(value)), and then unwrapping upon each get. However, as the use of WeakReference in this manner will not prevent value objects from being GC'd, this approach is only useful when entries in the map are not relied upon for keeping the underlying value objects "live".
ACTUAL -
One way to deal with this is to wrap values themselves within WeakReferences before inserting, as in: m.put(key, new WeakReference(value)), and then unwrapping upon each get.

URL OF FAULTY DOCUMENTATION :
http://docs.oracle.com/javase/7/docs/api/java/util/WeakHashMap.html

Comments
EVALUATION http://hg.openjdk.java.net/jdk8/tl/jdk/rev/237e27c7ddc3
2012-06-04