FutureTalker V1.3
by Matthew Ford
2005/04/11

au.com.forward.futureTalker
Class TaskUtilities

java.lang.Object
  extended by au.com.forward.futureTalker.TaskUtilities

public class TaskUtilities
extends java.lang.Object

A collection of utilites for coding tasks so that they can be interrupted.


Constructor Summary
TaskUtilities()
           
 
Method Summary
static java.io.Closeable closeIgnoringErrors(java.io.Closeable c)
          Close this Closable, if it is not null, ignoring any errors.
static void ifInterruptedStop()
          Checks if the interrupt flag is set for the thread running this task and throws an InterruptedException if it is.
static java.io.InputStream interruptibleInputStream(java.io.FileInputStream f_in)
          Returns an interruptible InputStream connected to a FileInputStream.
static java.io.InputStream interruptibleInputStream(java.io.RandomAccessFile f_in)
          Returns an interruptible InputStream connected to a RandomAccessFile.
static java.io.OutputStream interruptibleOutputStream(java.io.FileOutputStream f_out)
          Returns an interruptible OutputStream connected to a FileOutputStream.
static java.io.OutputStream interruptibleOutputStream(java.io.RandomAccessFile f_out)
          Returns an interruptible OutputStream connected to a RandomAccessFile.
static java.io.Reader interruptibleReader(java.io.FileInputStream f_in)
          Returns an interruptible Reader connected to a FileInputStream using the default character set.
static java.io.Reader interruptibleReader(java.io.FileInputStream f_in, java.lang.String csName)
          Returns an interruptible Reader connected to a FileInputStream using the given character set.
static java.io.Reader interruptibleReader(java.io.RandomAccessFile f_in)
          Returns an interruptible Reader connected to a RandomAccessFile using the default character set.
static java.io.Reader interruptibleReader(java.io.RandomAccessFile f_in, java.lang.String csName)
          Returns an interruptible Reader connected to a RandomAccessFile using the given character set.
static java.io.InputStream interruptibleSystemIn()
          Returns an interruptible InputStream connected to System.in
static java.io.Writer interruptibleWriter(java.io.FileOutputStream f_out)
          Returns an interruptible Writer connected to a FileOutputStream using the default character set.
static java.io.Writer interruptibleWriter(java.io.FileOutputStream f_out, java.lang.String csName)
          Returns an interruptible Writer connected to a FileOutputStream using the given character set.
static java.io.Writer interruptibleWriter(java.io.RandomAccessFile f_out)
          Returns an interruptible Writer connected to a RandomAccessFile using the default character set.
static java.io.Writer interruptibleWriter(java.io.RandomAccessFile f_out, java.lang.String csName)
          Returns an interruptible Writer connected to a RandomAccessFile using the given character set.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TaskUtilities

public TaskUtilities()
Method Detail

ifInterruptedStop

public static void ifInterruptedStop()
                              throws java.lang.InterruptedException
Checks if the interrupt flag is set for the thread running this task and throws an InterruptedException if it is.

In order to stop the task, this InterruptedException must propergate out of the Callable.call() method.

If this check is done in an internal method which is not defined to throw exceptions you will have to catch the InterruptedException and wrap it in a RuntimeException and re-throw it.

Throws:
java.lang.InterruptedException - Thrown if the interrupt flag is set for the thread running this method.

closeIgnoringErrors

public static java.io.Closeable closeIgnoringErrors(java.io.Closeable c)
Close this Closable, if it is not null, ignoring any errors.
This should only be called in a finally clause after normal close methods have been called. This method is designed only to be called in the cleanup after some error has already occured.

