Distributed Locking

RFC-44 compliant distributed locking patterns for Java services.

When to use this skill

Implementing distributed locking for scheduled jobs
Migrating from legacy locking mechanisms
Choosing between PostgreSQL and Redis locking
Migrating from Fabric8 leader election
Migrating from incubated in-repo libraries
When asked to "migrate locks to be RFC-44 compliant"

Skill Contents

Available Resources

📚 references/ - Detailed documentation

Quick Start

1. Add Dependencies (PostgreSQL)

# gradle/libs.versions.toml
[versions]
distributed-locking-api = "2.0.0"
distributed-locking-postgres-jooq = "2.0.0"

[libraries]
distributed-locking-api = { module = "com.bitso.commons:distributed-locking-api", version.ref = "distributed-locking-api" }
distributed-locking-postgres-jooq = { module = "com.bitso.commons:distributed-locking-postgres-jooq", version.ref = "distributed-locking-postgres-jooq" }

2. Create Configuration Bean

@Configuration
public class DistributedLockConfiguration {
    @Bean
    DistributedLockManager<Long> distributedLockManager(
            @Qualifier("write-dslcontext") DSLContext dslContext) {
        return new JooqPostgresSessionDistributedLockManager(dslContext);
    }
}

3. Use in Scheduled Jobs

@Scheduled(cron = "${job.cron:-}", zone = "UTC")
public void scheduledJob() {
    try (var lock = distributedLockManager.tryLock("job-lock")) {
        if (!lock.acquired()) {
            log.info("Job already running on another instance");
            return;
        }
        doWork();
    }
}

Implementation Options

RFC-44 supports two valid locking implementations:

Implementation	When to Use
PostgreSQL Advisory Locks (Default)	Services with PostgreSQL available
Redis Locking (Allowed)	Services without PostgreSQL, or with justified Redis use case

Important: Redis-based locking is NOT deprecated. It is explicitly supported per RFC-44.

Common Patterns

Try-with-resources Pattern

try (var lock = distributedLockManager.tryLock("lock-key")) {
    if (!lock.acquired()) {
        return;
    }
    executeTask();
}

Vavr Pattern

Try.withResources(() -> distributedLockManager.tryLock("lock-key"))
    .of(lock -> Option.of(lock)
        .filter(DistributedLock::acquired)
        .onEmpty(() -> log.info("Lock not acquired"))
        .peek(l -> doWork()));

References

Reference	Description
references/migration-workflow.md	Step-by-step migration guide
references/lock-patterns.md	RFC-44 lock patterns
references/redis-integration.md	Redis-based locking setup
references/troubleshooting.md	Common issues and solutions

Related Rules

.cursor/rules/java-distributed-locking-rfc44.mdc - Full RFC-44 reference

Related Skills

Skill	Purpose
gradle-standards	Dependency configuration
java-testing	Testing lock mechanisms