Interface IdempotencyRepository

All Known Implementing Classes:
CaffeineIdempotencyRepository, JdbcIdempotencyRepository, RedisIdempotencyRepository
public interface IdempotencyRepository
Service Provider Interface for pluggable infrastructure storage.

  • Method Details

    • acquireOrGet

      Optional<IdempotencyRecord> acquireOrGet(String idempotencyKey)
      Atomically attempts to save a new record with the state STARTED. If the record already exists and is in a COMPLETED state, it is returned. If a record is in a STARTED state and has not expired, this method should throw an IdempotencyConflictException. If a record is in a STARTED state and has expired, a new record is created.
      Parameters:
      idempotencyKey - The unique key for the request.
      Returns:
      An optional containing the existing record if it's completed, or an empty optional if a new lock was acquired.
      Throws:
      IdempotencyConflictException - if a conflicting, non-expired request is in progress.

    • acquireOrGet

      default Optional<IdempotencyRecord> acquireOrGet(String idempotencyKey, String requestHash)
      Atomically attempts to save a new record with the state STARTED, verifying the request hash. If the record already exists but the request hashes do not match, an IdempotencyMismatchException is thrown.
      Parameters:
      idempotencyKey - The unique key for the request.
      requestHash - The hash of the request payload to ensure the key is not reused for a different payload.
      Returns:
      An optional containing the existing record if it's completed, or an empty optional if a new lock was acquired.
      Throws:
      IdempotencyConflictException - if a conflicting, non-expired request is in progress.
      IdempotencyMismatchException - if the key exists but the request hashes do not match.

    • saveSuccess

      void saveSuccess(String idempotencyKey, IdempotencyResponse response)
      Updates an existing record with a successful payload and sets the state to COMPLETED.
      Parameters:
      idempotencyKey - The unique key for the request.
      response - The response to save.

    • saveFailure

      void saveFailure(String idempotencyKey, String errorMessage)
      Clears the active lock and updates the state to FAILED. Usually implies the request can be retried by the client.
      Parameters:
      idempotencyKey - The unique key for the request.
      errorMessage - The error message to save.

    • get

      Optional<IdempotencyRecord> get(String idempotencyKey)
      Pure read-only check of the current record.
      Parameters:
      idempotencyKey - The unique key for the request.
      Returns:
      An optional containing the record if found, empty otherwise.

    • delete

      default void delete(String idempotencyKey)
      Removes the idempotency record associated with the given key. Useful for administrative cleanup or explicit invalidation.
      Parameters:
      idempotencyKey - The unique key to remove.

    • evictExpired

      default int evictExpired()
      Evicts all expired records from the underlying storage. Useful for periodic cleanup in persistent data stores.
      Returns:
      The number of records deleted.