de.sciss.common
Class ProcessingThread

java.lang.Object
  de.sciss.common.ProcessingThread

All Implemented Interfaces:

EventManager.Processor, Disposable, java.awt.event.ActionListener, java.lang.Runnable, java.util.EventListener

public class ProcessingThread
extends java.lang.Object
implements java.lang.Runnable, EventManager.Processor, java.awt.event.ActionListener, Disposable

A subclass of Thread that is capable of dealing with synchronization issues. It will pause all event dispatching related to specified doors which will be locked during processing. It includes helper methods for updating a progress bar and displaying messages and exceptions.

Version:

0.70, 28-Jun-08

Author:

Hanns Holger Rutz

Nested Class Summary

static class	ProcessingThread.CancelledException
static interface	ProcessingThread.Client
static class	ProcessingThread.Event
static interface	ProcessingThread.Listener

Field Summary

protected EventManager	elm
protected java.lang.Exception	exception
protected java.lang.String	name
protected float	progress
protected boolean	progressInvoked
protected int	returnCode
protected java.lang.Object	sync

Constructor Summary

ProcessingThread(ProcessingThread.Client client, ProgressComponent pc, java.lang.String procName)
Creates a new ProcessingThread.

Method Summary

void	actionPerformed(java.awt.event.ActionEvent e)
void	addListener(ProcessingThread.Listener l) Registers a listener to be notified when the process starts and terminates.
void	cancel(boolean doSync) Forwards the cancel request to the client.
static ProcessingThread	currentThread()
void	dispose()
static void	flushProgression()
java.lang.Object	getClientArg(java.lang.Object key)
java.util.Map	getClientMap()
java.awt.Component	getComponent()
java.lang.Exception	getException() Queries the last exception thrown in the run method.
java.lang.String	getName()
int	getReturnCode() Returns the cient's return code.
boolean	isRunning()
void	processEvent(BasicEvent e) Processes the next event in the queue.
void	putClientArg(java.lang.Object key, java.lang.Object value)
void	removeListener(ProcessingThread.Listener l) Removes a listener from being notified when the process starts and terminates.
void	resetProgression()
void	run() The is the main method of a thread; it invokes the client's processRun method.
void	setException(java.lang.Exception e) If the client is capable of catching an exception in its execution block, it should pass it to the pt calling this method.
static void	setNextProgStop(float p)
void	setProgression(float p) Called by the client to update the progress bar.
static boolean	shouldCancel()
void	start() Starts processing.
void	sync() Puts the calling thread in wait mode until the processing is finished.
void	sync(int timeout)
static void	update(float progress)

Methods inherited from class java.lang.Object

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

Field Detail

name

protected final java.lang.String name

progress

protected volatile float progress

progressInvoked

protected volatile boolean progressInvoked

exception

protected volatile java.lang.Exception exception

elm

protected EventManager elm

returnCode

protected int returnCode

sync

protected final java.lang.Object sync

Constructor Detail

ProcessingThread

public ProcessingThread(ProcessingThread.Client client,
                        ProgressComponent pc,
                        java.lang.String procName)

Creates a new ProcessingThread. To start the process and starts processing.

Parameters:

client - Interface whose method runProcessing() is called inside the new thread when it's started.

pc - Component responsible for displaying progress bar etc.

procName - Name for the thread and the process monitoring

Synchronization:

must be called in the event thread

Method Detail

putClientArg

public void putClientArg(java.lang.Object key,
                         java.lang.Object value)

getClientArg

public java.lang.Object getClientArg(java.lang.Object key)

getClientMap

public java.util.Map getClientMap()

getName

public java.lang.String getName()

start

public void start()

Starts processing. Call this method only once!

sync

public void sync()

Puts the calling thread in wait mode until the processing is finished. This should be called in the event thread only if the process is about to quit very fast since it will otherwise block GUI updates. An example for its use is the prior request to cancel the process. If the amount of time till the end of the process is unknown, the preferred method to wait for the thread is to register a listener!

See Also:

addListener( ProcessingThread.Listener )

sync

public void sync(int timeout)

cancel

public void cancel(boolean doSync)

Forwards the cancel request to the client.

Parameters:

doSync - if true, wait for the client to abort, otherwise return immediately

currentThread

public static ProcessingThread currentThread()

shouldCancel

public static boolean shouldCancel()

update

public static void update(float progress)
                   throws ProcessingThread.CancelledException

Throws:

ProcessingThread.CancelledException

isRunning

public boolean isRunning()

getReturnCode

public int getReturnCode()

Returns the cient's return code.

Returns:

the return code (Client.DONE etc.) or -1 if the client had not been started

addListener

public void addListener(ProcessingThread.Listener l)

Registers a listener to be notified when the process starts and terminates.

Parameters:

l - the listener to register

removeListener

public void removeListener(ProcessingThread.Listener l)

Removes a listener from being notified when the process starts and terminates.

Parameters:

l - the listener to unregister

dispose

public void dispose()

Specified by:

dispose in interface Disposable

run

public void run()

The is the main method of a thread; it invokes the client's processRun method.

Specified by:

run in interface java.lang.Runnable

setException

public void setException(java.lang.Exception e)

If the client is capable of catching an exception in its execution block, it should pass it to the pt calling this method.

Parameters:

e - exception which was thrown in the client's run method. when the thread stops it will display this error to the user.

getException

public java.lang.Exception getException()

Queries the last exception thrown in the run method.

Returns:

the most recent exception or null if no exception was thrown

setNextProgStop

public static void setNextProgStop(float p)

flushProgression

public static void flushProgression()

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent e)

Specified by:

actionPerformed in interface java.awt.event.ActionListener

processEvent

public void processEvent(BasicEvent e)

Description copied from interface: EventManager.Processor

Processes the next event in the queue. This gets called in the event thread. Usually implementing classes should loop through all listeners by calling elm.countListeners() and elm.getListener(), and invoke specific dispatching methods on these listeners.

Specified by:

processEvent in interface EventManager.Processor

getComponent

public java.awt.Component getComponent()

setProgression

public void setProgression(float p)

Called by the client to update the progress bar.

Parameters:

p - new progression between zero and one

resetProgression

public void resetProgression()