The api note for Object.finalize is not an optimal location for this
more general advice,
but is good as far as it can go in relation to the current changes to
deprecate Object.finalize().
The webrev[1] is updated to add a paragraph to the apiNote[2]:
* @apiNote
* Classes that embed non-heap resources have a number of options
* for cleanup of those resources. The class must ensure that the
* lifetime of each instance is longer than that of any resource it
embeds.
* {@link java.lang.ref.Reference#reachabilityFence} can be used to
ensure that
* objects remain reachable while resources embedded in the object
are in use.
Regards, Roger
[1] http://cr.openjdk.java.net/~rriggs/webrev-finalize-deprecate-8165641
[2]
http://cr.openjdk.java.net/~rriggs/webrev-finalize-deprecate-8165641/src/java.base/share/classes/java/lang/Object.java.sdiff.html
