org.apache.geode

Class CancelCriterion

java.lang.Object

org.apache.geode.CancelCriterion

public abstract class CancelCriterion
extends java.lang.Object

Abstract cancellation proxy for cancelling an operation, esp. a thread. Creators of services or threads should implement a subclass of CancelCriterion, and implement the two methods - cancelInProgress, and generateCancelledException(e). Code inside the service can check to see if the service is cancelled by calling checkCancelInProgress(Throwable). Generally the pattern is to check before performing an operation, check if the service is canceled before propagating an exception further up the stack, and check for cancellation inside a long loop. Eg.

 while (true) {
   c.checkCancelInProgress(null);
   try {
     dispatchEvents();
   } catch (IOException e) {
     c.checkCancelInProgress(e);
     throw e;
   }
 }
 

Since:

GemFire 5.1

See Also:

CancelException

Constructor Summary

Constructors

Constructor and Description
CancelCriterion()

Method Summary

Modifier and Type	Method and Description
abstract java.lang.String	cancelInProgress() Indicate if the service is in the progress of being cancelled.
void	checkCancelInProgress(java.lang.Throwable e) See if the current operation is being cancelled.
protected java.lang.String	checkFailure() Use this utility function in your implementation of cancelInProgress() and cancelled() to indicate a system failure
abstract java.lang.RuntimeException	generateCancelledException(java.lang.Throwable throwable) Template factory method for generating the exception to be thrown by checkCancelInProgress(Throwable).
boolean	isCancelInProgress() Checks to see if a cancellation is in progress.

Methods inherited from class java.lang.Object

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

Constructor Detail

CancelCriterion

public CancelCriterion()

Method Detail

cancelInProgress

public abstract java.lang.String cancelInProgress()

Indicate if the service is in the progress of being cancelled. The typical use of this is to indicate, in the case of an InterruptedException, that the current operation should be cancelled.

Returns:

null if the service is not shutting down, or a message that can be used to construct an exception indicating the service is shut down.

checkFailure

protected java.lang.String checkFailure()

Use this utility function in your implementation of cancelInProgress() and cancelled() to indicate a system failure

Returns:

failure string if system failure has occurred

checkCancelInProgress

public void checkCancelInProgress(java.lang.Throwable e)

See if the current operation is being cancelled. If so, it either throws a RuntimeException (usually a CancelException).

Parameters:

e - an underlying exception or null if there is no exception that triggered this check

See Also:

cancelInProgress()

generateCancelledException

public abstract java.lang.RuntimeException generateCancelledException(java.lang.Throwable throwable)

Template factory method for generating the exception to be thrown by checkCancelInProgress(Throwable). Override this to specify different exception for checkCancelInProgress() to throw. This method should wrap the exception in a service specific CancelationException (eg CacheClosedException). or return null if the service is not being canceled.

Parameters:

throwable - an underlying exception, if any

Returns:

RuntimeException to be thrown by checkCancelInProgress(), null if the receiver has not been cancelled.

isCancelInProgress

public boolean isCancelInProgress()

Checks to see if a cancellation is in progress. This is equivalent to the expression (cancelInProgress() != null).

Returns:

true if a cancellation is in progress, false if not