RFR: 8302496: Runtime.exit incorrectly says it never throws an exception

[Alan Bateman]

On Fri, 28 Apr 2023 21:44:58 GMT, Stuart Marks <smarks at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/Runtime.java line 146:
>> 
>>> 144:      * If a security manager is present and its {@link SecurityManager#checkExit checkExit}
>>> 145:      * method disallows exiting with the specified status, throws {@link SecurityException}.
>>> 146:      * Otherwise, this method blocks indefinitely; it neither returns nor throws an exception
>> 
>> The SM is not long for this world.  So I'm in two minds about it making a farewell appearance in the first paragraph of the method description when we know we will have to remove this text very soon.  If we really need to change this now then maybe it could be reduced to "When a security manager is not set, this method never returns ..." so that the distraction of checkExit is not in the first paragraph.
>
> Yeah I had some misgivings mentioning the SM first, but if it's not mentioned, then the assertions in the rest of the text become hedged and uncertain. The SM, checkExit, and whether the exit value is allowed all have to be mentioned somewhere anyway. It would be awkward to try to wedge all of this into a subordinate or parenthetical clause of some other sentence.
> 
> Even though we know the SM is on the way out, it's still part of Java SE 21, and it ought to be specified correctly. When the SM is actually removed, we'll have to revisit these specs anyway. Choosing different wording now won't make the future change any easier or harder.

One thing you could do is reduce the words down to something like "Unless denied exiting by the security manager, this method blocks indefinitely ..." to avoid complicating the first paragraph with something that only arises with a niche execution mode. If needed, a later paragraph could have this detail, or just leave it to the existing @throws text where the permission check is specified.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/13706#discussion_r1181399806