Skip to content

With other Spring annotations

Garvit Joshi edited this page Nov 14, 2026 · 4 revisions

Spring applies annotations such as @Transactional through advice, code that runs around the method. When a method has several of them, the advice with the lower order runs first and wraps the rest. Locksmith's advice runs at order Ordered.LOWEST_PRECEDENCE - 1:

  • After Spring Security's method checks, such as @PreAuthorize and @Secured, so a call they deny never reaches Redis.
  • Before @Transactional and @Cacheable at their default order, so a transaction that starts at the locked method commits before the lock is released. Leave @Transactional at its default order: an order below LOWEST_PRECEDENCE - 1 puts the transaction outside the lock, and the lock is then released before the commit.
  • @Async, and Spring Framework's @Retryable and @ConcurrencyLimit, run outside Locksmith at their default order, so each retry takes the lock again. An order on @EnableAsync or @EnableResilientMethods that has Spring apply them first, such as Ordered.HIGHEST_PRECEDENCE, puts them inside Locksmith instead: one lock is then held across all the retries, and an @Async method's body runs after the lock is released. Leave both at their default order.

Transactions

A transaction the caller already started is not covered. The locked method joins it, and the lock is released when the method returns, before the caller commits; in that gap another instance can take the lock and read data that is not committed yet. Put @Transactional on the locked method itself, or on a method it calls, not only on its caller. If a caller may already hold a transaction, use @Transactional(propagation = Propagation.REQUIRES_NEW) on the locked method: its own transaction then commits before the unlock, and its changes stay committed even if the caller's transaction later rolls back.

Caching

@Cacheable does not skip the lock. The cache runs inside the lock, so every call takes the lock, a cache hit included. With the default try-once, two callers that hit the cache for one key at the same moment collide, and one of them gets LockNotAcquiredException: in a test, 1,760 of 2,000 concurrent hits on a cached key failed. To serve cache hits without the lock, put @Cacheable on a method of another bean that calls the locked method.

@Async and methods that return a future

A method that returns a future must be @Async, on the method or on the bean's class, and declare Future or CompletableFuture; otherwise startup fails. At @EnableAsync's default order, Spring's @Async interceptor runs first, so Locksmith runs on the worker thread, and the lock and permit cover the whole method body:

@Async
@DistributedLock(key = "order:#{#orderId}", waitTime = "5s")
public CompletableFuture<Receipt> process(String orderId) {
    return CompletableFuture.completedFuture(Receipt.from(client.send(orderId)));
}

The lock is released when the method body returns. Work the body starts but does not wait for, such as a future it returns before that future completes, runs on without the lock; when the body returns such a future, Locksmith logs an ERROR. With SKIP, the caller's future completes with null. With an order on @EnableAsync that has Spring apply @Async first, such as Ordered.HIGHEST_PRECEDENCE, Locksmith runs outside it instead: it releases the lock as soon as the @Async proxy hands back its future, before the body runs, and logs that ERROR on every call.

Future and CompletableFuture are the only future types Spring's @Async returns: it fails every call of a method declared to return CompletionStage, and a CompletableFuture subclass fails with a ClassCastException after the method has run. For the same reason, an annotated @Async method that returns anything but void, Kotlin Unit, Future or CompletableFuture fails startup. @Async on the bean's class, on a superclass or on an interface of it counts for every method the bean inherits, as it does for Spring.

Spring MVC's own async return types are a different case. A locked handler that returns Callable, WebAsyncTask, DeferredResult, StreamingResponseBody or an emitter such as SseEmitter fails startup, with or without @Async: Spring MVC runs that work after the handler returns, when the lock is already released. Put the annotation on the method that does the work, such as a service method called inside the Callable. See Return types that are rejected.

@PostAuthorize and @PostFilter

@PostAuthorize and @PostFilter see what SKIP or HANDLER returns. SKIP returns null for a collection type, which @PostFilter rejects; on such a method use HANDLER and return an empty collection.

Related limitations

Clone this wiki locally