Summary
-------

This request proposes specification changes in support of a command-line option that disables finalization.

Problem
-------

[JEP 421](https://openjdk.java.net/jeps/421) proposes to deprecate finalization for removal. Part of that work is a command-line option to disable finalization, so that developers can evaluate the effect on applications of not having finalization prior to its removal. This entails changes to the *Java SE Platform Specification*, the *Java Language Specification*, and the `java` tool specification.

Solution
--------

Allowing a fundamental part of the Java platform to be reconfigured or disabled via the command line is best handled in the main text of the *Java SE Platform Specification*. Precedent for this is the "Relaxing strong encapsulation" sections that have appeared in various versions of the *Platform Specification*: [Java SE 9][1], [Java SE 16][2], and [Java SE 17][3]. The primary change is in the *Platform Specification*. Adjustments will be made to other specifications. 

[1]: http://cr.openjdk.java.net/~iris/se/9/latestSpec/#Relaxing-strong-encapsulation
[2]: http://cr.openjdk.java.net/~iris/se/16/latestSpec/#Relaxing-strong-encapsulation
[3]: http://cr.openjdk.java.net/~iris/se/17/latestSpec/#Relaxing-strong-encapsulation

* We propose a section in the *Java SE Platform Specification* to cover disabling finalization via the command line. We expect that this section will evolve in the future, when the default setting changes and when finalization is eventually removed.

* The *Java Language Specification*, section 12.6, will be updated to highlight the change to the *Platform Specification*. See [JDK-8277344][4].

[4]: https://bugs.openjdk.java.net/browse/JDK-8277344

* The *API Specification* will be updated by [JDK-8276748][5] to add deprecation annotations and corresponding text. Those changes also mention the possibility of finalization being disabled or removed.

[5]: https://bugs.openjdk.java.net/browse/JDK-8276748

* The specification of the JDK's `java` tool will be updated, to cover the specific syntax of the command-line option.

The ability to disable finalization is a change to Java SE. The addition of a command-line option is a change to the JDK.

There is no change to the *Java Virtual Machine Specification*. Although it does mention garbage collection, there is no mention of finalization.


Specification
-------------

The following text will be added into an appropriate section of the *Java SE Platform Specification*:

> **Deprecation of finalization.** An Implementation must support the finalization of objects, as described in the [Java Language Specification, section 12.6](https://docs.oracle.com/javase/specs/jls/se17/html/jls-12.html#jls-12.6). However, this Platform Specification deprecates finalization, for removal. To aid preparations for the removal of finalization, an Implementation may provide a means to invoke its run-time system with finalization disabled. If finalization is disabled, the effect is that the Java Virtual Machine never invokes an object's finalizer before the storage for the object is reclaimed by the garbage collector. An Implementation must not, by default, disable finalization.

> (The Reference Implementation provides the ability to disable finalization via the command-line option `--finalization=disabled`.)

> Future revisions of this Platform Specification are expected to disable finalization by default and, eventually, to remove finalization from the Java Language Specification. 

An informative note will be added to the JLS at the opening of section 12.6:

> As of Java SE 18, the Java SE Platform Specification allows finalization of class instances to be disabled by an Implementation of the Java SE Platform, in anticipation of the removal of finalization from a future release of the Platform.

The following text will be added to the JDK's specification of the `java` tool:

> `--finalization=<value>`
>
> Controls whether the JVM performs finalization of objects.
> Valid values are "enabled" and "disabled". Finalization is enabled by default,
> so the value "enabled" does nothing. The value "disabled" disables finalization,
> so that no finalizers are invoked.