info.textgrid.lab.core.model.util

Class LongOperation<T>

java.lang.Object

info.textgrid.lab.core.model.util.LongOperation<T>

Type Parameters:

T - the return value of the run method (that gets passed through busyCursor(IProgressMonitor) etc.)

public abstract class LongOperation<T>
extends Object

A wrapper for long-running operations (like grid access) that should never be run from the UI thread. This is a convenience class that mainly takes care of result and exception handling, freeing the user from writing long try-catch-blocks unwrapping an rethrowing exceptions, but it has been designed for use for common use cases within the model.

Implementors instantiate a subclass of this and implement its run method with their functionality. Then, they call runInJob(IProgressMonitor, String) on it.

Here is an example on how to use it:

 public InputStream openInputStream(final int options,
                final IProgressMonitor monitor) throws CoreException {
        return new LongOperation<InputStream>() {
 
                @Override
                public InputStream run(IProgressMonitor monitor) throws CoreException {
                        return doOpenInputStream(options, monitor);
                }
 
        }.runInJob(monitor);
 }
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	LongOperation.JoiningRunnable
static class	LongOperation.LongOperationException An exception that is thrown when an error occurs while running the LongOperation.
protected class	LongOperation.RunnableWrappingJob A job that wraps a IRunnableWithProgress and adapts the API for error reporting and cancellation.

Constructor Summary

Constructors

Constructor and Description
LongOperation()

Method Summary

Modifier and Type	Method and Description
T	busyCursor(IProgressMonitor monitor) Deprecated. in some cases, might trigger TG-360 on Macs. Also displays a large enervating popup dialog. Use runInJob(IProgressMonitor, String) instead.
protected T	getResult()
abstract T	run(IProgressMonitor monitor) A long-running operation that should in no case be executed in the UI thread.
T	runInJob(IProgressMonitor monitor, String message) Run the operation in a background job and wait for the background job to finish, when called from an UI thread.

Methods inherited from class java.lang.Object

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

Constructor Detail

LongOperation

public LongOperation()

Method Detail

run

public abstract T run(IProgressMonitor monitor)
               throws CoreException

A long-running operation that should in no case be executed in the UI thread.

Parameters:

monitor - A progress monitor to report progress to. May be null.

Returns:

The result.

Throws:

CoreException

busyCursor

public T busyCursor(IProgressMonitor monitor)
             throws CoreException

Deprecated. in some cases, might trigger TG-360 on Macs. Also displays a large enervating popup dialog. Use runInJob(IProgressMonitor, String) instead.

Runs the run(IProgressMonitor) method as appropriate:

• When called from a non-UI thread, directly calls the run(IProgressMonitor) method.
• When called from the UI thread, aquires the workbench's progress service and runs the method through its IProgressService.busyCursorWhile(IRunnableWithProgress) method.

In both cases, the GUI will stay reactive.

Parameters:

monitor - a progress monitor that will be used when the method is not called from the UI thread.

Returns:

the result of the run(IProgressMonitor) method.

Throws:

LongOperation.LongOperationException - when run(IProgressMonitor) has thrown an unknown exception (which it shouldn't)

CoreException - when the run(IProgressMonitor) has thrown a CoreException

RuntimeException - when run(IProgressMonitor) has thrown a RuntimeException

runInJob

public T runInJob(IProgressMonitor monitor,
                  String message)
           throws CoreException

Run the operation in a background job and wait for the background job to finish, when called from an UI thread. Otherwise, just run the operation. Implemented for TG-360 FIXME this needs to be improved, esp. the progress reporting stuff should be merged. See also TG-328!

Parameters:

monitor - a monitor to report progress to

message - the job title if this operation is forced to the background

Returns:

the result of the wrapped operation (see run(IProgressMonitor))

Throws:

CoreException - in case of an error, see run(IProgressMonitor) and LongOperation.LongOperationException

getResult

protected T getResult()

Returns:

the result of the run(IProgressMonitor) method after that has run or null.