net.sf.basedb.core.signal
Class EnhancedThreadSignalHandler

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

All Implemented Interfaces:

InterruptHandler, SignalHandler

public class EnhancedThreadSignalHandler
extends AbstractSignalHandler
implements InterruptHandler

An extension to the thread signal handler that supports any number of signals. When a signal is recieved it will call Thread.interrupt() on the worker thread. This signal handler is also registered as an interrupt handler with ThreadSignalHandler.setInterruptHandler(InterruptHandler), and will throw a SignalReceivedException when interrupted.

When the worker thread becomes aware of the notification it should call getReceivedSignals() or hasReceived(Signal) to find out which signal that was sent and then take the proper action.

There are usually three different ways to get a notification about the signal:

• An InterruptedException is thrown. This usually happens when the code involves blocking IO operations or other blocking synchronization functions.
• A SignalReceivedException is thrown. This is usually thrown from the BASE core when it detects that the thread has been interrupted.
• Check the Thread.interrupted() flag. But we recommend that ThreadSignalHandler.checkInterrupted() is used instead.

// ... code in worker thread
threadSignalHandler.setWorkerThread();
beginTransaction();
boolean done = false;
boolean interrupted = false;
while (!done && !interrupted)
{
   try
   {
      done = doSomeWork(); // NOTE! This must not take forever!
      ThreadSignalHandler.checkInterrupted();
   }
   catch (SignalReceivedException ex)
   {
        // This exception can be thrown from BASE core when a thread is interrupted
        interrupted = true;
   }
   catch (InterruptedException ex)
   {
      // NOTE! Try-catch is only needed if thread calls a blocking method 
      interrupted = true;
   }
}
if (interrupted)
{
        if (threadSignalHandler.hasReceived(Signal.SHUTDOWN))
        {
                // save current state so that we can continue when the system
                // is up and running again
        }
   rollbackTransaction();
}
else
{
   commitTransaction();
}

Since:

2.16

Author:

nicklas

Last modified

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

Field Summary

private static Logger	logger Log signals processing.
private List<Signal>	received
private Thread	workerThread The worker thread that should be interrupted when a signal is received.

Constructor Summary

EnhancedThreadSignalHandler(Collection<Signal> supported)
Create a new signal handler that supports the specified signals.

EnhancedThreadSignalHandler(Signal... supported)
Create a signal handler that supports the specified signals.

Method Summary

void	checkForSignals() If at least one signal has been received a SignalReceivedException is thrown.
List<Signal>	getReceivedSignals() Get the list of received signals.
void	handleInterrupt() Throws a SignalReceivedException if one ore more signals has been received.
void	handleSignal(Signal signal) When a supported signal is received Thread.interrupt() is called on the worker thread that was registered when this object was created.
boolean	hasReceived(Signal signal) Check if the given signal has been received by this signal handler.
boolean	hasReceivedSignals() Check if any signals has been received by this handler.
void	setWorkerThread() Set the worker thread to the current thread.

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

logger

private static final Logger logger

Log signals processing.

received

private final List<Signal> received

workerThread

private Thread workerThread

The worker thread that should be interrupted when a signal is received.

Constructor Detail

EnhancedThreadSignalHandler

public EnhancedThreadSignalHandler(Collection<Signal> supported)

Create a new signal handler that supports the specified signals.

Parameters:

supported - A collection with the signals that are initially supported. More signals can be added with AbstractSignalHandler.addSignal(Signal)

EnhancedThreadSignalHandler

public EnhancedThreadSignalHandler(Signal... supported)

Create a signal handler that supports the specified signals.

Parameters:

supported - An array with the signals that are initially supported. More signals can be added with AbstractSignalHandler.addSignal(Signal)

Method Detail

handleSignal

public void handleSignal(Signal signal)

When a supported signal is received Thread.interrupt() is called on the worker thread that was registered when this object was created. Note that this method is called from a different thread. The worker thread is busy doing something else. If the worker thread has already ended, this method does nothing. It is the responsibility of the worker thread to regularly check with this signal handler if it has recieved any signals.

Specified by:

handleSignal in interface SignalHandler

Parameters:

signal - The signal

Throws:

UnsupportedSignalException - If signal is not supported

handleInterrupt

public void handleInterrupt()

Throws a SignalReceivedException if one ore more signals has been received.

Specified by:

handleInterrupt in interface InterruptHandler

setWorkerThread

public void setWorkerThread()

Set the worker thread to the current thread. This will also register this object as an interrupt handler with ThreadSignalHandler.setInterruptHandler(InterruptHandler).

hasReceivedSignals

public boolean hasReceivedSignals()

Check if any signals has been received by this handler.

Returns:

TRUE if at least one signal has been received, FALSE otherwise

getReceivedSignals

public List<Signal> getReceivedSignals()

Get the list of received signals. Calling this method clears the internal list and if no signals are received in the meantime, the next call to this method will return null.

Returns:

A list with signals in the order they were received, or null if no signals has been received

checkForSignals

public void checkForSignals()

If at least one signal has been received a SignalReceivedException is thrown. This method clears the received signals.

hasReceived

public boolean hasReceived(Signal signal)

Check if the given signal has been received by this signal handler.

Parameters:

signal - The signal to check for

Returns:

TRUE if the signal has been received, FALSE otherwise