CancelCriterion (Apache Geode 2.0.2)
Description: declaration: package: org.apache.geode, class: CancelCriterion

Package org.apache.geode

# Class CancelCriterion

java.lang.Object
org.apache.geode.CancelCriterion

public abstract class CancelCriterion extends 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
  Description
  `CancelCriterion()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract String`
  `cancelInProgress()`
  Indicate if the service is in the progress of being cancelled.
  `void`
  `checkCancelInProgress()`
  `void`
  `checkCancelInProgress(Throwable e)`
  See if the current operation is being cancelled.
  `protected String`
  `checkFailure()`
  Use this utility function in your implementation of cancelInProgress() and cancelled() to indicate a system failure
  `abstract RuntimeException`
  `generateCancelledException(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 Details

  - ### CancelCriterion

    public CancelCriterion()

- ## Method Details

  - ### cancelInProgress

    public abstract 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 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(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()`

  - ### checkCancelInProgress

    public void checkCancelInProgress()

  - ### generateCancelledException

    public abstract RuntimeException generateCancelledException(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