Repository navigation
Failure handling
onFailure decides what an annotated method does when its lock or permit is not acquired within
waitTime, including when the waiting thread is interrupted. Its value is a policy: THROW, SKIP
or HANDLER.
The method does not run. The call throws:
| Exception | Fields | Message |
|---|---|---|
in.riido.locksmith.lock.LockNotAcquiredException |
key(), waitTime()
|
Lock [locksmith:lock:order:42] not acquired within PT5S |
in.riido.locksmith.semaphore.SemaphoreNotAcquiredException |
key(), permits(), waitTime()
|
Semaphore [locksmith:semaphore:reports] permit not acquired within PT2S (permits 5) |
key() is the full Redis key. waitTime() is the configured wait time. Both extend
in.riido.locksmith.LocksmithException, which is unchecked, as is
LocksmithConfigurationException, the third subclass.
The method does not run and returns the default of its return type:
| Return type | Value |
|---|---|
void |
nothing |
Optional |
Optional.empty() |
OptionalInt, OptionalLong, OptionalDouble
|
the empty value |
CompletableFuture |
a future already completed with null
|
Future |
null, which Spring's @Async turns into a future that yields null
|
boolean, Boolean
|
false |
byte, short, int, long, float, double, char and their boxes |
zero of that type |
| any other type | null |
The method does not run. Locksmith calls the handler bean and returns its value as-is, so return something the method's return type accepts. Anything the handler throws propagates.
@Component
public class BusyOrderHandler implements LockFailureHandler {
@Override
public Object onFailure(LockFailureContext context) {
return OrderResult.busy(context.key());
}
}
@DistributedLock(
key = "order:#{#orderId}",
onFailure = OnFailure.HANDLER,
handler = BusyOrderHandler.class)
public OrderResult process(String orderId) { ... }handler names a type, and exactly one bean of that type must exist in the application context: a
@Component, a @Bean method that returns the class, a scoped proxy, or a bean that Spring
advises, for example with @Transactional, under either proxy mode. A @Bean method that returns
the handler interface works too, unless the bean is lazy, prototype or scoped; see
Handlers in a parent context. Locksmith looks the
handler up on each failure and never instantiates it itself. handler is required with HANDLER
and not allowed with the other policies. The handler receives:
| Record | Components |
|---|---|
LockFailureContext |
key (full Redis key), method, args, waitTime
|
SemaphoreFailureContext |
key (full Redis key), permits, method, args, waitTime
|
For a semaphore, implement SemaphoreFailureHandler the same way.
Locksmith takes the permit first, then the lock, and releases them in reverse order: lock first,
then permit. So a caller never holds the lock while it waits in line for a permit. If no permit is
acquired, the semaphore's onFailure applies. If the permit is acquired but the lock is not, the
permit is released first, and then the lock's onFailure applies; a lock handler therefore runs
without holding the permit.
A Redis error is never a "not acquired" outcome. The Redisson exception propagates unchanged from the
annotated method, and onFailure does not apply.