lock4j Documentation

lock4j provides several extension points:

1. Custom Executor: Implement your own lock executor and specify it in the @Lock4j(executor = ...) annotation. Ensure the implementation is registered as a Spring Bean.

2. Custom Lock Key Builder: Extend com.baomidou.lock.DefaultLockKeyBuilder and override buildKey to change how lock keys are generated.

3. Custom Lock Failure Strategy: Implement the LockFailureStrategy interface and override onLockFailure to define custom behavior when a lock cannot be acquired. The default is com.baomidou.lock.DefaultLockFailureStrategy.

// Custom Key Builder
@Component
public class MyLockKeyBuilder extends DefaultLockKeyBuilder {
    @Override
    public String buildKey(MethodInvocation invocation, String[] definitionKeys) {
        String key = super.buildKey(invocation, definitionKeys);
        // custom logic
        return key;
    }
}

// Custom Failure Strategy
@Component
public class MyLockFailureStrategy implements LockFailureStrategy {
    @Override
    public void onLockFailure(String key, long acquireTimeout, int acquireCount) {
        // custom logic
    }
}

To use lock4j, include the appropriate starter dependency for your chosen distributed lock implementation. You can include multiple starters if you need different lock implementations for different methods.

Available starters:

• lock4j-redis-template-spring-boot-starter for redisTemplate implementation.
• lock4j-redisson-spring-boot-starter for redisson implementation.
• lock4j-zookeeper-spring-boot-starter for zookeeper implementation.

<dependencies>
    <!-- If using redisTemplate as the underlying distributed lock -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>lock4j-redis-template-spring-boot-starter</artifactId>
        <version>${latest.version}</version>
    </dependency>
    <!-- If using redisson as the underlying distributed lock -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>lock4j-redisson-spring-boot-starter</artifactId>
        <version>${latest.version}</version>
    </dependency>
    <!-- If using zookeeper as the underlying distributed lock -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>lock4j-zookeeper-spring-boot-starter</artifactId>
        <version>${latest.version}</version>
    </dependency>
</dependencies>

Apply the @Lock4j annotation to methods that require distributed locking.

Basic Usage: Uses default settings (3s acquire timeout, 30s lock expiration).

Advanced Configuration:

• keys: An array of SpEL expressions to generate the lock key (e.g., #user.id).
• expire: Lock expiration time in milliseconds (prevents deadlocks).
• acquireTimeout: Maximum time (ms) to wait in queue for the lock before failing.
• executor: Specify a specific lock executor class (e.g., RedissonLockExecutor.class).
• autoRelease: If set to false, the lock will not be automatically released, which can be used for rate limiting (e.g., allowing only one access every 5 seconds).

@Service
public class DemoService {

    // Default: 3s acquire timeout, 30s expiration
    @Lock4j
    public void simple() {
        // do something
    }

    // Custom configuration with SpEL keys
    @Lock4j(keys = {"#user.id", "#user.name"}, expire = 60000, acquireTimeout = 1000)
    public User customMethod(User user) {
        return user;
    }

    // Rate limiting: User can only access once every 5 seconds
    @Lock4j(keys = {"#user.id"}, acquireTimeout = 0, expire = 5000, autoRelease = false)
    public Boolean test(User user) {
        return "true";
    }
}

If annotation-based locking is not suitable, use LockTemplate to manually acquire and release locks.

1. Inject LockTemplate into your service.
2. Call lockTemplate.lock(key, expire, acquireTimeout, executorClass).
3. If the returned LockInfo is not null, the lock was acquired.
4. Wrap your business logic in a try-finally block and call lockTemplate.releaseLock(lockInfo) in the finally block to ensure the lock is released.

@Service
public class ProgrammaticService {
    @Autowired
    private LockTemplate lockTemplate;

    public void programmaticLock(String userId) {
        // Acquire lock: key, expire (ms), acquireTimeout (ms), executor
        final LockInfo lockInfo = lockTemplate.lock(userId, 30000L, 5000L, RedissonLockExecutor.class);
        
        if (null == lockInfo) {
            throw new RuntimeException("Business processing in progress, please try again later");
        }

        try {
            // Execute business logic
            System.out.println("Executing logic...");
        } finally {
            // Release the lock
            lockTemplate.releaseLock(lockInfo);
        }
    }
}