Package com.broadleafcommerce.common.messaging.repository

Interface ResourceLockRepository<D,ID>

All Superinterfaces:
org.springframework.data.repository.Repository<D,ID>
All Known Subinterfaces:
JpaResourceLockRepository
All Known Implementing Classes:
JpaCustomizedResourceLockRepository, NoOpResourceLockRepository
@NoRepositoryBean public interface ResourceLockRepository<D,ID> extends org.springframework.data.repository.Repository<D,ID>
Repository responsible for allowing requesters to lock and unlock a resource. This prevents concurrent mutation of a resource, particularly during sandbox workflow operations. For example, a reject operation would lock a resource and prevent a promotion operation for that same resource from occurring until the completion of the reject.
Author:
Jeff Fischer

  • Method Details

    • lockResource

      String lockResource(String contextId, Class<?> type, @Nullable String optional, @Nullable String conceptKey)
      Lock a resource indefinitely based on identifying information. Will return a token representing the lock that is suitable to be passed to unlockResource(String) when the work requiring the lock is complete. If unable to acquire the lock, a ResourceLockException is thrown.
      Parameters:
      contextId - a unique id of the obtain a lock for
      type - grouping for the contextId
      optional - Optional information associated with the lock. Common values are sandboxId and status.
      conceptKey - a generally descriptive key that identifies the overall concept for which the lock is taking place
      Returns:
      The token that identifies the lock
      Throws:
      ResourceLockException - if the lock could not be acquired

    • updateState

      default boolean updateState(String token, String state)
      Update the state for the process associated with this lock
      Parameters:
      token - The lock token
      state - The new state
      Returns:
      Whether the update was successful

    • attemptTakeover

      default LockState attemptTakeover(String contextId, Class<?> type, @Nullable String conceptKey, String completionState, Duration stagnationThreshold)
      Attempt to take over a lock that has not reached a completed state. If successful, will return a token representing the lock that is suitable to be passed to unlockResource(String) when the work requiring the lock is complete. If unable to acquire the lock, a ResourceLockException is thrown.
      Parameters:
      contextId - a unique id of the obtain a lock for
      type - grouping for the contextId
      conceptKey - a generally descriptive key that identifies the overall concept for which the lock is taking place
      completionState - The status with which the process associated with the lock is considered complete. A lock without this status is a valid candidate for takeover.
      stagnationThreshold - The amount of time to pass before the process associated with the lock is considered abandoned. A lock that has surpassed this stagnation threshold is a valid candidate for takeover.
      Returns:
      The new token and last reported status information from the lock previously
      Throws:
      ResourceLockException - if the completionStatus is already met.
      FailedTakeoverException - if the takeover attempt was unsuccessful as a result of stagnationThreshold not being met. Takeover may be attempted again.

    • lockResourceTemporarily

      String lockResourceTemporarily(String contextId, Class<?> type, @Nullable String optional, @Nullable String conceptKey)
      Lock a resource temporarily based on identifying information. Will return a token representing the lock that is suitable to be passed to unlockResource(String) when the work requiring the lock is complete. If unable to acquire the lock, a ResourceLockException is thrown.
      Parameters:
      contextId - a unique id of the obtain a lock for
      type - grouping for the contextId
      optional - Optional information associated with the lock. Common values are sandboxId and status.
      conceptKey - a generally descriptive key that identifies the overall concept for which the lock is taking place
      Returns:
      The token that identifies the lock
      Throws:
      ResourceLockException - if the lock could not be acquired
      See Also:

    • lockResourceTemporarily

      String lockResourceTemporarily(String contextId, Class<?> type, @Nullable String optional, @Nullable String conceptKey, Duration stagnationThreshold)
      Lock a resource temporarily based on identifying information. Will return a token representing the lock that is suitable to be passed to unlockResource(String) when the work requiring the lock is complete. If unable to acquire the lock, a ResourceLockException is thrown.
      Parameters:
      contextId - a unique id of the obtain a lock for
      type - grouping for the contextId
      optional - Optional information associated with the lock. Common values are sandboxId and status.
      conceptKey - a generally descriptive key that identifies the overall concept for which the lock is taking place
      stagnationThreshold - how long the lock should be held
      Returns:
      The token that identifies the lock
      Throws:
      ResourceLockException - if the lock could not be acquired

    • unlockResource

      void unlockResource(String token)
      Unlock the resource so that other requesters can acquire the lock on the resource.
      Parameters:
      token - The identifying token for the lock

    • status

      LockStatus status(String token)
      Report on the status of the lock. Especially useful if the token is distributed outside of a discrete flow.
      Parameters:
      token - The identifying token for the lock
      Returns:
      The status of the lock
      Throws:
      ResourceLockException - if the lock status cannot be determined

    • doWithLock

      <V> V doWithLock(String contextId, Class<?> type, @Nullable String optional, @Nullable String conceptKey, Supplier<V> operation)
      A convenience method for lockResource(String, Class, String, String) and unlockResource(String) to obtainin a lock, perform an operation and then unlock
      Type Parameters:
      V - type returned from operation
      Parameters:
      contextId - a unique id of the obtain a lock for
      type - grouping for the contextId
      optional - Optional information associated with the lock. Common values are sandboxId and status.
      conceptKey - a generally descriptive key that identifies the overall concept for which the lock is taking place
      operation - the operation to perform within the lock
      Returns:
      the result of invoking operation

    • doWithTemporaryLock

      <V> V doWithTemporaryLock(String contextId, Class<?> type, @Nullable String optional, @Nullable String conceptKey, Supplier<V> operation)
      A convenience method for lockResource(String, Class, String, String) and unlockResource(String) to obtain a temporary lock, perform an operation and then unlock
      Type Parameters:
      V - type returned from operation
      Parameters:
      contextId - a unique id of the obtain a lock for
      type - grouping for the contextId
      optional - Optional information associated with the lock. Common values are sandboxId and status.
      conceptKey - a generally descriptive key that identifies the overall concept for which the lock is taking place
      operation - the operation to perform within the lock
      Returns:
      the result of invoking operation
      See Also:

    • doWithTemporaryLock

      <V> V doWithTemporaryLock(String contextId, Class<?> type, @Nullable String optional, @Nullable String conceptKey, Duration stagnationThreshold, Supplier<V> operation)
      A convenience method for lockResource(String, Class, String, String) and unlockResource(String) to obtainin a lock, perform an operation and then unlock
      Type Parameters:
      V - type returned from operation
      Parameters:
      contextId - a unique id of the obtain a lock for
      type - grouping for the contextId
      optional - Optional information associated with the lock. Common values are sandboxId and status.
      conceptKey - a generally descriptive key that identifies the overall concept for which the lock is taking place
      stagnationThreshold - how long the lock should be held
      operation - the operation to perform within the lock
      Returns:
      the result of invoking operation

    • purgeLocks

      default void purgeLocks(Class<?> type, Duration lockTtl)
      Deletes all non-expiring locks that are out of date according to the lockTtl and have JpaResourceLock.getTypeAlias() equal to the provided type.
      Parameters:
      type - The type of lock that is to be removed
      lockTtl - How long the lock should be held. If the lock is too old, then it should be removed.

    • purgeLocks

      void purgeLocks(Set<String> lockTypes, Duration lockTtl)
      Deletes all non-expiring locks that are out of date according to the lockTtl and have JpaResourceLock.getTypeAlias() equal to the provided lockTypes.
      Parameters:
      lockTypes - The types of locks that are to be removed
      lockTtl - How long the lock should be held. If the lock is too old, then it should be removed.