net.sf.basedb.core.signal
Class ThreadSignalHandler

java.lang.Object
  net.sf.basedb.core.signal.AbstractSignalHandler
      net.sf.basedb.core.signal.ThreadSignalHandler

All Implemented Interfaces:

SignalHandler

public class ThreadSignalHandler
extends AbstractSignalHandler

An implementation of a signal handler that uses the Thread class to communicate signals back to the SignalTarget. This handler only supports the Signal.ABORT signal. When this signal is received, Thread.interrupt() is called on the thread that was registered with this handler. This should typically be a worker thread for some process. The worker thread should regularly check Thread.interrupted() to see if it has been interrupted. If the thread may be waiting for a blocking call to end, it should be able to handle the resulting InterruptedException that is thrown if the thread is interrupted.

If the worker thread becomes interrupted it should stop what it is doing, cleanup any allocated resources and exit in a timely fasion. Here is a general outline:

// ... code in worker thread
threadSignalHandler.setWorkerThread(null);
beginTransaction();
boolean done = false;
boolean interrupted = false;
while (!done && !interrupted)
{
   try
   {
      done = doSomeWork(); // NOTE! This must not take forever!
      interrupted = Thread.interrupted();
   }
   catch (InterruptedException ex)
   {
      // NOTE! Try-catch is only needed if thread calls a blocking method 
      interrupted = true;
   }
}
if (interrupted)
{
   rollbackTransaction();
}
else
{
   commitTransaction();
}

Version:

2.6

Author:

nicklas

Last modified

$Date: 2010-09-10 13:09:05 +0200 (Fri, 10 Sep 2010) $

Field Summary

private boolean	forceStop If TRUE, call Thread.stop() instead of Thread.interrupt()
private static ThreadLocal<InterruptHandler>	interruptHandler Keep per-thread interupt handlers.
private static Logger	logger Log signals processing.
private static Set<Signal>	supported
private Thread	workerThread The worker thread that should be interrupted when Signal.ABORT is received.

Constructor Summary

ThreadSignalHandler()
Create a new thread signal handler.

ThreadSignalHandler(Thread workerThread)
Create a new thread signal handler.

Method Summary

static void	checkInterrupted() Utility method to check if the current thread has been interrupted and (may) throw a SignalException if it has.
void	handleSignal(Signal signal) Only handles the Signal.ABORT signal.
void	setForceStop(boolean forceStop) Call this method with a true value to make the signal handler use Thread.stop(Throwable) instead of Thread.interrupt().
static void	setInterruptHandler(InterruptHandler handler) Register an interrupt handler with the current thread.
void	setWorkerThread(Thread workerThread) Set the worker thread that should be interrupted when a signal is receiver.

Methods inherited from class net.sf.basedb.core.signal.AbstractSignalHandler

addSignal, getSupportedSignals, removeSignal, supports

Methods inherited from class java.lang.Object

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

Field Detail

interruptHandler

private static ThreadLocal<InterruptHandler> interruptHandler

Keep per-thread interupt handlers. The default handler is ExceptionInterruptHandler which simply throws a SignalException if the current thread has been interrupted.

Since:

2.16

logger

private static final Logger logger

Log signals processing.

supported

private static final Set<Signal> supported

workerThread

private Thread workerThread

The worker thread that should be interrupted when Signal.ABORT is received.

forceStop

private boolean forceStop

If TRUE, call Thread.stop() instead of Thread.interrupt()

Constructor Detail

ThreadSignalHandler

public ThreadSignalHandler()

Create a new thread signal handler. It will interrupt the current thread when it recieves the Signal.ABORT signal.

ThreadSignalHandler

public ThreadSignalHandler(Thread workerThread)

Create a new thread signal handler.

Parameters:

workerThread - The worker thread to interrupt when it receieves the Signal.ABORT signal, or null to interrupt the current thread

Method Detail

checkInterrupted

public static void checkInterrupted()

Utility method to check if the current thread has been interrupted and (may) throw a SignalException if it has. NOTE! Since BASE 2.16 the actual behaviour of this method is determined by the InterruptHandler that has been registered for the current thread by setInterruptHandler(InterruptHandler). The default handler always throws a SignalException.

setInterruptHandler

public static void setInterruptHandler(InterruptHandler handler)

Register an interrupt handler with the current thread. The handler is used by the checkInterrupted() method when the thread has been interrupted. If no handler has been registered with a thread the default action is to throw a SignalException.

Parameters:

handler - An interrupt handler or null to remove a previously registered handler

Since:

2.16

handleSignal

public void handleSignal(Signal signal)

Only handles the Signal.ABORT signal. When receieved, Thread.interrupt() is called on the worker thread that was registered when this object was created. Note that this method called from a different thread. The worker thread is busy doing something else. If the worker thread has already ended, this method does nothing.

Parameters:

signal - The signal, only Signal.ABORT is accepted

Throws:

UnsupportedSignalException - If signal is anything else than Signal.ABORT

setWorkerThread

public void setWorkerThread(Thread workerThread)

Set the worker thread that should be interrupted when a signal is receiver.

Parameters:

workerThread - The worker thread, or null to use the current thread

setForceStop

public void setForceStop(boolean forceStop)

Call this method with a true value to make the signal handler use Thread.stop(Throwable) instead of Thread.interrupt(). Note that the Thread.stop method is deprecated and it is not recommended that it is used. For some plug-ins though this may be the only option, if they are mainly executing code outside of their control which doesn't check the Thread.interrupted() status. The exception passed to the thread will be a InterruptedException.

Parameters:

forceStop - TRUE to stop the thread by force, FALSE to signal to it with a flag