Deprecate finalization-related methods for removal

Summary

Deprecate finalization-related methods for removal, per JEP 421 ("Deprecate Finalization for Removal").

Problem

Finalization has several critical, fundamental flaws. These were widely recognized early in Java's history, and the JDK has offered better alternatives for quite some time. JEP 421 deprecates finalization for removal. The deprecations should be reflected in the API specification.

Solution

Several finalize() methods are already ordinarily deprecated. They will be upgraded to terminal deprecation by adding forRemoval=true:

• java.lang.Object.finalize()
• java.lang.Enum.finalize()
• java.awt.Graphics.finalize()
• java.awt.PrintJob.finalize()
• java.util.concurrent.ThreadPoolExecutor.finalize()
• javax.imageio.spi.ServiceRegistry.finalize()
• javax.imageio.stream.FileCacheImageInputStream.finalize()
• javax.imageio.stream.FileImageInputStream.finalize()
• javax.imageio.stream.FileImageOutputStream.finalize()
• javax.imageio.stream.ImageInputStreamImpl.finalize()
• javax.imageio.stream.MemoryCacheImageInputStream.finalize()

Two methods will be newly deprecated with forRemoval=true:

• java.lang.Runtime.runFinalization()
• java.lang.System.runFinalization().

One method will be newly deprecated with forRemoval=false:

• java.lang.management.MemoryMXBean.getObjectPendingFinalizationCount().

MemoryMXBean is an interface. Removing a method from it could adversely impact existing implementations. While developers should avoid using this method, it's safe to leave it in place. When finalization is disabled (or removed), this method will always return zero.

Specification

See attached webrev, also available at:

http://cr.openjdk.java.net/~bchristi/8276748/webrev-CSR-03-8276748/