This was for a time CR 6254531 "(spec thread) ThreadLocal leak when value references ThreadLocal". However that CR has been converted to a Dolphin RFE and this CR will carry the doc improvement.

Users expect automagic reclaiming of thread local objects and the ThreadLocal design ultimately ties reclamation guarantees to Thread lifetimes. That is, until a Thread instance returns from its run method or otherwise terminates normally enough that normal exit actions take plce, locals can be "trapped." This is especially terrible when a local is self-referencing or involved with a reference cycle or there is an explicit reference to the Thread instance involved. 

To the extent possible the ThreadLocal javadoc needs to be improved to give users the opportunity to understand the limitations some (e.g. Sun's) implementation may impose, how to use ThreadLocal.remove when possible, and any strategies compatible with API documentation constraints. A specific suggested fix to follow.