net.sf.basedb.core.signal
Class ProgressReporterSignalHandler

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

All Implemented Interfaces:

ProgressReporter, SignalHandler

public class ProgressReporterSignalHandler
extends AbstractSignalHandler
implements ProgressReporter

An implementation of a signal handler that uses a ProgressReporter to communicate signals back to the target. This handler supports any signals. This signal handler works by replacing the progress reporter a plug-in uses with it's own progress reporter. Each time the plug-in calls ProgressReporter.display(int, String) or ProgressReporter.append(String) and the percentage value is less than 100 the signal handler will check if a signal has been received. If so, a SignalReceivedException will be thrown.

NOTE! Some parts of the BASE core only uses the Thread.interrupt() mechanism for aborting a process. For example, long-running queries against the dynamic database. In this case we recommend that a ThreadSignalHandler, possible linked with DelegatingSignalHandler, is used instead.

Here is a general outline of a plug-in that uses the progress reporter signal handler:

// To keep track of current progress
private int percent;
private String progressMessage;

// Set up signal handling; ABORT is the only supported signal
private ProgressReporterSignalHandler signalHandler;
public SignalHandler getSignalHandler()
{
   signalHandler = new ProgressReporterSignalHandler(Signal.ABORT);
   return signalHandler;
}
public void run(Request request, Response response, ProgressReporter progress)
{
   if (signalHandler != null)
   {
      signalHandler.forwardTo(progress);
      progress = signalHandler;
   }
   beginTransaction();
   boolean done = false;
   while (!done && !interrupted)
   {
      try
      {
         done = doSomeWork(); // NOTE! This must not take forever!
         if (progress != null) progress.display(percent, progressMessage);
       }
       catch (SignalReceivedException ex)
       {
          // We only support the abort signal
          interrupted = true;
       }
   }
   if (interrupted)
   {
      rollbackTransaction();
      response.setError("Aborted by user", null);
   }
   else
   {
      commitTransaction();
      response.setDone("Done");
   }
}

Version:

2.6

Author:

nicklas

See Also:

ThreadSignalHandler

Last modified

$Date: 2008-09-11 22:09:17 +0200 (Thu, 11 Sep 2008) $

Field Summary

private ProgressReporter	forwardTo Original progress reporter that progress updates should be forwarded to.
private int	limit When the progress has reached this limit signal checking becomes disabled.
private static Logger	logger Log signals processing.
private int	percent The current percentage status.
private List<Signal>	received

Constructor Summary

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

Method Summary

void	append(String message) Append a message to the previous one.
void	checkForSignals() If at least one signal has been received a SignalReceivedException is thrown.
void	display(int percent, String message) Display a progress message.
void	forwardTo(ProgressReporter forwardTo) Set the progress reporter that progress information should be forwarded to.
int	getLimit() Get the percentage limit where signal checking becomes disabled.
List<Signal>	getReceivedSignals() Get the list of received signals.
void	handleSignal(Signal signal) When signals are receieved, they are stored in a temporary list in the order they come in.
boolean	hasReceivedSignals() Check if any signals has been received by this handler.
void	setLimit(int limit) Set the percentage limit.

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.

forwardTo

private ProgressReporter forwardTo

Original progress reporter that progress updates should be forwarded to.

received

private List<Signal> received

percent

private int percent

The current percentage status.

limit

private int limit

When the progress has reached this limit signal checking becomes disabled. Default value is 100.

Constructor Detail

ProgressReporterSignalHandler

public ProgressReporterSignalHandler(Collection<Signal> supported)

Create a new progress reporter 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)

Method Detail

handleSignal

public void handleSignal(Signal signal)

When signals are receieved, they are stored in a temporary list in the order they come in. When the signal target calls display(int, String) or append(String) a SignalReceivedException is throw if the list is not empty. Once the exception has been thrown the internal list is cleared.

Specified by:

handleSignal in interface SignalHandler

Parameters:

signal - The signal to handle

Throws:

UnsupportedSignalException - If the signal is not supported

append

public void append(String message)

Description copied from interface: ProgressReporter

Append a message to the previous one.

Specified by:

append in interface ProgressReporter

Parameters:

message - The message

display

public void display(int percent,
                    String message)

Description copied from interface: ProgressReporter

Display a progress message.

Specified by:

display in interface ProgressReporter

Parameters:

percent - How many percent of the task that is completed or -1 if not known

message - A message, or null

forwardTo

public void forwardTo(ProgressReporter forwardTo)

Set the progress reporter that progress information should be forwarded to.

Parameters:

forwardTo - The progress reporter, or null if progress should not be forwarded

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

getLimit

public int getLimit()

Get the percentage limit where signal checking becomes disabled.

Returns:

The limit in percent

setLimit

public void setLimit(int limit)

Set the percentage limit. When the progress has reached the limit signal checking will be disable. The default value is 100 since there is no need to abort a process when it has already been finished.

Parameters:

limit - The new limit

checkForSignals

public void checkForSignals()

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