Installation

Installation

This guide walks you through adding Locksmith to your Spring Boot project.

Maven

Add the Locksmith starter to your pom.xml:

<dependency>
    <groupId>in.riido</groupId>
    <artifactId>locksmith-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

Locksmith is available on Maven Central.

Required Dependencies

Locksmith requires Redisson and AspectJ. Add these to your project:

<dependency>
    <groupId>org.redisson</groupId>
    <artifactId>redisson</artifactId>
    <version>4.3.0</version>
</dependency>

<dependency>
    <groupId>org.aspectj</groupId>
    <artifactId>aspectjweaver</artifactId>
</dependency>

Note: AspectJ version is managed by Spring Boot's dependency management, so you don't need to specify a version.

Gradle

For Gradle projects, add to your build.gradle:

implementation 'in.riido:locksmith-spring-boot-starter:3.0.3'
implementation 'org.redisson:redisson:4.3.0'
implementation 'org.aspectj:aspectjweaver'

Or in Kotlin DSL (build.gradle.kts):

implementation("in.riido:locksmith-spring-boot-starter:3.0.3")
implementation("org.redisson:redisson:4.3.0")
implementation("org.aspectj:aspectjweaver")

Complete pom.xml Example

Here's a complete example with all dependencies:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.0.3</version>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>my-app</artifactId>
    <version>1.0.0</version>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <!-- Spring Boot Starter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>

        <!-- Locksmith -->
        <dependency>
            <groupId>in.riido</groupId>
            <artifactId>locksmith-spring-boot-starter</artifactId>
            <version>3.0.3</version>
        </dependency>

        <!-- Redisson (required) -->
        <dependency>
            <groupId>org.redisson</groupId>
            <artifactId>redisson</artifactId>
            <version>4.3.0</version>
        </dependency>

        <!-- AspectJ (required) -->
        <dependency>
            <groupId>org.aspectj</groupId>
            <artifactId>aspectjweaver</artifactId>
        </dependency>
    </dependencies>
</project>

Verify Installation

After adding dependencies, verify the installation by checking that auto-configuration works:

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

When you start your application, you should see in the logs:

INFO  Initializing locksmith lock aspect with Spring Boot 4.0.3 and Redisson 4.3.0 - Lock Properties: LockProperties[enabled=true, leaseTime=PT10M, ...], Metrics: disabled
INFO  Initializing locksmith semaphore aspect with Spring Boot 4.0.3 and Redisson 4.3.0 - Semaphore Properties: SemaphoreProperties[enabled=true, leaseTime=PT5M, ...], Metrics: disabled
INFO  Initializing locksmith rate limit aspect with Spring Boot 4.0.3 and Redisson 4.3.0 - Rate Limit Properties: RateLimitProperties[enabled=true, ...], Metrics: disabled

Compatibility Matrix

Locksmith	Spring Boot	Java	Redisson
3.0.x	4.0.x	17+	4.3.x+
2.1.x	4.0.x	17+	4.0.x+
2.0.x	4.0.x	17+	4.0.x
1.4.x	4.0.x	17+	4.0.x
1.3.x	4.0.x	17+	4.0.x

Migration from v2.x to v3.0

If upgrading from Locksmith v2.x, note these changes:

1. Redisson 4.3.0 required — Update your Redisson dependency from 4.0.x/4.1.x/4.2.x to 4.3.0+.
2. New @RateLimit annotation — v3.0.0 adds distributed rate limiting. No action needed unless you want to use it.
3. New locksmith.rate-limit.* properties — A new configuration namespace is available for rate limiting defaults. All properties are optional and have sensible defaults.

Add to your configuration (optional):

locksmith:
  rate-limit:
    enabled: true           # Enable/disable rate limit aspect and template
    wait-time: 60s          # Default wait time for WAIT_AND_SKIP mode
    key-prefix: "ratelimit:" # Prefix for all rate limit keys in Redis
    debug: false            # Enable debug logging
    metrics-enabled: false  # Enable Micrometer metrics

Migration from v1.x to v2.0

If upgrading from Locksmith v1.x, note these configuration changes:

Before (v1.x):

locksmith:
  lease-time: 10m
  wait-time: 60s
  key-prefix: "lock:"

After (v2.0):

locksmith:
  lock:
    lease-time: 10m
    wait-time: 60s
    key-prefix: "lock:"
  semaphore:
    lease-time: 5m
    wait-time: 60s
    key-prefix: "semaphore:"

See Configuration for complete details.

Next Steps

1. Configure Redis connection
2. Add your first distributed lock
3. Add your first distributed semaphore
4. Add rate limiting