CancelCriterion (Apache Geode 1.4.0)
Date: 2018-01-29

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

    All Methods Instance Methods Abstract Methods Concrete Methods
    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