net.dclausen.util
Class SignalInterceptor

java.lang.Object
  net.dclausen.util.SignalInterceptor

Direct Known Subclasses:

SignalLogger

public abstract class SignalInterceptor

extends Object

A simple wrapper around the undocumented and unsupported sun.misc.Signal* classes which are present in most JVM implementations. It can be used to trap OS signals such as SIGINT, SIGTERM, and SIGHUP on these JVMs.

SignalInterceptor provides a level of indirection between your code and sun.misc.SignalHandler which can be useful for the following reasons:

1. It gracefully handles the situation when the sun.misc.Signal* classes are not available, throwing a checked exception out of the register method, rather than awkward LinkageErrors durring class initialization.
2. It has a simple technique for chaining signal handlers.
3. It is documented and has gone through some testing.

Some possible uses of this class are:

• Change the behavior of SIGHUP so that instead of exiting the JVM, your application reloads its configuration file.
• Log the fatal signals SIGHUP, SIGINT, and SIGTERM before passing them onto the JVM's native handlers, so that you have a record of when and why your application exited.
• Implement your own version of ShutdownHooks which run prior to the standard ones. This can be useful because many other packages have their own ShutdownHooks which close resources which you might like to use. For example the java.util.logging package closes all of its files in its ShutdownHook, which means your ShutdownHook might not be able to log anything. Note that you would still need to deal with System.exit(), but there is a different hack available for that ;).

Constructor Summary

protected

SignalInterceptor()

Method Summary

protected abstract boolean	handle(String signame) Handle the given signal (which you had previously registered for).
protected void	register(String signame) Register for the given signal.
protected boolean	registerQuietly(String signame) A wrapper around register(String) which never throws an exception.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SignalInterceptor

protected SignalInterceptor()

Method Detail

register

protected void register(String signame)
                 throws SignalInterceptorException

Register for the given signal. Note that the signal name should not begin with SIG. For example, if you are interested in SIGTERM, you should call register("TERM").

If the registration fails for any reason, a SignalInterceptorException will be thrown. This is usually caused by one of the following conditions:

• The sun.misc.Signal* classes are not available (e.g. you are not using Sun's JVM).
• signame is not a valid trappable signal name on this OS (e.g. KILL can't be trapped, HUP does not exist on Windows)
• The JVM refuses to let you trap signame because it is already being used for some other important purpose (e.g. QUIT and/or BREAK cause the JVM to print diagnostic output).

Throws:

SignalInterceptorException

registerQuietly

protected boolean registerQuietly(String signame)

A wrapper around register(String) which never throws an exception. Instead, it returns true if registration succeeded, and false if it failed.

handle

protected abstract boolean handle(String signame)

Handle the given signal (which you had previously registered for). If this method return false, or throws an exception, subsequent handlers in the chain will not be called.