Typical usage is

 FileInputStream in_1 = null;
 FileInputStream in_2 = null;
 try {
   ....
   in_1.close(); // throws exception if error.
   in_1 = null;  // flag as closed
   in_2.close(); // throws exception if error.
   in_2 = null;  // flag as closed
 } finally {
   // clean up any un-released resources.
   // if streams are local to this method no need to assign them to null here
   // but assign to null if global to indicate they have been closed.
   // in_1 = (FileInputStream)TaskUtilities.closeIgnoringErrors(in_1); // if global
   TaskUtilities.closeIgnoringErrors(in_1); // if local
   // in_2 = (FileInputStream)TaskUtilities.closeIgnoringErrors(in_2); // if global
   TaskUtilities.closeIgnoringErrors(in_2); // if local
   // etc...
 }

Parameters:
c - The Closable that needs closing
Returns:
null to be assigned to the object being closed.

interruptibleSystemIn

public static java.io.InputStream interruptibleSystemIn()
Returns an interruptible InputStream connected to System.in

If a thread is blocked in an I/O operation on the returned stream then another thread may invoke the stream's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

If a thread is blocked in an I/O operation on the returned stream, then another thread may invoke the blocked thread's interrupt method. This will cause the stream to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a the returned stream, then the stream will be closed and the thread will immediately receive a ClosedByInterruptException. The thread's interrupt status will remain set.

Returns:
interruptible stream connected to System.in

interruptibleInputStream

public static java.io.InputStream interruptibleInputStream(java.io.RandomAccessFile f_in)
Returns an interruptible InputStream connected to a RandomAccessFile.
If the RandomAccessFile is not opened for reading, attempting to read from this stream will throw an exception

If a thread is blocked in an I/O operation on the returned stream then another thread may invoke the stream's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

If a thread is blocked in an I/O operation on the returned stream, then another thread may invoke the blocked thread's interrupt method. This will cause the stream to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a the returned stream, then the stream will be closed and the thread will immediately receive a ClosedByInterruptException. The thread's interrupt status will remain set.

Parameters:
f_in - the RandomAccessFile to connect to.
Returns:
interruptible stream connected to the RandomAccessFile

interruptibleOutputStream

public static java.io.OutputStream interruptibleOutputStream(java.io.RandomAccessFile f_out)
Returns an interruptible OutputStream connected to a RandomAccessFile.
flush() does not work due to problem in Sun's library so the latest output will be lost on closing/interruption.
Also you cannot interrupt a write operation. You can only interrupt when the write is blocked.
If the RandomAccessFile is not opened for writing, attempting to write to this stream will throw an exception

If a thread is blocked in an I/O operation on the returned stream then another thread may invoke the stream's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

If a thread is blocked in an I/O operation on the returned stream, then another thread may invoke the blocked thread's interrupt method. This will cause the stream to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a the returned stream, then the stream will be closed and the thread will immediately receive a ClosedByInterruptException. The thread's interrupt status will remain set.

Parameters:
f_out - the RandomAccessFile to connect to.
Returns:
interruptible stream connected to the RandomAccessFile

interruptibleInputStream

public static java.io.InputStream interruptibleInputStream(java.io.FileInputStream f_in)
Returns an interruptible InputStream connected to a FileInputStream.

If a thread is blocked in an I/O operation on the returned stream then another thread may invoke the stream's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

If a thread is blocked in an I/O operation on the returned stream, then another thread may invoke the blocked thread's interrupt method. This will cause the stream to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a the returned stream, then the stream will be closed and the thread will immediately receive a ClosedByInterruptException. The thread's interrupt status will remain set.

Parameters:
f_in - the FileInputStream to connect to
Returns:
interruptible stream connected to the FileInputStream

interruptibleOutputStream

public static java.io.OutputStream interruptibleOutputStream(java.io.FileOutputStream f_out)
Returns an interruptible OutputStream connected to a FileOutputStream.
flush() does not work due to problem in Sun's library so the latest output will be lost on closing/interruption.
Also you cannot interrupt a write operation. You can only interrupt when the write is blocked.

If a thread is blocked in an I/O operation on the returned stream then another thread may invoke the stream's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

