Skip to content

Failure handling

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

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.

THROW (default)

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.

SKIP

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

HANDLER

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.

Both annotations on one method

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.

Redis errors

A Redis error is never a "not acquired" outcome. The Redisson exception propagates unchanged from the annotated method, and onFailure does not apply.

Related limitations

Clone this wiki locally