com.foxsmart.ic.lang
Class ThreadMonitor

java.lang.Object
  com.foxsmart.ic.lang.ThreadMonitor

public class ThreadMonitor
extends java.lang.Object

This class executes code in a separate thread and optionally times out if the thread takes too long to complete. Since the JDK makes the methods that stop threads depricated, the thread will not be timed out, but rather an interrupted flag will be set. This flag can be checked by the InterruptibleThread class by calling the isInterrupted() method of this class. The executing code in the run method of the InterruptibleThread class should monitor this flag and return as soon as possible if it is set.

The following is an example of how the ThreadMonitor class can be used:

 ThreadMonitor threadMonitor = new ThreadMonitor(
    new InterruptibleThread()
    {
       public void run(ThreadMonitor threadMonitor) throws Exception
       {
          // This is the code that is executed in a separate thread.
 

          // The isInterrupted method should be checked periodically to see if the thread has been interrupted and
 return.
          if (threadMonitor.isInterrupted())
          {
                return;
          }
 

          // The setTimeoutMessage method should be called before performing an operation in case the thread times
 out.
          threadMonitor.setTimeoutMessage("Unable to connect to server.");
 

          // Code to connect to server goes here...
 

          // If an error is found, a normal exception can be thrown
          if (errorFound)
          {
             throw new Exception("Unable to connect to server.");
          }
 

          // If everything is successful, the run method should just return normally.
          return;
       }
    }, new Integer(60)); // 60 second timeout
 

 // Startup the thread
 try
 {
    threadMonitor.start();
 }
 catch (ThreadTimeoutException ex)
 {
    // The thread timed out
 }
 catch (ThreadErrorException ex)
 {
    // The thread finished because the code in the thread threw an exception.
 }
 

Field Summary

protected org.apache.commons.logging.Log

log

Constructor Summary

ThreadMonitor(InterruptibleThread interruptibleThread, java.lang.Integer timeoutSeconds)
Constructs a new thread monitor with a monitorable thread object.

Method Summary

java.lang.Object	getReturnValue() Gets the return value.
boolean	isInterrupted() Returns whether the thread is interrupted.
void	setInterrupted(boolean interrupted) Sets the interrupt flag.
void	setInterruptibleThread(InterruptibleThread interruptibleThread) Sets the InterruptibleThread class to execute when the run method is called.
void	setReturnValue(java.lang.Object returnValue) Sets a return value within the interruptible thread that can be retrieved by the caller.
void	setTimeout(java.lang.Integer timeoutSeconds) Sets the timeout value in seconds for the thread.
void	setTimeoutMessage(java.lang.String message) Sets the timeout message.
void	start() Executes the InterruptibleThread code in a separate thread.

Methods inherited from class java.lang.Object

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

Field Detail

log

protected org.apache.commons.logging.Log log

Constructor Detail

ThreadMonitor

public ThreadMonitor(InterruptibleThread interruptibleThread,
                     java.lang.Integer timeoutSeconds)

Constructs a new thread monitor with a monitorable thread object.

Parameters:

interruptibleThread - An class that contains code to run in a separate thread and can be interrupted if the thread times out.

timeoutSeconds - The time in seconds for the thread to run before it times out. A value of null means that the thread will not timeout.

Method Detail

setTimeout

public void setTimeout(java.lang.Integer timeoutSeconds)

Sets the timeout value in seconds for the thread. This should be set prior to calling the run method.

Parameters:

timeoutSeconds - The time in seconds for the thread to run before it times out. A value of null means that the thread will not timeout.

setInterruptibleThread

public void setInterruptibleThread(InterruptibleThread interruptibleThread)

Sets the InterruptibleThread class to execute when the run method is called. This should be set prior to calling the run method.

Parameters:

interruptibleThread - An class that contains code to run in a separate thread and can be interrupted if the thread times out.

setTimeoutMessage

public void setTimeoutMessage(java.lang.String message)

Sets the timeout message. This message will be included in the ThreadTimeoutException object that is thrown if the thread times out. A default message will be included if a message is not set or if null is passed. This method should be called by the running thread before each independent operation so an appropriate message will be displayed if the thread times out. For example, a message such as "Unable to connect to server." could be set right before the InterruptibleThread code attempts to make a connection to a server.

Parameters:

message - The timeout message.

setReturnValue

public void setReturnValue(java.lang.Object returnValue)

Sets a return value within the interruptible thread that can be retrieved by the caller.

Parameters:

returnValue - The value to set.

getReturnValue

public java.lang.Object getReturnValue()

Gets the return value.

Returns:

The return value.

isInterrupted

public boolean isInterrupted()

Returns whether the thread is interrupted. This should be checked by the code in the run method of the InterruptibleThread periodically to see if the thread has been interrupted and should terminate.

Returns:

true if the thread is interrupted or false if not.

setInterrupted

public void setInterrupted(boolean interrupted)

Sets the interrupt flag. This flag is set automatically when the thread times out. However, this method can be called while the thread is running to manually interrupt it.

Parameters:

interrupted - the interrupted flag.

start

public void start()
           throws ThreadTimeoutException,
                  ThreadErrorException

Executes the InterruptibleThread code in a separate thread. This method will reset the interrupt flag before the thread is executed. Note that if no timeout is specified and if the code in the InterruptibleThread's run method never returns, this method will not return.

Throws:

ThreadTimeoutException - if the thread timed out.

ThreadErrorException - if the code in the thread threw an exception. The original exception that was thrown by the thread is contained within the ThreadErrorException and can be obtained by calling the getOriginalException method.