If a thread is blocked in an I/O operation on the returned stream, then another thread may invoke the blocked thread's interrupt method. This will cause the stream to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a the returned stream, then the stream will be closed and the thread will immediately receive a ClosedByInterruptException. The thread's interrupt status will remain set.

Parameters:
f_out - the FileOutputStream to connect to.
Returns:
interruptible stream connected to the FileOutputStream

interruptibleReader

public static java.io.Reader interruptibleReader(java.io.RandomAccessFile f_in)
Returns an interruptible Reader connected to a RandomAccessFile using the default character set.
If the RandomAccessFile is not opened for reading, attempting to read from this stream will throw an exception

If a thread is blocked in an I/O operation on the returned stream then another thread may invoke the stream's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

If a thread is blocked in an I/O operation on the returned stream, then another thread may invoke the blocked thread's interrupt method. This will cause the stream to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a the returned stream, then the stream will be closed and the thread will immediately receive a ClosedByInterruptException. The thread's interrupt status will remain set.

Parameters:
f_in - the RandomAccessFile to connect to.
Returns:
interruptible stream connected to the RandomAccessFile

interruptibleReader

public static java.io.Reader interruptibleReader(java.io.RandomAccessFile f_in,
                                                 java.lang.String csName)
Returns an interruptible Reader connected to a RandomAccessFile using the given character set.
If the RandomAccessFile is not opened for reading, attempting to read from this stream will throw an exception

If a thread is blocked in an I/O operation on the returned stream then another thread may invoke the stream's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

If a thread is blocked in an I/O operation on the returned stream, then another thread may invoke the blocked thread's interrupt method. This will cause the stream to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a the returned stream, then the stream will be closed and the thread will immediately receive a ClosedByInterruptException. The thread's interrupt status will remain set.

Parameters:
f_in - the RandomAccessFile to connect to.
csName - the Charset name.
Returns:
interruptible Reader connected to the RandomAccessFile
Throws:
IllegalCharsetNameException - - If the given charset name is illegal
UnsupportedCharsetException - - If no support for the named charset is available in this instance of the Java virtual machine

interruptibleWriter

public static java.io.Writer interruptibleWriter(java.io.RandomAccessFile f_out)
Returns an interruptible Writer connected to a RandomAccessFile using the default character set.
flush() does not work due to problem in Sun's library so the latest output will be lost on closing/interruption.
Also you cannot interrupt a write operation. You can only interrupt when the write is blocked.
If the RandomAccessFile is not opened for writing, attempting to write to this reader will throw an exception

If a thread is blocked in an I/O operation on the returned stream then another thread may invoke the stream's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

If a thread is blocked in an I/O operation on the returned stream, then another thread may invoke the blocked thread's interrupt method. This will cause the stream to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a the returned stream, then the stream will be closed and the thread will immediately receive a ClosedByInterruptException. The thread's interrupt status will remain set.

Parameters:
f_out - the RandomAccessFile to connect to.
Returns:
interruptible Writer connected to the RandomAccessFile

interruptibleWriter

public static java.io.Writer interruptibleWriter(java.io.RandomAccessFile f_out,
                                                 java.lang.String csName)
Returns an interruptible Writer connected to a RandomAccessFile using the given character set.
flush() does not work due to problem in Sun's library so the latest output will be lost on closing/interruption.
Also you cannot interrupt a write operation. You can only interrupt when the write is blocked. RandomAccessFile using the given character set.
If the RandomAccessFile is not opened for writing, attempting to write to this reader will throw an exception

If a thread is blocked in an I/O operation on the returned stream then another thread may invoke the stream's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

If a thread is blocked in an I/O operation on the returned stream, then another thread may invoke the blocked thread's interrupt method. This will cause the stream to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a the returned stream, then the stream will be closed and the thread will immediately receive a ClosedByInterruptException. The thread's interrupt status will remain set.

