jklustor-all-api-0.0.7-20140619012755 (ChemAxon)


com.chemaxon.calculations.common
Interface CancelObserver

All Known Subinterfaces:
ProgressObserver, SubProgressObserver
All Known Implementing Classes:
ProgressObservers.CancelObserverImpl

@Beta
public interface CancelObserver

Callback to propagate cancel requests into long running tasks.

Cancel request propagation is part of the functionality provided by ProgressObserver, however it is a cross cutting concern, so it is exposed as a separate interface.

Polling and callback based notification also can be used to propagate cancel requests.

Thread safety: implementations are not required to be thread safe; observed processes must be prepared for working with non thread safe observers. Consequently observer methods can be called only on the thread invoked the observed process.

Please note that this interface is marked with Beta annotation, so it can be subject of incompatible changes or removal in later releases.

Author:
Gabor Imre

Field Summary
static String FIRED_PROPERTY_NAME
          Name of property stored in fired property change listener upon cancellation.
 
Method Summary
 void addPropertyChangeListener(PropertyChangeListener listener)
          Add a listener for cancellation.
 boolean isCancelled()
          Returns whether cancellation of current operation has been requested.
 void removePropertyChangeListener(PropertyChangeListener listener)
          Remove a listener.
 

Field Detail

FIRED_PROPERTY_NAME

static final String FIRED_PROPERTY_NAME
Name of property stored in fired property change listener upon cancellation.

See Also:
Constant Field Values
Method Detail

isCancelled

boolean isCancelled()
Returns whether cancellation of current operation has been requested.

Long running/memory intensive operations should poll to see if cancelation has been requested. Since time-out based cancelations might be implemented polling should not be done too often.

It is expected that implementations wont return false after a true value returned. It is also expected that implementations tolerate multiple calls regardless of the cancallation state.

Please note that test cases might check for too frequent invocations, so the propagation of any AssertionError thrown by this method should not be obstructed.

It is usually expected that the cancelled task should throw CancellationException and this behavior should be documented in their APIdocs.

Returns:
true if cancellation has been requested, false otherwise.

addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener listener)
Add a listener for cancellation.

The passed PropertyChangeListener will be called upon cancellation event. The fired PropertyChangeEvent conforms to the following contract:

It is guaranteed that one PropertyChangeEvent is fired at most once per additon count, only when cancellation occurs. In case cancellation occurs before listener addition then event will be fired upon addition.

Invocation count behaves according to the API contract stated in PropertyChangeSupport.addPropertyChangeListener(java.beans.PropertyChangeListener)

Parameters:
listener - Callback to invoke upon cancellation.

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)
Remove a listener.

This method behaves according to the API contarct stated in PropertyChangeSupport.removePropertyChangeListener(java.beans.PropertyChangeListener)

Parameters:
listener - Listener to remove.

jklustor-all-api-0.0.7-20140619012755 (ChemAxon)