Summary

Clarify the specifications of System.exit, Runtime.exit, and Runtime.halt.

Problem

The various method specifications say that they never throw an exception, however they in fact do throw SecurityException.

Solution

Reword the specifications to improve clarity and to remove the inconsistency. The intent of the previous specifications is retained. There is no change in behavior.

Specification

Runtime.exit:

     /**
-     * Initiates the <a href="#shutdown">shutdown sequence</a> of the Java Virtual Machine.
-     * This method blocks indefinitely; it never returns or throws an exception (that is, it
-     * does not complete either normally or abruptly). The argument serves as a status code;
-     * by convention, a nonzero status code indicates abnormal termination.
+     * Initiates the {@linkplain ##shutdown shutdown sequence} of the Java Virtual Machine.
+     * Unless the security manager denies exiting, this method initiates the shutdown sequence
+     * (if it is not already initiated) and then blocks indefinitely. This method neither returns
+     * nor throws an exception; that is, it does not complete either normally or abruptly.
      *
-     * <p> Invocations of this method are serialized such that only one
-     * invocation will actually proceed with the shutdown sequence and
-     * terminate the VM with the given status code. All other invocations
-     * simply block indefinitely.
+     * <p> The argument serves as a status code. By convention, a nonzero status code
+     * indicates abnormal termination.
      *
-     * <p> Because this method always blocks indefinitely, if it is invoked from
-     * a shutdown hook, it will prevent that shutdown hook from terminating.
-     * Consequently, this will prevent the shutdown sequence from finishing.
+     * <p> Successful invocations of this method are serialized such that only one invocation
+     * initiates the shutdown sequence and terminates the VM with the given status code.
+     * All other invocations will perform no action and block indefinitely.
+     *
+     * <p> Because a successful invocation of this method blocks indefinitely, if it is invoked
+     * from a shutdown hook, it will prevent that shutdown hook from terminating. Consequently,
+     * this will prevent the shutdown sequence from finishing.

Runtime.halt:

     /**
-     * Immediately <a href="#termination">terminates</a> the Java Virtual Machine. Termination
-     * is unconditional and immediate. This method does not initiate the
-     * <a href="#shutdown">shutdown sequence</a>, nor does it wait for the shutdown sequence
-     * to finish if it is already in progress. This method never returns normally.
+     * Immediately {@linkplain ##termination terminates} the Java Virtual Machine.
+     * If the security manager denies exiting, throws {@link SecurityException}.
+     * Otherwise, termination of the Java Virtual Machine is unconditional and immediate.
+     * This method does not initiate the {@linkplain ##shutdown shutdown sequence}, nor does
+     * it wait for the shutdown sequence to finish if it is already in progress. An
+     * invocation of this method never returns normally.

System.exit:

     /**
-     * Initiates the <a href="Runtime.html#shutdown">shutdown sequence</a> of the
-     * Java Virtual Machine. This method always blocks indefinitely. The argument
-     * serves as a status code; by convention, a nonzero status code indicates
-     * abnormal termination.
+     * Initiates the {@linkplain Runtime##shutdown shutdown sequence} of the Java Virtual Machine.
+     * Unless the security manager denies exiting, this method initiates the shutdown sequence
+     * (if it is not already initiated) and then blocks indefinitely. This method neither returns
+     * nor throws an exception; that is, it does not complete either normally or abruptly.
      * <p>
-     * This method calls the {@code exit} method in class {@code Runtime}. This
-     * method never returns normally.
+     * The argument serves as a status code. By convention, a nonzero status code
+     * indicates abnormal termination.