Parameters:
f_out - the RandomAccessFile to connect to.
csName - the Charset name.
Returns:
interruptible Writer connected to the RandomAccessFile
Throws:
IllegalCharsetNameException - - If the given charset name is illegal
UnsupportedCharsetException - - If no support for the named charset is available in this instance of the Java virtual machine

interruptibleReader

public static java.io.Reader interruptibleReader(java.io.FileInputStream f_in)
Returns an interruptible Reader connected to a FileInputStream using the default character set.

If a thread is blocked in an I/O operation on the returned stream then another thread may invoke the stream's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

If a thread is blocked in an I/O operation on the returned stream, then another thread may invoke the blocked thread's interrupt method. This will cause the stream to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a the returned stream, then the stream will be closed and the thread will immediately receive a ClosedByInterruptException. The thread's interrupt status will remain set.

Parameters:
f_in - the FileInputStream to connect to.
Returns:
interruptible Reader connected to the FileInputStream

interruptibleReader

public static java.io.Reader interruptibleReader(java.io.FileInputStream f_in,
                                                 java.lang.String csName)
Returns an interruptible Reader connected to a FileInputStream using the given character set.

If a thread is blocked in an I/O operation on the returned stream then another thread may invoke the stream's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

If a thread is blocked in an I/O operation on the returned stream, then another thread may invoke the blocked thread's interrupt method. This will cause the stream to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a the returned stream, then the stream will be closed and the thread will immediately receive a ClosedByInterruptException. The thread's interrupt status will remain set.

Parameters:
f_in - the FileInputStream to connect to.
csName - the Charset name.
Returns:
interruptible Reader connected to the FileInputStream
Throws:
IllegalCharsetNameException - - If the given charset name is illegal
UnsupportedCharsetException - - If no support for the named charset is available in this instance of the Java virtual machine

interruptibleWriter

public static java.io.Writer interruptibleWriter(java.io.FileOutputStream f_out)
Returns an interruptible Writer connected to a FileOutputStream using the default character set.
flush() does not work due to problem in Sun's library so the latest output will be lost on closing/interruption.
Also you cannot interrupt a write operation. You can only interrupt when the write is blocked.

If a thread is blocked in an I/O operation on the returned stream then another thread may invoke the stream's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

If a thread is blocked in an I/O operation on the returned stream, then another thread may invoke the blocked thread's interrupt method. This will cause the stream to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a the returned stream, then the stream will be closed and the thread will immediately receive a ClosedByInterruptException. The thread's interrupt status will remain set.

Parameters:
f_out - the FileInputStream to connect to.
Returns:
interruptible Writer connected to the FileOutputStream

interruptibleWriter

public static java.io.Writer interruptibleWriter(java.io.FileOutputStream f_out,
                                                 java.lang.String csName)
Returns an interruptible Writer connected to a FileOutputStream using the given character set.
flush() does not work due to problem in Sun's library so the latest output will be lost on closing/interruption.
Also you cannot interrupt a write operation. You can only interrupt when the write is blocked.

If a thread is blocked in an I/O operation on the returned stream then another thread may invoke the stream's close method. This will cause the blocked thread to receive an AsynchronousCloseException.

If a thread is blocked in an I/O operation on the returned stream, then another thread may invoke the blocked thread's interrupt method. This will cause the stream to be closed, the blocked thread to receive a ClosedByInterruptException, and the blocked thread's interrupt status to be set.

If a thread's interrupt status is already set and it invokes a blocking I/O operation upon a the returned stream, then the stream will be closed and the thread will immediately receive a ClosedByInterruptException. The thread's interrupt status will remain set.

Parameters:
f_out - the FileInputStream to connect to.
csName - the Charset name.
Returns:
interruptible Writer connected to the FileOutputStream
Throws:
IllegalCharsetNameException - - If the given charset name is illegal
UnsupportedCharsetException - - If no support for the named charset is available in this instance of the Java virtual machine

©2004, Forward Computing and Control Pty. Ltd
ACN 003 669 994   NSW Australia
All Rights Reserved.