Package com.complexible.common.cancellation

# Class CancellationManager

java.lang.Object
com.complexible.common.cancellation.CancellationManager

All Implemented Interfaces:
  `Disposable`

public final class CancellationManager extends Object implements Disposable
This is general abstraction to make 5 main functions: 1) Create cancellation point for specific database; Locks global mutex in readLock mode; Locks database-related mutex in readLock mode; 2) Execute exclusive database operation for specific database; Locks global mutex in readLock mode; Locks database-related mutex in writeLock mode; So it is impossible to create new cancellation point or to execute critical section while this lock is acquired; 3) Unregister cancellation point; Does not have locks with other operations; 4) Cancel cancellation points; Does not have locks with other operations; 5) Dispose cancellation manager (for all databases); Locks global mutex in write lock mode; It will be impossible to run all parallel methods during dispose;

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `CancellationManager.CheckedFunction<T,R>`
  Callable which may throw an exception.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CancellationManager()`
  `CancellationManager(int cancelTimeoutMs, int databaseLockTimeoutMs, int disposeTimeoutMs)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `cancel()`
  Cancel all registered cancellation points;
  `void`
  `cancel(String theDatabaseName)`
  Cancel all registered cancellation points for the specific database.
  `int`
  `countCancellationPoint(String db)`
  `void`
  `dispose()`
  Dispose cancellation manager; It cancels all active cancellation points and cleanup all resources;
  `<T> T`
  `executeExclusiveDatabaseOperation(String theDatabaseName, String theProcessDescription, Runnable theForceClose, CancellationManager.CheckedFunction<CancellationPoint,T> theWorker)`
  Executes database-critical operation; Creates a cancellation point which may be used to cancel the operation.
  `<T> T`
  `executeExclusiveDatabaseOperation(String theDatabaseName, String theProcessDescription, Runnable theForceClose, Callable<T> theWorker)`
  Executes database-critical operation; It acquires global lock in shared mode; It acquires local per-db lock in exclusive mode;
  `<T> T`
  `executeExclusiveDatabaseOperation(String theDatabaseName, String theProcessDescription, Callable<T> theWorker)`
  `void`
  `predisposed()`
  `CancellationPoint`
  `registerCancellationPoint(String theCancellationMessage, String theDatabaseName)`
  Register cancellation point with default thrower;
  `CancellationPoint`
  `registerCancellationPoint(String theCancellationMessage, String theDatabaseName, Function<String,? extends RuntimeException> theCancellationThrower)`
  This method is used to register new cancellation point;
  `void`
  `registerDatabase(String theDatabaseName)`
  Register database in the system;
  `void`
  `unregisterDatabase(String theDatabaseName)`
  De-register database;
  `void`
  `wait(String dbname, String theProcessDescription, int waitTimeMs)`

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### CancellationManager

    public CancellationManager()

  - ### CancellationManager

    public CancellationManager(int cancelTimeoutMs, int databaseLockTimeoutMs, int disposeTimeoutMs)

- ## Method Details

  - ### registerCancellationPoint

    public CancellationPoint registerCancellationPoint(String theCancellationMessage, String theDatabaseName)
    Register cancellation point with default thrower;
    Parameters:
      `theCancellationMessage` - - the cancellation message;
      `theDatabaseName` - - the database name;
    Returns:
      created cancellation point;

  - ### registerCancellationPoint

    public CancellationPoint registerCancellationPoint(String theCancellationMessage, String theDatabaseName, Function<String,? extends RuntimeException> theCancellationThrower)
    This method is used to register new cancellation point;
    Parameters:
      `theCancellationMessage` - - the new cancellation message;
      `theDatabaseName` - - the database name;
      `theCancellationThrower` - - the thrower which will be used;
    Returns:
      created cancellation point;

  - ### registerDatabase

    public void registerDatabase(String theDatabaseName)
    Register database in the system;
    Parameters:
      `theDatabaseName` - - the database name;

  - ### unregisterDatabase

    public void unregisterDatabase(String theDatabaseName)
    De-register database;
    Parameters:
      `theDatabaseName` - - the database name;

  - ### executeExclusiveDatabaseOperation

    public <T> T executeExclusiveDatabaseOperation(String theDatabaseName, String theProcessDescription, Runnable theForceClose, Callable<T> theWorker)
    Executes database-critical operation; It acquires global lock in shared mode; It acquires local per-db lock in exclusive mode;
    Parameters:
      `theDatabaseName` - - the database name;
      `theProcessDescription` - - the description of process;
      `theForceClose` - - Callback if not all CPs close after a timeout
      `theWorker` - - the worked for execution;
    Returns:
      the result of the Worker's call;

  - ### executeExclusiveDatabaseOperation

    public <T> T executeExclusiveDatabaseOperation(String theDatabaseName, String theProcessDescription, Callable<T> theWorker)
    See Also:
      - `executeExclusiveDatabaseOperation(String, String, Runnable, CheckedFunction)`

  - ### executeExclusiveDatabaseOperation

    public <T> T executeExclusiveDatabaseOperation(String theDatabaseName, String theProcessDescription, Runnable theForceClose, CancellationManager.CheckedFunction<CancellationPoint,T> theWorker)
    Executes database-critical operation; Creates a cancellation point which may be used to cancel the operation. It is not possible to create any new Cancellation Points before this method returns. It acquires global lock in shared mode; It acquires local per-db lock in exclusive mode;
    Parameters:
      `theForceClose` - callback if there are remaining CPs not closed after a timeout.
      `theWorker` - the callable which will be executed with the CP
    See Also:
      - `executeExclusiveDatabaseOperation(String, String, Callable)`

  - ### cancel

    public void cancel()
    Cancel all registered cancellation points;

  - ### predisposed

    public void predisposed()

  - ### cancel

    public void cancel(String theDatabaseName)
    Cancel all registered cancellation points for the specific database.
    Parameters:
      `theDatabaseName` - - the database's name;

  - ### dispose

    public void dispose()
    Dispose cancellation manager; It cancels all active cancellation points and cleanup all resources;
    Specified by:
      `dispose` in interface `Disposable`

  - ### wait

    public void wait(String dbname, String theProcessDescription, int waitTimeMs)

  - ### countCancellationPoint

    public int countCancellationPoint(String db)