agi.foundation.infrastructure.threading

(agi.foundation.core-2024r3.jar)

Class BackgroundCalculation

java.lang.Object

javax.swing.SwingWorker<Object,Void>

agi.foundation.infrastructure.threading.BackgroundCalculation

All Implemented Interfaces:

ITrackCalculationProgress, Runnable, Future<Object>, RunnableFuture<Object>

public class BackgroundCalculation
extends SwingWorker<Object,Void>
implements ITrackCalculationProgress

Used to perform a computation in the background. This type:

• configures the CalculationContext for the new thread by copying the context of the thread that initiates the background computation.
• implements the ITrackCalculationProgress interface so that it can be passed directly to long running operations to support progress reporting and cancellation.
• contains an AsyncWaitHandle (get) property. It returns a WaitHandle that is set to signaled when the DoWork (add / remove) event handler completes.

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.SwingWorker

SwingWorker.StateValue

Constructor Summary

Constructors

Constructor and Description
BackgroundCalculation() Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
void	addDoWork(DoWorkEventHandler value) Adds a handler for an event that occurs when BackgroundCalculation.runWorkerAsync() is called.
void	addProgressChanged(ProgressChangedEventHandler value) Adds a handler for an event that occurs when BackgroundCalculation.reportProgress(int, java.lang.Object) is called.
void	addRunWorkerCompleted(RunWorkerCompletedEventHandler value) Adds a handler for an event that occurs when the background operation has completed, been canceled, or raised an exception.
void	cancelAsync() Requests cancellation of a pending background operation.
void	captureCalculationContext() Captures the calculation context of the calling thread.
protected Object	doInBackground()
protected void	done()
ManualResetEvent	getAsyncWaitHandle() Gets a WaitHandle that is used to wait for the operation to complete.
boolean	getCancellationPending() Gets a value indicating whether the application has requested cancellation of a background operation.
boolean	getIsBusy() Gets a value indicating whether this instance is running an asynchronous operation.
boolean	getWorkerReportsProgress() Gets a value indicating whether this instance can report progress updates.
boolean	getWorkerSupportsCancellation() Gets a value indicating whether this instance supports asynchronous cancellation.
void	removeDoWork(DoWorkEventHandler value) Removes a handler for an event that occurs when BackgroundCalculation.runWorkerAsync() is called.
void	removeProgressChanged(ProgressChangedEventHandler value) Removes a handler for an event that occurs when BackgroundCalculation.reportProgress(int, java.lang.Object) is called.
void	removeRunWorkerCompleted(RunWorkerCompletedEventHandler value) Removes a handler for an event that occurs when the background operation has completed, been canceled, or raised an exception.
void	reportProgress(int percentProgress, Object additionalInformation) Raises the ProgressChanged (add / remove) event.
void	runWorkerAsync() Starts execution of a background operation.
void	runWorkerAsync(Object argument) Starts execution of a background operation.

Methods inherited from class javax.swing.SwingWorker

addPropertyChangeListener, cancel, execute, firePropertyChange, get, get, getProgress, getPropertyChangeSupport, getState, isCancelled, isDone, process, publish, removePropertyChangeListener, run, setProgress

Methods inherited from class java.lang.Object

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

Constructor Detail

BackgroundCalculation

public BackgroundCalculation()

Initializes a new instance. Also captures the CalculationContext from the thread constructing the new instance in order to pass the context to the new thread when BackgroundCalculation.runWorkerAsync() is called. To capture the context again later, call BackgroundCalculation.captureCalculationContext().

Method Detail

captureCalculationContext

public void captureCalculationContext()

Captures the calculation context of the calling thread. This is the context that will be passed to the new thread when BackgroundCalculation.runWorkerAsync() is called. This method cannot be called after BackgroundCalculation.runWorkerAsync().

Throws:

IllegalStateException - Thrown when the background computation has already been started. The calculation context cannot be captured after this point.

getAsyncWaitHandle

public ManualResetEvent getAsyncWaitHandle()

Gets a WaitHandle that is used to wait for the operation to complete. When the DoWork (add / remove) event handler has finished, this event will be signaled.

getCancellationPending

public boolean getCancellationPending()

Gets a value indicating whether the application has requested cancellation of a background operation. True if the application has requested cancellation of a background operation; otherwise, false. The default is false.

Specified by:

getCancellationPending in interface ITrackCalculationProgress

cancelAsync

public void cancelAsync()

Requests cancellation of a pending background operation.

runWorkerAsync

public void runWorkerAsync()

Starts execution of a background operation.

runWorkerAsync

public void runWorkerAsync(Object argument)

Starts execution of a background operation.

Parameters:

argument - A parameter for use by the background operation to be executed in the DoWork (add / remove) event handler.

doInBackground

protected Object doInBackground()

Specified by:

doInBackground in class SwingWorker<Object,Void>

done

protected void done()

Overrides:

done in class SwingWorker<Object,Void>

reportProgress

public void reportProgress(int percentProgress,
                           Object additionalInformation)

Raises the ProgressChanged (add / remove) event.

Specified by:

reportProgress in interface ITrackCalculationProgress

Parameters:

percentProgress - The percentage, from 0 to 100, of the background operation that is complete.

additionalInformation - The state object passed to BackgroundCalculation.runWorkerAsync().

getIsBusy

public boolean getIsBusy()

Gets a value indicating whether this instance is running an asynchronous operation.

Returns:

true, if this instance is running an asynchronous operation; otherwise, false.

getWorkerReportsProgress

public boolean getWorkerReportsProgress()

Gets a value indicating whether this instance can report progress updates.

Returns:

Always true.

getWorkerSupportsCancellation

public boolean getWorkerSupportsCancellation()

Gets a value indicating whether this instance supports asynchronous cancellation.

Returns:

Always true.

addDoWork

public void addDoWork(DoWorkEventHandler value)

Adds a handler for an event that occurs when BackgroundCalculation.runWorkerAsync() is called.

Parameters:

value - The handler.

removeDoWork

public void removeDoWork(DoWorkEventHandler value)

Removes a handler for an event that occurs when BackgroundCalculation.runWorkerAsync() is called.

Parameters:

value - The handler to remove.

addProgressChanged

public void addProgressChanged(ProgressChangedEventHandler value)

Adds a handler for an event that occurs when BackgroundCalculation.reportProgress(int, java.lang.Object) is called.

Parameters:

value - The handler.

removeProgressChanged

public void removeProgressChanged(ProgressChangedEventHandler value)

Removes a handler for an event that occurs when BackgroundCalculation.reportProgress(int, java.lang.Object) is called.

Parameters:

value - The handler to remove.

addRunWorkerCompleted

public void addRunWorkerCompleted(RunWorkerCompletedEventHandler value)

Adds a handler for an event that occurs when the background operation has completed, been canceled, or raised an exception.

Parameters:

value - The handler.

removeRunWorkerCompleted

public void removeRunWorkerCompleted(RunWorkerCompletedEventHandler value)

Removes a handler for an event that occurs when the background operation has completed, been canceled, or raised an exception.

Parameters:

value - The handler to remove.