Page History

...

This implementation uses an internal flag to track whether the exit is permitted. The method setExitAllowed() sets this flag. The checkExit method throws a SecurityException when the flag is unset (e.g., false). Consequently, normal exception processing bypasses the initial call to System.exit(). The program catches the SecurityException and performs mandatory clean-up operations, including logging the exception. The setExitAllowed() method is invoked only after clean-up is complete. Consequently, the program exits gracefully.

Noncompliant Code Example

When a user forcefully exits a program by pressing the ctrl + c key or by using the kill command, the JVM terminates abruptly. Although this event cannot be captured, the program should nevertheless perform any mandatory clean-up operations before exiting. This noncompliant code example fails to do so.

public class InterceptExit {
  public static void main(String[] args) {
    System.out.println("Regular code block");
    // Abrupt exit such as ctrl + c key pressed
    System.out.println("This never executes");
  }
}

Compliant Solution

Use the addShutdownHook() method of java.lang.Runtime to assist with performing clean-up operations in the event of abrupt termination. The JVM starts the shutdown hook thread when abrupt termination is initiated; the shutdown hook runs concurrently with other JVM threads.

According to the Java API \[[API 2006|AA. Bibliography#API 06]\] Class {{Runtime}}, method {{addShutdownHook}}

A shutdown hook is simply an initialized but unstarted thread. When the virtual machine begins its shutdown sequence it will start all registered shutdown hooks in some unspecified order and let them run concurrently. When all the hooks have finished it will then run all uninvoked finalizers if finalization-on-exit has been enabled. Finally, the virtual machine will halt. Once the shutdown sequence has begun it can be stopped only by invoking the halt method, which forcibly terminates the virtual machine. Once the shutdown sequence has begun it is impossible to register a new shutdown hook or de-register a previously-registered hook.

Some precautions must be taken because the JVM is in a sensitive state during shutdown. Shutdown hook threads should:

• be light-weight and simple
• be thread safe
• hold locks when accessing data and release those locks when done

• Wiki Markup
  lack reliance on system services, as the services themselves may be shutting down (for example, the logger may shutdown from another hook). Instead of one service it may be better to run a series of shutdown tasks from one thread by using a single shutdown hook \[[Goetz 2006|AA. Bibliography#Goetz 06]\].

This compliant solution shows the standard method to install a hook.

public class Hook {
  public static void main(String[] args) {
    Runtime.getRuntime().addShutdownHook(new Thread() {
      public void run() {
        hookShutdown();
      }
    });
		
   // ...
  }

  public static void hookShutdown() {
    // Log shutdown and close all resources
  }
}

The JVM can abort for external reasons, such as an external SIGKILL signal (UNIX) or the TerminateProcess call (Microsoft Windows), or memory corruption caused by native methods. Shutdown hooks may fail to execute as expected in such cases, because the JVM cannot guarantee that they will be executed as intended.

Exceptions

*EXC09-EX1:* It is permissible for a command line utility to call {{System.exit()}} or terminate prematurely; for example, when the required number of arguments are not input \[[Bloch 2008|AA. Bibliography#Bloch 08]\] and \[[ESA 2005|AA. Bibliography#ESA 05]\].

...