Package org.keycloak.models.locking

Interface GlobalLockProvider

All Superinterfaces:
Provider
All Known Implementing Classes:
DBLockGlobalLockProvider, HotRodGlobalLockProvider, MapGlobalLockProvider
public interface GlobalLockProvider extends Provider

  • Method Details

    • withLock

      default <V> V withLock(String lockName, KeycloakSessionTaskWithResult<V> task) throws LockAcquiringTimeoutException
      Acquires a new non-reentrant global lock that is visible to all Keycloak nodes. Effectively the same as withLock(lockName, null, task)
      Type Parameters:
      V - Type of object returned by the task
      Parameters:
      lockName - Identifier used for acquiring lock. Can be any non-null string.
      task - The task that will be executed under the acquired lock
      Returns:
      Value returned by the task
      Throws:
      LockAcquiringTimeoutException - When acquiring the global lock times out (see Javadoc of withLock(String, Duration, KeycloakSessionTaskWithResult) for more details on how the time duration is determined)
      NullPointerException - When lockName is null.

    • withLock

      <V> V withLock(String lockName, Duration timeToWaitForLock, KeycloakSessionTaskWithResult<V> task) throws LockAcquiringTimeoutException
      Acquires a new non-reentrant global lock that is visible to all Keycloak nodes. If the lock was successfully acquired the method runs the task in a new transaction to ensure all data modified in task is committed to the stores before releasing the lock and returning to the caller.

      If there is another global lock with the same identifier (lockName) already acquired, this method waits until the lock is released, however, not more than timeToWaitForLock duration. If the lock is not acquired after timeToWaitForLock duration, the method throws LockAcquiringTimeoutException.

      When the execution of the task finishes, the acquired lock must be released regardless of the result.

      A note to implementors of the interface:

      To make sure acquiring/releasing the lock is visible to all Keycloak nodes it may be needed to run the code that acquires/releases the lock in a separate transactions. This means together the method can use 3 separate transactions, for example: 

           try {
         KeycloakModelUtils.runJobInTransaction(factory,
                                innerSession -> /* run code that acquires the lock *\/)

         KeycloakModelUtils.runJobInTransactionWithResult(factory, task)
     } finally {
         KeycloakModelUtils.runJobInTransaction(factory,
                                innerSession -> /* run code that releases the lock *\/)
     }
      Type Parameters:
      V - Type of object returned by the task
      Parameters:
      lockName - Identifier used for acquiring lock. Can be any non-null string.
      task - The task that will be executed under the acquired lock
      timeToWaitForLock - Duration this method waits until it gives up acquiring the lock. If null, each implementation should provide some default duration, for example, using a configuration option.
      Returns:
      Value returned by the task
      Throws:
      LockAcquiringTimeoutException - When the method waits for timeToWaitForLock duration and the lock is still not available to acquire.
      NullPointerException - When lockName is null.

    • forceReleaseAllLocks

      void forceReleaseAllLocks()
      Releases all locks acquired by this GlobalLockProvider.

      This method unlocks all existing locks acquired by this provider regardless of the thread or Keycloak instance that originally acquired them.